Diagrams
Convert Mermaid
Convert one Mermaid diagram.
POST
/v1/diagrams/convert-mermaidTL;DR
| Question | Answer |
|---|---|
| What does it do? | Convert one Mermaid diagram. |
| Which tool does the same? | convert_mermaid |
| What does it take? | A JSON body of type ConvertMermaidInput. |
| What does it return? | Status 200 with a body of type ConvertMermaidResponse. |
| What can go wrong? | 400 the body failed schema validation; 401 the api key is missing or not valid; 403 the account is on the free plan, which does not include the rest drawing and checking routes (plan.rest_not_included); 413 the body is larger than the size cap; 429 too many requests. Every failure uses the one error envelope. |
What it does
Converts one Mermaid flowchart, sequence, ER, git, Gantt, class, state, timeline, journey, mind map, treemap, pie, quadrant, C4, sankey, XY chart, or tree view diagram to Plotwork source and validates the result. The answer carries every dropped or changed construct as a diagnostic with a hint, the Plotwork validation with icon and group-type suggestions, the outline, and, when render is true, the SVG for each requested theme. A Mermaid diagram that cannot be read is a normal 200 result with ok false and nothing converted. Prefer this route over converting by hand and then calling the validate, outline, and render routes. To convert every Mermaid fence in a document at once, use the Markdown sync route with convertMermaid set.
Request body
The body has the type ConvertMermaidInput.
| Field | Type | Required | Description |
|---|---|---|---|
source | string | yes | One Mermaid diagram: a flowchart or graph, sequenceDiagram, erDiagram, gitGraph, gantt, classDiagram, stateDiagram, timeline, journey, mindmap, treemap-beta or treemap, pie, quadrantChart, C4Context or C4Container or C4Component or C4Dynamic or C4Deployment, sankey-beta or sankey, xychart-beta or xychart, or treeView-beta or treeView. Front matter and %%{init}%% directives are allowed and are dropped. Send the text inside a mermaid fence, without the fence. at least 1 character; at most 50000 characters. |
lenient | boolean | no | false (the default): a line that cannot be read stops the conversion, so nothing is converted with a line missing. true: such a line is skipped with a warning and the rest is converted. default false. |
render | boolean | no | Also draw the converted diagram, in the color schemes themes names. default false. |
themes | "light" | "dark" | "both" | no | light, dark, or both (the default): the light picture and the dark one a dark page needs. default "both". |
detail | "summary" | "full" | no | summary (the default), or full: the whole outline, and the source embedded in each SVG. default "summary". |
svg | "auto" | "always" | "never" | no | auto (the default) returns the SVGs, but over MCP leaves them out when the answer would be too big for a client (picturesOmitted). always returns them at any size. never draws nothing, which is cheaper. The HTTP API treats auto as always. default "auto". |
embedSource | boolean | no | Write the source into each SVG so read_diagram can give it back. Set it when you save the SVG in a repository or publish it to edit later; anyone with the file or link can then read the source. default false. |
settings | object | no | The repo's plotwork.config.json, if any. Schema: https://docs.plotwork.dev/schemas/plotwork.config.json (opens in a new tab). |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The converted source and its diagnostics. | ConvertMermaidResponse |
| 400 | The body failed schema validation. | ErrorResponse |
| 401 | The API key is missing or not valid. | ErrorResponse |
| 403 | The account is on the Free plan, which does not include the REST drawing and checking routes (plan.rest_not_included). | ErrorResponse |
| 413 | The body is larger than the size cap. | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
Response body
A 200 answer has the type ConvertMermaidResponse.
| Field | Type | Required | Description |
|---|---|---|---|
ok | boolean | yes | True when source is valid Plotwork source. False means nothing was converted and source is empty: read diagnostics. |
kind | string | null | yes | The Plotwork kind the diagram became, or null when it could not be converted. |
mermaidType | string | null | yes | The Mermaid diagram type read from the first line, such as flowchart or sequenceDiagram; null when none was found. |
source | string | yes | The Plotwork source, or an empty string when nothing could be converted. |
diagnostics | Diagnostic[] | yes | Everything dropped, changed, or wrong, with a hint that says what to do. Codes start with M. Lines and columns point into the Mermaid you sent. M1xx codes are errors that stop the conversion; M2xx codes are warnings and the conversion went on. |
diagnostics[].code | "E100" | "E101" | "E110" | "E111" | "E120" | "E121" | "E122" | "E123" | "E124" | "E125" | "E130" | "E131" | "E132" | "E133" | "E134" | "E135" | "E136" | "E137" | "E138" | "E139" | "E140" | "W200" | "W201" | "W202" | "W203" | "W204" | "W205" | "W206" | "W207" | "W500" | "M100" | "M101" | "M102" | "M103" | "M104" | "M110" | "M200" | "M201" | "M202" | "M203" | "M204" | "M205" | "M206" | "M207" | "M208" | "M209" | "M210" | "M211" | "M212" | "M213" | "M214" | "M215" | "M216" | "M217" | "M218" | "E300" | "E301" | "E302" | "E303" | "E304" | "W300" | "W301" | "W302" | "W303" | "M120" | "M220" | "M221" | "M222" | "E340" | "E341" | "E342" | "E343" | "E344" | "E345" | "W320" | "W321" | "W322" | "W323" | "M240" | "M241" | "M242" | "E360" | "E361" | "E362" | "E363" | "E364" | "E365" | "E366" | "E367" | "W330" | "W331" | "W332" | "W333" | "W334" | "M250" | "M251" | "E400" | "E401" | "E402" | "E403" | "W350" | "W351" | "W352" | "W353" | "M270" | "M271" | "E420" | "E421" | "E422" | "E423" | "E424" | "W360" | "W361" | "W362" | "W363" | "W364" | "M180" | "M280" | "M281" | "M282" | "E320" | "E321" | "E322" | "E323" | "E324" | "E325" | "E326" | "E327" | "E328" | "E329" | "E330" | "W310" | "W311" | "W312" | "W313" | "W314" | "M130" | "M131" | "M132" | "M230" | "M231" | "M232" | "M233" | "M234" | "M235" | "M236" | "M237" | "M238" | "E380" | "E381" | "E382" | "E383" | "W340" | "W341" | "W342" | "W343" | "M260" | "I100" | "I101" | "I102" | "I103" | "I104" | "I105" | "I200" | "I201" | "I202" | "I203" | "I204" | "I206" | "R100" | "R101" | "R200" | "R201" | "R202" | "R203" | "R204" | "R205" | "R206" | "R207" | "S100" | "S200" | "S101" | "S102" | "S103" | "S104" | "S201" | "S202" | "S203" | yes | Stable code to branch on; E-codes are errors, W-codes are warnings. |
diagnostics[].severity | "error" | "warning" | yes | Errors stop rendering; warnings never do. |
diagnostics[].message | string | yes | What is wrong, in one sentence. |
diagnostics[].line | integer | yes | 1-based line in the submitted source. minimum 1. |
diagnostics[].column | integer | yes | 1-based column in that line. minimum 1. |
diagnostics[].length | integer | yes | Number of characters the problem covers. minimum 1. |
diagnostics[].hint | string | null | yes | A concrete suggestion for fixing it, or null. |
stats | object | yes | |
stats.nodes | integer | yes | Flow nodes written. |
stats.edges | integer | yes | Flow edges written. |
stats.groups | integer | yes | Flow groups written. |
stats.actors | integer | yes | Sequence participants written. |
stats.messages | integer | yes | Sequence messages written. |
stats.tables | integer | yes | Schema tables written. |
stats.columns | integer | yes | Schema columns written. |
stats.relations | integer | yes | Schema relations written. |
stats.dropped | integer | yes | Warnings about constructs that were dropped: styling, links, activations, and so on. |
stats.renamed | integer | yes | Ids that were not valid Plotwork ids and were renamed. |
validation | object | null | yes | The Plotwork validator run on source; null when nothing was converted. |
validation.valid | boolean | yes | True when the converted source has no Plotwork errors. It always is when ok is true. |
validation.errors | Diagnostic[] | yes | Plotwork errors in the converted source. Lines and columns point into source, not into the Mermaid. |
validation.errors[].code | "E100" | "E101" | "E110" | "E111" | "E120" | "E121" | "E122" | "E123" | "E124" | "E125" | "E130" | "E131" | "E132" | "E133" | "E134" | "E135" | "E136" | "E137" | "E138" | "E139" | "E140" | "W200" | "W201" | "W202" | "W203" | "W204" | "W205" | "W206" | "W207" | "W500" | "M100" | "M101" | "M102" | "M103" | "M104" | "M110" | "M200" | "M201" | "M202" | "M203" | "M204" | "M205" | "M206" | "M207" | "M208" | "M209" | "M210" | "M211" | "M212" | "M213" | "M214" | "M215" | "M216" | "M217" | "M218" | "E300" | "E301" | "E302" | "E303" | "E304" | "W300" | "W301" | "W302" | "W303" | "M120" | "M220" | "M221" | "M222" | "E340" | "E341" | "E342" | "E343" | "E344" | "E345" | "W320" | "W321" | "W322" | "W323" | "M240" | "M241" | "M242" | "E360" | "E361" | "E362" | "E363" | "E364" | "E365" | "E366" | "E367" | "W330" | "W331" | "W332" | "W333" | "W334" | "M250" | "M251" | "E400" | "E401" | "E402" | "E403" | "W350" | "W351" | "W352" | "W353" | "M270" | "M271" | "E420" | "E421" | "E422" | "E423" | "E424" | "W360" | "W361" | "W362" | "W363" | "W364" | "M180" | "M280" | "M281" | "M282" | "E320" | "E321" | "E322" | "E323" | "E324" | "E325" | "E326" | "E327" | "E328" | "E329" | "E330" | "W310" | "W311" | "W312" | "W313" | "W314" | "M130" | "M131" | "M132" | "M230" | "M231" | "M232" | "M233" | "M234" | "M235" | "M236" | "M237" | "M238" | "E380" | "E381" | "E382" | "E383" | "W340" | "W341" | "W342" | "W343" | "M260" | "I100" | "I101" | "I102" | "I103" | "I104" | "I105" | "I200" | "I201" | "I202" | "I203" | "I204" | "I206" | "R100" | "R101" | "R200" | "R201" | "R202" | "R203" | "R204" | "R205" | "R206" | "R207" | "S100" | "S200" | "S101" | "S102" | "S103" | "S104" | "S201" | "S202" | "S203" | yes | Stable code to branch on; E-codes are errors, W-codes are warnings. |
validation.errors[].severity | "error" | "warning" | yes | Errors stop rendering; warnings never do. |
validation.errors[].message | string | yes | What is wrong, in one sentence. |
validation.errors[].line | integer | yes | 1-based line in the submitted source. minimum 1. |
validation.errors[].column | integer | yes | 1-based column in that line. minimum 1. |
validation.errors[].length | integer | yes | Number of characters the problem covers. minimum 1. |
validation.errors[].hint | string | null | yes | A concrete suggestion for fixing it, or null. |
validation.warnings | Diagnostic[] | yes | Plotwork quality warnings, including icon and group-type suggestions with the exact icon= to write. Lines and columns point into source, not into the Mermaid. |
validation.warnings[].code | "E100" | "E101" | "E110" | "E111" | "E120" | "E121" | "E122" | "E123" | "E124" | "E125" | "E130" | "E131" | "E132" | "E133" | "E134" | "E135" | "E136" | "E137" | "E138" | "E139" | "E140" | "W200" | "W201" | "W202" | "W203" | "W204" | "W205" | "W206" | "W207" | "W500" | "M100" | "M101" | "M102" | "M103" | "M104" | "M110" | "M200" | "M201" | "M202" | "M203" | "M204" | "M205" | "M206" | "M207" | "M208" | "M209" | "M210" | "M211" | "M212" | "M213" | "M214" | "M215" | "M216" | "M217" | "M218" | "E300" | "E301" | "E302" | "E303" | "E304" | "W300" | "W301" | "W302" | "W303" | "M120" | "M220" | "M221" | "M222" | "E340" | "E341" | "E342" | "E343" | "E344" | "E345" | "W320" | "W321" | "W322" | "W323" | "M240" | "M241" | "M242" | "E360" | "E361" | "E362" | "E363" | "E364" | "E365" | "E366" | "E367" | "W330" | "W331" | "W332" | "W333" | "W334" | "M250" | "M251" | "E400" | "E401" | "E402" | "E403" | "W350" | "W351" | "W352" | "W353" | "M270" | "M271" | "E420" | "E421" | "E422" | "E423" | "E424" | "W360" | "W361" | "W362" | "W363" | "W364" | "M180" | "M280" | "M281" | "M282" | "E320" | "E321" | "E322" | "E323" | "E324" | "E325" | "E326" | "E327" | "E328" | "E329" | "E330" | "W310" | "W311" | "W312" | "W313" | "W314" | "M130" | "M131" | "M132" | "M230" | "M231" | "M232" | "M233" | "M234" | "M235" | "M236" | "M237" | "M238" | "E380" | "E381" | "E382" | "E383" | "W340" | "W341" | "W342" | "W343" | "M260" | "I100" | "I101" | "I102" | "I103" | "I104" | "I105" | "I200" | "I201" | "I202" | "I203" | "I204" | "I206" | "R100" | "R101" | "R200" | "R201" | "R202" | "R203" | "R204" | "R205" | "R206" | "R207" | "S100" | "S200" | "S101" | "S102" | "S103" | "S104" | "S201" | "S202" | "S203" | yes | Stable code to branch on; E-codes are errors, W-codes are warnings. |
validation.warnings[].severity | "error" | "warning" | yes | Errors stop rendering; warnings never do. |
validation.warnings[].message | string | yes | What is wrong, in one sentence. |
validation.warnings[].line | integer | yes | 1-based line in the submitted source. minimum 1. |
validation.warnings[].column | integer | yes | 1-based column in that line. minimum 1. |
validation.warnings[].length | integer | yes | Number of characters the problem covers. minimum 1. |
validation.warnings[].hint | string | null | yes | A concrete suggestion for fixing it, or null. |
validation.summary | string | null | yes | One-line description of the converted diagram, usable as alt text. |
validation.size | object | null | yes | Natural size of the laid-out diagram. |
validation.size.width | integer | yes | Width in px. minimum 1. |
validation.size.height | integer | yes | Height in px. minimum 1. |
quality | object | no | How clean the converted diagram looks and up to three changes that would help (see draw_diagram); absent when it is not valid. |
quality.score | integer | yes | 0 to 100; 100 is a picture with nothing to fix. The same diagram always gets the same score. minimum 0; maximum 100. |
quality.grade | "clean" | "fair" | "cluttered" | yes | clean is 85 or more, fair 60 or more, cluttered below. |
quality.measures | object | yes | What the score is made from: crossings, lineOverBox, labelOverlaps, smallestTextPx (in an 880px column), aspectRatio, emptySpace (0 to 1), longestLine (px), detour (1 is straight), the counts of boxes, lines, labels, series, and slices, and any measure the kind adds. |
quality.hints | string[] | yes | Up to three changes, the one worth most first, each naming the statement or option to edit. |
quality.line | string | yes | The grade, the score, and the first hint in one line. |
outline | string[] | yes | The converted diagram as plain text, to check it says what the Mermaid said; empty when nothing was converted. |
outlineTruncated | boolean | yes | True when the summary level cut the outline short. Call again with detail "full" to read all of it. |
renders | object[] | yes | One picture per requested color scheme, light first; empty unless render was true and the conversion is valid, when svg is never, and when every picture was left out (see picturesOmitted). |
renders[].theme | "light" | "dark" | yes | The color scheme this picture is drawn in. |
renders[].svg | string | yes | Self-contained SVG markup with an accessible title and description. |
renders[].size | Size | yes | Natural size of a rendered diagram in px. |
renders[].size.width | integer | yes | Width in px. minimum 1. |
renders[].size.height | integer | yes | Height in px. minimum 1. |
picturesOmitted | object | no | Present only when pictures were left out because the answer would have been too big for an AI client to read in one piece. |
picturesOmitted.themes | ("light" | "dark")[] | yes | The color schemes whose pictures were left out. |
picturesOmitted.characters | integer | yes | How many characters the pictures left out came to. |
picturesOmitted.limit | integer | yes | The most characters one answer may hold before the pictures are left out. |
picturesOmitted.why | string | yes | Why they were left out, and what to do. |
viewUrl | string | no | A link that shows a valid diagram in a browser; give it to the person who wants to look. The source is in the part after #, never sent to a server, but anyone with the link can read it. Absent when too long; next says so. |
pngUrl | string | no | The viewUrl with &download=png: opening it in a browser saves the diagram as a PNG for Slack, email, or a wiki. The PNG is drawn in the person's browser, not on a server, so it is a link to open, not an image address to embed. Absent when too long. |
svgUrl | string | no | The viewUrl with &download=svg: a person opens it to download the SVG. Not a file address for curl; use saveCommand. Absent when too long. |
saveCommand | string | no | Run in a shell to save the SVG into the repository: the CLI decodes the link locally, fetches nothing, and embeds the source. Set --out to the path; add --theme dark for dark. Absent when too long. |
next | string | yes | The next step in one sentence. |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
convert_mermaid | The same operation as an MCP tool |
| Tool reference | The operations as callable tools |