Diagrams
Embed diagram
Write a snippet that shows a picture with the viewer.
POST
/v1/diagrams/embedTL;DR
| Question | Answer |
|---|---|
| What does it do? | Write a snippet that shows a picture with the viewer. |
| Which tool does the same? | embed_diagram |
| What does it take? | A JSON body of type EmbedDiagramInput. |
| What does it return? | Status 200 with a body of type EmbedDiagramResponse. |
| 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 a hosted link (/d/, a stable link /l/, or an organisation embed link /o/), the text of a Plotwork SVG a site serves, or both, and answers with the line that installs @plotwork.official/viewer and an HTML or React snippet that shows the picture. live is kept for a stable or organisation embed link, and pin adds the SHA-256 fingerprint of the SVG text; a choice that cannot apply is left out and said in notes. A link that is not a hosted picture is a 200 answer with ok false and a hint. Nothing is fetched or laid out.
Request body
The body has the type EmbedDiagramInput.
| Field | Type | Required | Description |
|---|---|---|---|
url | string | no | A hosted picture (/d/), stable link (/l/) or organisation embed link (/o/) on cdn.plotwork.dev. Never fetched. at least 1 character; at most 200 characters. |
svg | string | no | The text of a Plotwork SVG; needed to pin. at least 1 character; at most 1000000 characters. |
path | string | no | Where the page serves svg from, when there is no url. at least 1 character; at most 500 characters. |
format | "html" | "react" | no | html for any page, react for React. default "html". |
live | boolean | no | Follow new versions: /l/ and /o/ links only. default false. |
pin | boolean | no | Show only exactly this picture: needs svg. default false. |
label | string | no | What the diagram shows, for a screen reader. at most 200 characters. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The snippet, the install line, the fingerprint and the notes. | EmbedDiagramResponse |
| 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 EmbedDiagramResponse.
| Field | Type | Required | Description |
|---|---|---|---|
ok | boolean | yes | False when the url is not a hosted picture or the svg is not an SVG; message and hint say why. |
snippet | string | null | yes | The code to paste into the page or component, or null when ok is false. |
install | string | yes | The command that installs the viewer. |
src | string | null | yes | The address the snippet loads the picture from. |
linkKind | "picture" | "stable" | "organisation" | null | yes | picture (/d/), stable (/l/), organisation (/o/), or null for a file the page serves. |
fingerprint | string | null | yes | sha256- |
live | boolean | yes | True when the snippet carries live. |
pinned | boolean | yes | True when the snippet carries fingerprint. |
notes | string[] | yes | Each choice left out and why, and what to know about the link. |
message | string | yes | What happened, in one sentence. |
hint | string | null | yes | What to send instead, when ok is false. |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
embed_diagram | The same operation as an MCP tool |
| Tool reference | The operations as callable tools |