Hosted diagrams

TL;DR

1. How publishing works

There is no way to send SVG. The API refuses a field it does not know, so a request that carries an svg field fails with status 400 and nothing is stored.

A link looks like https://cdn.plotwork.dev/d/k3T9vQ1xZ0aB7cD2eF4gHw.svg. It serves the picture and nothing else.

Publishing the same source in the same theme again from the same account finds the diagram that is already stored. You get the same link, created is false, and the time it is kept starts over. Nothing is stored twice, so an agent that repeats a step does not use up your allowance. If Plotwork's renderer changes, the same source can draw differently and then gets a new link.

Each publish is one call toward your daily limit.

Embedded source

By default the diagram source is not stored: the hosted picture shows the text of the diagram, and Plotwork keeps nothing else of it. With embedSource set to true, the renderer writes the source into the picture's metadata, and the picture can then be read back by read_diagram, by POST /v1/diagrams/read, or by anyone who fetches the link. Three things follow:

• The source is public. Anyone who has the link can read it, not only see the drawing. Do not set it for a diagram whose source must stay private.
• The picture is bigger by about the size of the source, and the plan's size limit counts it.
• The same diagram published with and without embedSource is two pictures, so it gets two links. Publishing it again with the same choice returns the same link.

Nothing sets embedSource for you. The privacy policy says the same. To change a diagram from its link, see Editing an existing diagram.

Folders

A diagram can be filed in a folder, such as Payments/Checkout. Pass folder when you publish, or move a diagram later with Move on the Diagrams page of the portal. A slash nests folders, up to five levels, and each name can be forty characters or fewer. A folder exists while it holds a diagram, so there is nothing to make or delete first. Folders are for your own tidiness: a folder is not part of the link, and nobody who has the link can see it.

Publishing the same diagram again with a different folder moves it and keeps its link. Leaving folder out keeps the diagram where it is.

2. Publish from an agent

The hosted MCP server has three tools that the local server does not: publish_diagram, list_diagrams and delete_diagram. This section is about publishing; List and delete from an agent covers the other two. Connect the hosted server with an API key or a browser sign-in, then ask in plain words:

Publish this diagram and give me the link.

The agent calls publish_diagram with the source it already has. It is told to publish only when you ask, because anyone who has the link can see the picture.

The result starts with the link, then a Markdown image to paste, such as ![Login flow](https://cdn.plotwork.dev/d/k3T9vQ1xZ0aB7cD2eF4gHw.svg). It carries the same fields as the REST answer below, including locked and lockedAt, and adds markdown. When the diagram is locked, the result also says so and that only the time it is kept was refreshed. A refusal says which limit was reached, lists every mistake in the source, or says the diagram is locked.

With organization, the answer has no public link and no Markdown image, because an organisation diagram has none. It has private: true and a viewUrl, a page of the portal that needs a sign-in, and the same id, name, folder, bytes and expiresAt. Your own library's answer does not change.

With alias, the answer also has stableLink with the link's alias and url, and the Markdown image uses the stable link, so the image you paste keeps showing the latest version.

With embedSource, the answer also has sourceEmbedded: true and a line saying the source is part of the picture. Without it the answer is what it always was.

Every other tool of the hosted server only reads, except delete_diagram. publish_diagram stores a file, so your client may ask for your approval before it runs.

3. Publish over REST

Send the source in a JSON body, with your API key in the X-API-Key header. The command reads the key from the environment variable PLOTWORK_API_KEY, so replace nothing in it.

1curl -s -X POST https://api.plotwork.dev/v1/diagrams/publish \2  -H "X-API-Key: $PLOTWORK_API_KEY" \3  -H "content-type: application/json" \4  -d '{"source":"flow \"Login\"\nnode user person \"User\"\nnode api service \"Auth API\"\nuser -> api : \"POST /login\"","theme":"light","name":"Login flow"}'

A new diagram answers 201. One that was already stored answers 200 with the same link. Add "embedSource":true to the body to write the source into the picture.

1{2  "id": "0b6f9a52-4d1e-4c7a-9f3e-6d2a1b8c5e70",3  "url": "https://cdn.plotwork.dev/d/k3T9vQ1xZ0aB7cD2eF4gHw.svg",4  "name": "Login flow",5  "theme": "light",6  "bytes": 8412,7  "createdAt": 1791515700000,8  "publishedAt": 1791515700000,9  "expiresAt": 1794107700000,10  "created": true,11  "locked": false,12  "lockedAt": null13}

These are the failures a client should expect. Every one uses the error envelope, and the errorCode is the field to branch on.

The publish endpoint page lists the request and the answer as the API describes them.

4. Limits

The limits are per account. They are the same numbers the API holds your account to.

A refusal for a full allowance is checked at the moment you publish, so two publishes that arrive together cannot both pass. Plans and billing covers the other limits, and the Diagrams page of the portal shows how much of your allowance you have used.

5. How long a diagram is kept

An expired diagram is removed by a clean-up that runs once a day, so a link can keep working a little past its expiry date.

6. Who can see a link

Anyone who has the link can see the picture. Treat it as you would a public address: do not publish a diagram that must stay private, and do not paste the link where you would not paste the diagram itself.

The link cannot be guessed, and it does not name your account. The picture itself carries the diagram's id in a data-plotwork-id attribute on its root element. It is the same id the Diagrams page shows with Copy ID, and the one the API lists, moves and deletes a diagram by, so a copy of the file can be traced back to its diagram. The id is not your account id and it is not a secret: using it takes you, signed in, and for anyone else the API answers as if the diagram did not exist. Only you can list your diagrams: from the portal while you are signed in, or through an agent connected to your account with your key or your sign-in. The picture holds the text of the diagram, such as its node labels, so check what a diagram says before you share it.

A diagram published to an organisation is different. It has no public link, and only the organisation's signed-in members, and API keys that belong to the organisation or to a member, can open it.

7. Delete a diagram

Delete in the portal

1. Sign in at app.plotwork.dev (opens in a new tab) and open the Diagrams page.
2. Press Delete on the diagram, then confirm.

The link stops working. Anyone who has it sees a missing picture, and so does any README or page that embeds it. A copy can stay visible for up to an hour, because the picture is cached and Plotwork does not clear that cache for each delete.

The Diagrams page also lists every diagram with its size, when it was created, when it expires, and buttons that copy its link or its Markdown.

Deleting over REST needs your signed-in session, so a REST call with an API key cannot delete a diagram. An agent connected to the hosted MCP server can, with the tool described next, and only after you have named the diagram.

List and delete from an agent

Connect the hosted server with an API key or a browser sign-in, then ask in plain words:

Show me the diagrams I have published.

The agent calls list_diagrams, which reads and changes nothing, and tells you what is stored. Then name the one to remove:

Delete the Login flow diagram.

The agent calls delete_diagram with the id it got from the list. It deletes only the diagram you named, and tells you which one it deleted.

The result of list_diagrams says whether the library is yours or an organisation's, how many diagrams it holds in all, and where the account stands against its plan. It lists each diagram with its id, name, folder, bytes, createdAt, publishedAt and expiresAt, whether the owner locked it (locked and lockedAt), and whether you may delete it (canDelete). A diagram in your own library has its public url; one in an organisation has its viewUrl and no public link. The result of delete_diagram has the id, deleted: true, private (true for an organisation's library) and how many diagrams remaining in that library.

Lock a diagram

A lock protects a diagram you want to keep. Lock it in the portal, and it cannot be renamed, moved or deleted, by you, by an agent acting for you, or by a script, until you unlock it. A delete is refused with hosting.diagram_locked, and the agent is told that nobody can delete the diagram until its owner unlocks it, and not to work around the lock. list_diagrams shows a locked diagram as locked.

8. Links that always show the latest version

A picture link is per drawing: change the diagram and publish it, and you get a new picture at a new link. A stable link is a name you choose, such as checkout-flow, with an address of its own that always shows the diagram you last published under that name. Paste the stable link into a README, a wiki or a Notion page once, and every later version shows there by itself.

Publish over REST with an alias:

1curl -s -X POST https://api.plotwork.dev/v1/diagrams/publish \2  -H "X-API-Key: $PLOTWORK_API_KEY" \3  -H "content-type: application/json" \4  -d '{"source":"flow \"Checkout\"\nnode cart service \"Cart\"\nnode pay service \"Payments\"\ncart -> pay","alias":"checkout-flow"}'

The answer is the usual one with a stableLink added:

1{2  "stableLink": {3    "id": "8f3c2a10-5b7e-4d21-9c64-1a2b3c4d5e6f",4    "alias": "checkout-flow",5    "url": "https://cdn.plotwork.dev/l/q3Zr8J1x0bWcVvKm2hT9pA.svg",6    "diagramId": "0b6f9a52-4d1e-4c7a-9f3e-6d2a1b8c5e70",7    "createdAt": 1791515700000,8    "updatedAt": 17915157000009  }10}

From an agent, ask for the name in plain words, and ask for the same name every time you update the diagram:

Publish this diagram with the alias checkout-flow and give me the stable link.

GET /user/diagrams lists every stable link you keep under stableLinks, with the diagram each one shows, and list_diagrams shows each diagram's stable links beside its picture link.

9. Embed a diagram in other tools

The oEmbed endpoint is GET https://api.plotwork.dev/oembed?url=<link>&format=json. It takes a stable link, a picture link, or a viewer page, and answers a photo with the picture's address, its width and height (scaled down to maxwidth and maxheight when you send them), the title "Diagram", and no author: a diagram's name is shown only to you. For a stable link the picture's address is the stable link itself, so an embed made from it keeps showing the latest version. Only format=json is answered, and a link that is not a Plotwork diagram, or shows nothing now, is a 404. The viewer page names the endpoint in its head, for tools that look there.

See also