# API reference

> Page: https://docs.plotwork.dev/api/reference. Index of every page: https://docs.plotwork.dev/llms.txt

Check, render, and describe diagrams written in a small line-oriented language (flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane). Built for AI agents: every error carries a line, column, and fix hint, and the language reference is served as data. The same operations are available as MCP tools.

## TL;DR

| Question | Answer |
|---|---|
| What format? | JSON in, JSON out. Every body is described by a schema, and each endpoint page links the ones it uses. |
| Where is the live spec? | `GET /openapi.json` returns OpenAPI 3.1; `GET /docs` serves an interactive page. |
| What does an error look like? | One envelope for every failure; see "Error envelope". A diagram with mistakes is a normal result from the validate route and a `422` from the render and outline routes. |
| Where does it run? | The hosted API is at `https://api.plotwork.dev`, and every path below is relative to that address. Calling the drawing and checking routes needs an API key and the Pro plan. |
| Which endpoints draw diagrams? | The ones under `/v1`: each serves a tool of the [tool reference](https://docs.plotwork.dev/mcp/tools.md), and its page names the tool. |

## Endpoints

130 endpoints, each with a page of its own. They are grouped by what they do.

### Diagrams

| Method | Path | What it does |
|---|---|---|
| POST | [`/v1/diagrams/draw`](https://docs.plotwork.dev/api/post-v1-diagrams-draw.md) | Check, describe, and draw a diagram. |
| POST | [`/v1/diagrams/edit`](https://docs.plotwork.dev/api/post-v1-diagrams-edit.md) | Change diagram source with small typed operations. |
| POST | [`/v1/diagrams/convert-mermaid`](https://docs.plotwork.dev/api/post-v1-diagrams-convert-mermaid.md) | Convert one Mermaid diagram. |
| POST | [`/v1/diagrams/validate`](https://docs.plotwork.dev/api/post-v1-diagrams-validate.md) | Check diagram source. |
| POST | [`/v1/diagrams/render`](https://docs.plotwork.dev/api/post-v1-diagrams-render.md) | Render diagram source to SVG. |
| POST | [`/v1/diagrams/outline`](https://docs.plotwork.dev/api/post-v1-diagrams-outline.md) | Describe diagram source as text. |
| POST | [`/v1/diagrams/read`](https://docs.plotwork.dev/api/post-v1-diagrams-read.md) | Read the source back out of a Plotwork SVG. |
| POST | [`/v1/diagrams/compare`](https://docs.plotwork.dev/api/post-v1-diagrams-compare.md) | Say what changed between two versions of a diagram. |
| POST | [`/v1/diagrams/suggest`](https://docs.plotwork.dev/api/post-v1-diagrams-suggest.md) | Choose the kind of diagram for a request. |
| POST | [`/v1/import`](https://docs.plotwork.dev/api/post-v1-import.md) | Turn a file of another format into a diagram. |

### Icons

| Method | Path | What it does |
|---|---|---|
| POST | [`/v1/icons/map`](https://docs.plotwork.dev/api/post-v1-icons-map.md) | Choose icons for many names at once. |
| GET | [`/v1/icons`](https://docs.plotwork.dev/api/get-v1-icons.md) | Find bundled icon names. |

### Markdown

| Method | Path | What it does |
|---|---|---|
| POST | [`/v1/markdown/sync`](https://docs.plotwork.dev/api/post-v1-markdown-sync.md) | Turn a document's diagram fences into pictures. |
| POST | [`/v1/markdown/plan`](https://docs.plotwork.dev/api/post-v1-markdown-plan.md) | Find the sections of a document a picture would help. |

### Patterns

| Method | Path | What it does |
|---|---|---|
| POST | [`/v1/patterns/find`](https://docs.plotwork.dev/api/post-v1-patterns-find.md) | Find a ready-made architecture diagram. |
| POST | [`/v1/patterns/get`](https://docs.plotwork.dev/api/post-v1-patterns-get.md) | Read a pattern filled for a flavour. |
| POST | [`/v1/patterns/draw`](https://docs.plotwork.dev/api/post-v1-patterns-draw.md) | Fill a pattern and draw it. |

### Vocabulary

| Method | Path | What it does |
|---|---|---|
| GET | [`/v1/vocabulary`](https://docs.plotwork.dev/api/get-v1-vocabulary.md) | Get the diagram language reference. |

### Auth

| Method | Path | What it does |
|---|---|---|
| POST | [`/auth/code`](https://docs.plotwork.dev/api/post-auth-code.md) | Email a sign-in code. |
| POST | [`/auth/verify`](https://docs.plotwork.dev/api/post-auth-verify.md) | Sign in with a code. |
| POST | [`/auth/logout`](https://docs.plotwork.dev/api/post-auth-logout.md) | Sign out. |
| POST | [`/auth/sso/discover`](https://docs.plotwork.dev/api/post-auth-sso-discover.md) | Ask whether an address signs in with single sign-on. |
| POST | [`/auth/sso/start`](https://docs.plotwork.dev/api/post-auth-sso-start.md) | Start signing in through an organisation's identity provider. |
| GET | [`/auth/sso/callback`](https://docs.plotwork.dev/api/get-auth-sso-callback.md) | Finish signing in through an identity provider. |
| GET | [`/auth/sso/saml/{org}/metadata`](https://docs.plotwork.dev/api/get-auth-sso-saml-org-metadata.md) | Read an organisation's SAML service provider metadata. |
| POST | [`/auth/sso/saml/{org}/acs`](https://docs.plotwork.dev/api/post-auth-sso-saml-org-acs.md) | Finish signing in through a SAML identity provider. |

### Keys

| Method | Path | What it does |
|---|---|---|
| GET | [`/user/me`](https://docs.plotwork.dev/api/get-user-me.md) | Read the signed-in account. |
| GET | [`/user/api-keys`](https://docs.plotwork.dev/api/get-user-api-keys.md) | List your API keys. |
| POST | [`/user/api-keys`](https://docs.plotwork.dev/api/post-user-api-keys.md) | Create an API key. |
| POST | [`/user/api-keys/{id}/reveal`](https://docs.plotwork.dev/api/post-user-api-keys-id-reveal.md) | Reveal an API key. |
| DELETE | [`/user/api-keys/{id}`](https://docs.plotwork.dev/api/delete-user-api-keys-id.md) | Revoke an API key. |
| GET | [`/user/usage`](https://docs.plotwork.dev/api/get-user-usage.md) | Read the account's usage. |

### Connections

| Method | Path | What it does |
|---|---|---|
| POST | [`/user/mcp/approve`](https://docs.plotwork.dev/api/post-user-mcp-approve.md) | Approve a request to connect an agent. |
| GET | [`/user/mcp/connections`](https://docs.plotwork.dev/api/get-user-mcp-connections.md) | List the agents you have connected. |
| DELETE | [`/user/mcp/connections/{keyId}`](https://docs.plotwork.dev/api/delete-user-mcp-connections-key-id.md) | Disconnect an agent. |

### Hosting

| Method | Path | What it does |
|---|---|---|
| POST | [`/v1/diagrams/publish`](https://docs.plotwork.dev/api/post-v1-diagrams-publish.md) | Publish a diagram and get a link. |
| GET | [`/user/diagrams`](https://docs.plotwork.dev/api/get-user-diagrams.md) | List your hosted diagrams. |
| PATCH | [`/user/diagrams/{id}`](https://docs.plotwork.dev/api/patch-user-diagrams-id.md) | File a hosted diagram in a folder. |
| DELETE | [`/user/diagrams/{id}`](https://docs.plotwork.dev/api/delete-user-diagrams-id.md) | Delete a hosted diagram. |
| PUT | [`/user/diagrams/{id}/lock`](https://docs.plotwork.dev/api/put-user-diagrams-id-lock.md) | Lock a hosted diagram. |
| DELETE | [`/user/diagrams/{id}/lock`](https://docs.plotwork.dev/api/delete-user-diagrams-id-lock.md) | Unlock a hosted diagram. |
| PUT | [`/user/diagrams/{id}/source`](https://docs.plotwork.dev/api/put-user-diagrams-id-source.md) | Save edited source over a hosted diagram. |
| GET | [`/user/diagrams/{id}/versions`](https://docs.plotwork.dev/api/get-user-diagrams-id-versions.md) | List a hosted diagram's previous versions. |
| POST | [`/user/diagrams/{id}/versions/{versionId}/restore`](https://docs.plotwork.dev/api/post-user-diagrams-id-versions-version-id-restore.md) | Restore a previous version of a hosted diagram. |
| POST | [`/user/stable-links`](https://docs.plotwork.dev/api/post-user-stable-links.md) | Point a stable link at one of your diagrams. |
| DELETE | [`/user/stable-links/{id}`](https://docs.plotwork.dev/api/delete-user-stable-links-id.md) | Delete a stable link. |
| GET | [`/oembed`](https://docs.plotwork.dev/api/get-oembed.md) | Describe a diagram link for an embedder (oEmbed). |

### Organisations

| Method | Path | What it does |
|---|---|---|
| GET | [`/orgs`](https://docs.plotwork.dev/api/get-orgs.md) | List your organisations. |
| POST | [`/orgs`](https://docs.plotwork.dev/api/post-orgs.md) | Create an organisation. |
| GET | [`/orgs/{org}`](https://docs.plotwork.dev/api/get-orgs-org.md) | Read an organisation. |
| PATCH | [`/orgs/{org}`](https://docs.plotwork.dev/api/patch-orgs-org.md) | Rename an organisation. |
| DELETE | [`/orgs/{org}`](https://docs.plotwork.dev/api/delete-orgs-org.md) | Delete an organisation. |
| GET | [`/orgs/{org}/members`](https://docs.plotwork.dev/api/get-orgs-org-members.md) | List an organisation's members. |
| PATCH | [`/orgs/{org}/members/{userId}`](https://docs.plotwork.dev/api/patch-orgs-org-members-user-id.md) | Change a member's role. |
| DELETE | [`/orgs/{org}/members/{userId}`](https://docs.plotwork.dev/api/delete-orgs-org-members-user-id.md) | Remove a member, or leave. |
| GET | [`/orgs/{org}/invites`](https://docs.plotwork.dev/api/get-orgs-org-invites.md) | List an organisation's pending invitations. |
| POST | [`/orgs/{org}/invites`](https://docs.plotwork.dev/api/post-orgs-org-invites.md) | Invite an address to an organisation. |
| DELETE | [`/orgs/{org}/invites/{id}`](https://docs.plotwork.dev/api/delete-orgs-org-invites-id.md) | Revoke an invitation. |
| POST | [`/orgs/invites/accept`](https://docs.plotwork.dev/api/post-orgs-invites-accept.md) | Accept an invitation. |
| GET | [`/orgs/{org}/diagrams`](https://docs.plotwork.dev/api/get-orgs-org-diagrams.md) | List an organisation's diagrams. |
| POST | [`/orgs/{org}/diagrams`](https://docs.plotwork.dev/api/post-orgs-org-diagrams.md) | Publish a diagram to an organisation. |
| GET | [`/orgs/{org}/diagrams/{id}/svg`](https://docs.plotwork.dev/api/get-orgs-org-diagrams-id-svg.md) | Download an organisation diagram's SVG. |
| PATCH | [`/orgs/{org}/diagrams/{id}`](https://docs.plotwork.dev/api/patch-orgs-org-diagrams-id.md) | File or rename an organisation diagram. |
| DELETE | [`/orgs/{org}/diagrams/{id}`](https://docs.plotwork.dev/api/delete-orgs-org-diagrams-id.md) | Delete an organisation diagram. |
| PUT | [`/orgs/{org}/diagrams/{id}/lock`](https://docs.plotwork.dev/api/put-orgs-org-diagrams-id-lock.md) | Lock an organisation diagram. |
| DELETE | [`/orgs/{org}/diagrams/{id}/lock`](https://docs.plotwork.dev/api/delete-orgs-org-diagrams-id-lock.md) | Unlock an organisation diagram. |
| PUT | [`/orgs/{org}/diagrams/{id}/source`](https://docs.plotwork.dev/api/put-orgs-org-diagrams-id-source.md) | Save edited source over an organisation diagram. |
| GET | [`/orgs/{org}/diagrams/{id}/versions`](https://docs.plotwork.dev/api/get-orgs-org-diagrams-id-versions.md) | List an organisation diagram's previous versions. |
| POST | [`/orgs/{org}/diagrams/{id}/versions/{versionId}/restore`](https://docs.plotwork.dev/api/post-orgs-org-diagrams-id-versions-version-id-restore.md) | Restore a previous version of an organisation diagram. |
| PUT | [`/orgs/{org}/editable`](https://docs.plotwork.dev/api/put-orgs-org-editable.md) | Keep an organisation's diagrams editable. |
| PUT | [`/orgs/{org}/publishing`](https://docs.plotwork.dev/api/put-orgs-org-publishing.md) | Choose where an organisation's members publish. |
| GET | [`/orgs/{org}/publishing/public-diagrams`](https://docs.plotwork.dev/api/get-orgs-org-publishing-public-diagrams.md) | List members' public diagrams for review. |
| POST | [`/orgs/{org}/publishing/public-diagrams/{id}/move`](https://docs.plotwork.dev/api/post-orgs-org-publishing-public-diagrams-id-move.md) | Move a member's public diagram into the library. |
| DELETE | [`/orgs/{org}/publishing/public-diagrams/{id}`](https://docs.plotwork.dev/api/delete-orgs-org-publishing-public-diagrams-id.md) | Unpublish a member's public diagram. |
| GET | [`/user/publishing`](https://docs.plotwork.dev/api/get-user-publishing.md) | Read where your publishes go. |
| PUT | [`/user/publishing`](https://docs.plotwork.dev/api/put-user-publishing.md) | Choose your default organisation for publishing. |
| GET | [`/orgs/{org}/folder-rules`](https://docs.plotwork.dev/api/get-orgs-org-folder-rules.md) | List an organisation's folder rules. |
| PUT | [`/orgs/{org}/folder-rules`](https://docs.plotwork.dev/api/put-orgs-org-folder-rules.md) | Restrict a folder. |
| DELETE | [`/orgs/{org}/folder-rules`](https://docs.plotwork.dev/api/delete-orgs-org-folder-rules.md) | Remove a folder's rule. |
| GET | [`/orgs/{org}/keys`](https://docs.plotwork.dev/api/get-orgs-org-keys.md) | List an organisation's API keys. |
| POST | [`/orgs/{org}/keys`](https://docs.plotwork.dev/api/post-orgs-org-keys.md) | Create an organisation API key. |
| POST | [`/orgs/{org}/keys/{id}/reveal`](https://docs.plotwork.dev/api/post-orgs-org-keys-id-reveal.md) | Reveal an organisation API key. |
| DELETE | [`/orgs/{org}/keys/{id}`](https://docs.plotwork.dev/api/delete-orgs-org-keys-id.md) | Revoke an organisation API key. |
| GET | [`/orgs/{org}/brand`](https://docs.plotwork.dev/api/get-orgs-org-brand.md) | Read an organisation's brand theme. |
| PUT | [`/orgs/{org}/brand`](https://docs.plotwork.dev/api/put-orgs-org-brand.md) | Save an organisation's brand theme. |
| DELETE | [`/orgs/{org}/brand`](https://docs.plotwork.dev/api/delete-orgs-org-brand.md) | Remove an organisation's brand theme. |
| POST | [`/orgs/{org}/brand/preview`](https://docs.plotwork.dev/api/post-orgs-org-brand-preview.md) | Preview brand colors. |
| GET | [`/user/brand`](https://docs.plotwork.dev/api/get-user-brand.md) | Read the brand of your own calls. |
| PUT | [`/user/brand`](https://docs.plotwork.dev/api/put-user-brand.md) | Choose the brand of your own calls. |
| GET | [`/orgs/{org}/style-rules`](https://docs.plotwork.dev/api/get-orgs-org-style-rules.md) | Read an organisation's style rules. |
| PUT | [`/orgs/{org}/style-rules`](https://docs.plotwork.dev/api/put-orgs-org-style-rules.md) | Save an organisation's style rules. |
| DELETE | [`/orgs/{org}/style-rules`](https://docs.plotwork.dev/api/delete-orgs-org-style-rules.md) | Remove an organisation's style rules. |
| GET | [`/orgs/{org}/icons`](https://docs.plotwork.dev/api/get-orgs-org-icons.md) | List an organisation's custom icons. |
| PUT | [`/orgs/{org}/icons/{name}`](https://docs.plotwork.dev/api/put-orgs-org-icons-name.md) | Upload or replace a custom icon. |
| DELETE | [`/orgs/{org}/icons/{name}`](https://docs.plotwork.dev/api/delete-orgs-org-icons-name.md) | Delete a custom icon. |
| GET | [`/orgs/{org}/icons/{name}/preview`](https://docs.plotwork.dev/api/get-orgs-org-icons-name-preview.md) | Preview a custom icon in a diagram. |
| GET | [`/orgs/{org}/avatar`](https://docs.plotwork.dev/api/get-orgs-org-avatar.md) | Read an organisation's avatar. |
| PUT | [`/orgs/{org}/avatar`](https://docs.plotwork.dev/api/put-orgs-org-avatar.md) | Upload or replace an organisation's avatar. |
| DELETE | [`/orgs/{org}/avatar`](https://docs.plotwork.dev/api/delete-orgs-org-avatar.md) | Remove an organisation's avatar. |
| POST | [`/orgs/{org}/drift/runs`](https://docs.plotwork.dev/api/post-orgs-org-drift-runs.md) | Report a drift run from CI. |
| GET | [`/orgs/{org}/drift`](https://docs.plotwork.dev/api/get-orgs-org-drift.md) | Read an organisation's drift dashboard. |
| GET | [`/orgs/{org}/audit`](https://docs.plotwork.dev/api/get-orgs-org-audit.md) | Read an organisation's audit log. |
| GET | [`/orgs/{org}/audit/export`](https://docs.plotwork.dev/api/get-orgs-org-audit-export.md) | Export an organisation's audit log. |
| GET | [`/orgs/{org}/sso`](https://docs.plotwork.dev/api/get-orgs-org-sso.md) | Read an organisation's single sign-on settings. |
| PUT | [`/orgs/{org}/sso/connection`](https://docs.plotwork.dev/api/put-orgs-org-sso-connection.md) | Set up an OpenID Connect identity provider. |
| PATCH | [`/orgs/{org}/sso/connection`](https://docs.plotwork.dev/api/patch-orgs-org-sso-connection.md) | Turn single sign-on on or off, and set Require SSO and who joins on first sign-in. |
| DELETE | [`/orgs/{org}/sso/connection`](https://docs.plotwork.dev/api/delete-orgs-org-sso-connection.md) | Remove the identity provider. |
| PUT | [`/orgs/{org}/sso/saml`](https://docs.plotwork.dev/api/put-orgs-org-sso-saml.md) | Set up a SAML identity provider. |
| POST | [`/orgs/{org}/sso/domains`](https://docs.plotwork.dev/api/post-orgs-org-sso-domains.md) | Add an email domain. |
| POST | [`/orgs/{org}/sso/domains/{domain}/verify`](https://docs.plotwork.dev/api/post-orgs-org-sso-domains-domain-verify.md) | Check a domain's DNS record. |
| DELETE | [`/orgs/{org}/sso/domains/{domain}`](https://docs.plotwork.dev/api/delete-orgs-org-sso-domains-domain.md) | Remove an email domain. |
| GET | [`/orgs/{org}/scim`](https://docs.plotwork.dev/api/get-orgs-org-scim.md) | Read an organisation's SCIM settings. |
| POST | [`/orgs/{org}/scim/token`](https://docs.plotwork.dev/api/post-orgs-org-scim-token.md) | Make or rotate the SCIM token. |
| DELETE | [`/orgs/{org}/scim/token`](https://docs.plotwork.dev/api/delete-orgs-org-scim-token.md) | Revoke the SCIM token. |
| PATCH | [`/orgs/{org}/scim/groups/{group}`](https://docs.plotwork.dev/api/patch-orgs-org-scim-groups-group.md) | Choose the role a SCIM group gives. |
| GET | [`/orgs/{org}/support`](https://docs.plotwork.dev/api/get-orgs-org-support.md) | Read what priority support is for an organisation. |
| POST | [`/orgs/{org}/support/requests`](https://docs.plotwork.dev/api/post-orgs-org-support-requests.md) | Ask the organisation's named contact for help. |

### Billing

| Method | Path | What it does |
|---|---|---|
| GET | [`/user/billing`](https://docs.plotwork.dev/api/get-user-billing.md) | Read the account's plan. |
| POST | [`/user/billing/checkout`](https://docs.plotwork.dev/api/post-user-billing-checkout.md) | Start a checkout for a paid plan. |
| POST | [`/user/billing/verify-checkout`](https://docs.plotwork.dev/api/post-user-billing-verify-checkout.md) | Read a finished checkout back. |
| POST | [`/user/billing/cancel`](https://docs.plotwork.dev/api/post-user-billing-cancel.md) | Cancel the plan at the end of the period. |
| POST | [`/user/billing/resume`](https://docs.plotwork.dev/api/post-user-billing-resume.md) | Take back a cancellation. |
| POST | [`/user/billing/portal`](https://docs.plotwork.dev/api/post-user-billing-portal.md) | Open the Stripe billing portal. |
| GET | [`/user/billing/documents`](https://docs.plotwork.dev/api/get-user-billing-documents.md) | List your invoices and receipts. |
| GET | [`/user/billing/documents/{id}`](https://docs.plotwork.dev/api/get-user-billing-documents-id.md) | Read one invoice or receipt. |
| GET | [`/user/billing/documents/{id}/pdf`](https://docs.plotwork.dev/api/get-user-billing-documents-id-pdf.md) | Download an invoice or receipt as a PDF. |
| POST | [`/billing/webhook`](https://docs.plotwork.dev/api/post-billing-webhook.md) | Receive a Stripe event. Called by Stripe, not by clients. |

### Enterprise

| Method | Path | What it does |
|---|---|---|
| POST | [`/enterprise/enquiries`](https://docs.plotwork.dev/api/post-enterprise-enquiries.md) | Send an Enterprise enquiry. |

### Telemetry

| Method | Path | What it does |
|---|---|---|
| POST | [`/telemetry/usage`](https://docs.plotwork.dev/api/post-telemetry-usage.md) | Receive the opt-in daily totals of the local npm package. |

### Health

| Method | Path | What it does |
|---|---|---|
| GET | [`/health`](https://docs.plotwork.dev/api/get-health.md) | Check the service is up. |

## Error envelope

Every failure uses the same shape, so a client needs one error handler.

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | `true` | yes | Always true, so clients can branch without reading the status. |
| `errorCode` | `string` | yes | Stable snake_case key such as validation.failed or diagram.invalid. |
| `message` | `string` | yes | Safe, human-readable summary. |
| `details` | `any` | no | Validation issues or diagnostics, JSON-safe. |
| `requestId` | `string` | no | Trace id for correlating with logs. |

## See also

| Doc | Why |
|---|---|
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The same operations as callable tools |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | What the diagram source may contain |
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | The language by example |