# Compare diagrams

> Page: https://docs.plotwork.dev/api/post-v1-diagrams-compare. Index of every page: https://docs.plotwork.dev/llms.txt

Say what changed between two versions of a diagram.

`POST /v1/diagrams/compare`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Say what changed between two versions of a diagram. |
| Which tool does the same? | [`compare_diagrams`](https://docs.plotwork.dev/mcp/tools/compare-diagrams.md) |
| What does it take? | A JSON body of type [`CompareDiagramsInput`](https://docs.plotwork.dev/api/schemas.md#comparediagramsinput). |
| What does it return? | Status 200 with a body of type [`CompareDiagramsResponse`](https://docs.plotwork.dev/api/schemas.md#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`](https://docs.plotwork.dev/api/schemas.md#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`](https://docs.plotwork.dev/api/schemas.md#comparediagramsresponse) |
| 400 | The body failed schema validation. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 401 | The API key is missing or not valid. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 403 | The account is on the Free plan, which does not include the REST drawing and checking routes (plan.rest_not_included). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 413 | The body is larger than the size cap. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`CompareDiagramsResponse`](https://docs.plotwork.dev/api/schemas.md#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](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [`compare_diagrams`](https://docs.plotwork.dev/mcp/tools/compare-diagrams.md) | The same operation as an MCP tool |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |