Diagrams
Import source
Turn a file of another format into a diagram.
POST
/v1/importTL;DR
| Question | Answer |
|---|---|
| What does it do? | Turn a file of another format into a diagram. |
| Which tool does the same? | import_source |
| What does it take? | A JSON body of type ImportSourceInput. |
| What does it return? | Status 200 with a body of type ImportSourceResponse. |
| 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
Takes the text of a file and its format: SQL DDL, Prisma, or Drizzle becomes a schema; an OpenAPI 3 document becomes a matrix of who may call each endpoint, or one operation as a sequence; Terraform, Bicep, an ARM template, Pulumi, CloudFormation, the AWS CDK, Docker Compose, Kubernetes manifests, Helm, Kustomize, a Backstage catalog, AsyncAPI documents, or a GitHub Actions, GitLab CI/CD, or Azure Pipelines pipeline becomes a flow with icons and frames; a Structurizr workspace becomes a C4 diagram of one view; CSV or JSON data becomes the chart its shape suits; tree output or a list of paths becomes a tree; a git log becomes a git graph or a timeline. Answers with the Plotwork source, a diagnostic for everything left out with its line and column in the file, the validation, and an outline. A file that cannot be read is a normal 200 result with ok false. It runs no code and fetches nothing, and the text is not stored.
Request body
The body has the type ImportSourceInput.
| Field | Type | Required | Description |
|---|---|---|---|
format | "sql" | "prisma" | "drizzle" | "openapi" | "terraform" | "terraform-plan" | "bicep" | "arm" | "pulumi" | "cloudformation" | "cdk" | "compose" | "kubernetes" | "helm" | "kustomize" | "backstage" | "structurizr" | "asyncapi" | "github-actions" | "gitlab-ci" | "azure-pipelines" | "csv" | "json" | "tree" | "git-log" | yes | What the text is; get_diagram_syntax with topic import-formats describes each. |
text | string | no | The file content, as text. Send text or files, not both. |
files | object[] | no | The files of a folder, for a format that spans files; the others read the first. |
files[].path | string | yes | The file path, such as infra/network.tf; diagnostics name it. at least 1 character; at most 300 characters. |
files[].text | string | yes | The file content, as text. |
title | string | no | The diagram title; taken from the file when left out. at most 200 characters. |
partsPage | integer | no | Which page of parts to return when a split import has more than 24 diagrams: 1 (default) is the first 24. minimum 1; maximum 100000. |
options | object | no | default {}. |
options.view | "endpoints" | "map" | "sequence" | "git" | "timeline" | "context" | "container" | "component" | no | The picture of a format drawn several ways. |
options.operationId | string | no | openapi sequence: the operation. at most 200 characters. |
options.chart | "auto" | "xychart" | "pie" | "sankey" | "treemap" | "matrix" | no | csv, json: the chart; auto picks. |
options.tables | string[] | no | Tables to draw, by name or prefix*. |
options.paths | string[] | no | openapi: path prefixes to read. |
options.tags | string[] | no | openapi: tags to read. |
options.varFiles | string[] | no | Variables files to apply. |
options.groupBy | "module" | "network" | "file" | "owner" | no | How things are framed; module is the default. |
options.root | string | no | The root, stack, or template of several to draw. at most 300 characters. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The imported source, its diagnostics, its check, and its outline. | ImportSourceResponse |
| 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 ImportSourceResponse.
| Field | Type | Required | Description |
|---|---|---|---|
ok | boolean | yes | True when source is valid Plotwork source. False means nothing was imported and source is empty: read diagnostics. |
kind | string | null | yes | The kind of diagram the file became, or null when nothing was imported. |
format | string | yes | The format the text was read as. |
source | string | yes | The Plotwork source, or an empty string when nothing could be imported. |
diagnostics | Diagnostic[] | yes | Everything left out, changed, or wrong, with a hint. Codes start with I and point into the text you sent: I1xx errors stopped the import, I2xx warnings did not. |
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.items | integer | yes | Boxes, tables, rows, slices, places, entries, or commits written. |
stats.links | integer | yes | Arrows, relations, messages, flows, or merges written. |
stats.groups | integer | yes | Frames, sections, or folders written. |
stats.dropped | integer | yes | Things in the file left out by a cap or because the picture has no place for them; each is in diagnostics. |
coverage | object | null | yes | How much of the file the picture shows; null when nothing was imported. When complete is false, the picture is not the whole file: say so. |
coverage.noun | string | yes | What was counted, such as resources, services, tables, or endpoints. |
coverage.total | integer | yes | Everything of that kind in the file. |
coverage.drawn | integer | yes | Drawn as a box, frame, table, row, or entry of its own. |
coverage.summarised | integer | yes | Not drawn on their own but counted on the box they belong to, such as "3 role assignments". |
coverage.omitted | integer | yes | Not in the picture at all; the diagnostics say which and why. |
coverage.complete | boolean | yes | True when nothing was omitted. |
coverage.line | string | yes | The coverage in one sentence, such as "Drawn 12 of 85 resources; 60 are counted on the boxes they belong to and 13 are left out.". |
validation | object | null | yes | The Plotwork validator run on source; null when nothing was imported. |
validation.valid | boolean | yes | True when the source has no Plotwork errors. It always is when ok is true. |
validation.errors | Diagnostic[] | yes | Plotwork errors. Lines and columns point into source. |
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, with the exact fix in each hint. Lines and columns point into source. |
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 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. |
parts | object[] | yes | When the file is too big for one readable picture, the diagrams it was split into, in order, at most 24 a page; source is the first diagram of all. Show or draw each of them. Empty when the import is one diagram. |
parts[].title | string | yes | What this diagram shows, such as one resource group or one tag of an API. |
parts[].kind | string | yes | The kind of diagram. |
parts[].source | string | yes | The Plotwork source of this diagram; draw it with draw_diagram. |
parts[].items | integer | yes | The boxes, rows, or entries it draws. |
parts[].valid | boolean | yes | True when the source has no Plotwork errors. |
parts[].warnings | Diagnostic[] | yes | Plotwork quality warnings of this diagram. Lines and columns point into its source. |
parts[].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. |
parts[].warnings[].severity | "error" | "warning" | yes | Errors stop rendering; warnings never do. |
parts[].warnings[].message | string | yes | What is wrong, in one sentence. |
parts[].warnings[].line | integer | yes | 1-based line in the submitted source. minimum 1. |
parts[].warnings[].column | integer | yes | 1-based column in that line. minimum 1. |
parts[].warnings[].length | integer | yes | Number of characters the problem covers. minimum 1. |
parts[].warnings[].hint | string | null | yes | A concrete suggestion for fixing it, or null. |
partsTotal | integer | yes | How many diagrams the import was split into in all; 0 when it is one diagram. |
partsPage | integer | yes | The page of parts this answer holds, from 1. |
partsPages | integer | yes | How many pages of parts there are; call again with partsPage for the next one. |
outline | string[] | yes | The diagram as plain text, to check it says what the file says; empty when nothing was imported. |
outlineTruncated | boolean | yes | True when the outline was cut short at its summary length. |
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 |
import_source | The same operation as an MCP tool |
| Tool reference | The operations as callable tools |