# Embed diagram

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

Write a snippet that shows a picture with the viewer.

`POST /v1/diagrams/embed`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Write a snippet that shows a picture with the viewer. |
| Which tool does the same? | [`embed_diagram`](https://docs.plotwork.dev/mcp/tools/embed-diagram.md) |
| What does it take? | A JSON body of type [`EmbedDiagramInput`](https://docs.plotwork.dev/api/schemas.md#embeddiagraminput). |
| What does it return? | Status 200 with a body of type [`EmbedDiagramResponse`](https://docs.plotwork.dev/api/schemas.md#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`](https://docs.plotwork.dev/api/schemas.md#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`](https://docs.plotwork.dev/api/schemas.md#embeddiagramresponse) |
| 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 [`EmbedDiagramResponse`](https://docs.plotwork.dev/api/schemas.md#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-<hex> of the svg text, whether or not the snippet pins it; null without svg. |
| `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](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 |
| [`embed_diagram`](https://docs.plotwork.dev/mcp/tools/embed-diagram.md) | The same operation as an MCP tool |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |