Diagrams
Compare diagrams
Say what changed between two versions of a diagram.
POST
/v1/diagrams/compareTL;DR
| Question | Answer |
|---|---|
| What does it do? | Say what changed between two versions of a diagram. |
| Which tool does the same? | compare_diagrams |
| What does it take? | A JSON body of type CompareDiagramsInput. |
| What does it return? | Status 200 with a body of type CompareDiagramsResponse. |
| 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
Each side is diagram source, the text of a Plotwork SVG that carries its source, or a hosted link on the picture hosts. Answers with every statement added, removed, renamed, moved to another block, or changed, matched by id rather than by line, with counts, a plain-language summary for a pull request review, and with markdown true a block ready to paste as a comment. A side that gives no source is an answer, not an error. Lays nothing out.
Request body
The body has the type CompareDiagramsInput.
| Field | Type | Required | Description |
|---|---|---|---|
before | string | yes | The old diagram: source, the text of a Plotwork SVG that carries its source, or a cdn.plotwork.dev link. at least 1 character; at most 1000000 characters. |
after | string | yes | The new diagram, in any of the same three forms. at least 1 character; at most 1000000 characters. |
markdown | boolean | no | Also return a Markdown block ready to paste as a pull request comment. default false. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The changes, their counts, and the summary. | CompareDiagramsResponse |
| 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 CompareDiagramsResponse.
| Field | Type | Required | Description |
|---|---|---|---|
same | boolean | yes | |
before | object | yes | |
before.from | "source" | "svg" | "url" | yes | |
before.read | boolean | yes | False when no source could be read from it; message says why. |
before.kind | string | null | yes | A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, or swimlane today. Later versions add kinds, so expect others. |
before.valid | boolean | yes | |
before.message | string | null | yes | |
after | object | yes | |
after.from | "source" | "svg" | "url" | yes | |
after.read | boolean | yes | False when no source could be read from it; message says why. |
after.kind | string | null | yes | A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, or swimlane today. Later versions add kinds, so expect others. |
after.valid | boolean | yes | |
after.message | string | null | yes | |
counts | object | yes | |
counts.added | integer | yes | |
counts.removed | integer | yes | |
counts.renamed | integer | yes | |
counts.moved | integer | yes | |
counts.changed | integer | yes | |
changes | object[] | yes | |
changes[].change | "added" | "removed" | "renamed" | "moved" | "changed" | yes | |
changes[].subject | "header" | "node" | "group" | "edge" | "row" | "series" | "line" | yes | |
changes[].name | string | yes | The id, the label in quotes, or for an edge its ends. |
changes[].line | integer | null | yes | The line in after, or in before for a removal. |
changes[].detail | string | yes | |
truncated | boolean | yes | True when more changes were found than are listed; counts covers all of them. |
summary | string | yes | The changes in plain words, for a pull request review. |
markdown | string | null | yes | |
next | string | yes |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
compare_diagrams | The same operation as an MCP tool |
| Tool reference | The operations as callable tools |