Hosting
Publish a diagram and get a link
Renders the source and stores the SVG at a public link that cannot be guessed.
POST
/v1/diagrams/publishTL;DR
| Question | Answer |
|---|---|
| What does it do? | Publish a diagram and get a link. |
| What does it take? | A JSON body of type PublishDiagramBody. |
| What does it return? | Status 200 with a body of type PublishAnswer. |
| What can go wrong? | 400 the body failed schema validation, personal and organization were both sent, or an alias was sent for a diagram that lands in an organisation; 401 the api key is missing or not valid; 403 the plan has no room for another diagram (details says which limit, the plan, the limit, and what is used), the key is an organisation key (orgs.key_wrong_org, with details.organization, the id of its organisation), which publishes with post /orgs/{org}/diagrams, an organisation requires its members to publish to its library (orgs.publish_required, with details.organizations), or the role may not publish there (orgs.forbidden, orgs.folder_restricted); 404 the organisation named does not exist, or the account is not a member of it; 409 the diagram is already hosted and locked, and the publish names it or files it elsewhere (hosting.diagram_locked; unlock it in the portal first), or several organisations publish their members' diagrams to their library and none is the default (orgs.publish_ambiguous, with details.organizations); 413 the body is larger than the size cap, or the diagram renders larger than the plan hosts; 422 the diagram source has errors; the diagnostics are in details; 429 too many requests; 502 the diagram could not be stored; 503 hosting is not set up on this server. Every failure uses the one error envelope. |
What it does
Renders the source and stores the SVG at a public link that cannot be guessed. Only the renderer's own output is stored; there is no field for SVG. The same diagram published again from the same account keeps its link (200, created false) and moves its expiry out. 403 hosting.quota_exceeded says which limit was reached; 413 hosting.too_large says the diagram is larger than the plan hosts.
Request body
The body has the type PublishDiagramBody.
| Field | Type | Required | Description |
|---|---|---|---|
source | string | yes | Diagram source; the first line is the header, such as flow "Title" (draw_diagram lists every kind). at least 1 character; at most 50000 characters. |
settings | object | no | The repo's plotwork.config.json, if any. Schema: https://docs.plotwork.dev/schemas/plotwork.config.json (opens in a new tab). |
theme | "light" | "dark" | "auto" | no | The color scheme to draw it in: light, dark, or auto (one picture that follows the viewer's light or dark setting). default "light". |
embedSource | boolean | no | Write the diagram source into the stored SVG, in its metadata, so the picture can be edited later: read_diagram gives the source back from the link. The source then becomes part of the picture, which anyone who has the link can read (for a diagram in an organisation, every member who can open it). The same diagram published with and without it is two pictures with two links. Left out, a personal diagram does not store the source, and a diagram that lands in an organisation follows its keepEditable setting. |
name | string | no | A label for the diagram in your list and in the Markdown snippet. Optional. at least 1 character; at most 80 characters; pattern ^[^\p{Cc}]+$/u. |
folder | string | null | no | The folder to file the diagram in. Left out, a new diagram goes to the top level and a diagram that is already hosted stays where it is. A path files a new diagram there, or moves the one that is already hosted and keeps its link. null puts it at the top level. |
alias | string | no | Point a stable link with this name at the diagram, so one address always shows the latest version. The first publish with a name makes the stable link (the answer's stableLink.url) and every later publish with the same name moves it to the new diagram; the address never changes. How many stable links an account keeps depends on its plan. An alias asks for a personal link, so an organisation that requires its library refuses it (orgs.publish_required). Optional. at least 1 character; at most 60 characters; pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$. |
organization | string | no | An organisation's slug or id: the diagram goes to that organisation's private library, and the answer has private true and a viewUrl in place of a public link. The account must be a member who may publish there. Left out, the diagram goes to your own library, unless an organisation you belong to publishes its members' diagrams to its library. at least 1 character; at most 64 characters. |
personal | boolean | no | True asks for a public link in your own library even though an organisation you belong to publishes its members' diagrams to its library by default. An organisation that requires its library refuses it (403 orgs.publish_required). Not with organization. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The diagram was already hosted; its link is unchanged. | PublishAnswer |
| 201 | The diagram was stored. | PublishAnswer |
| 400 | The body failed schema validation, personal and organization were both sent, or an alias was sent for a diagram that lands in an organisation. | ErrorResponse |
| 401 | The API key is missing or not valid. | ErrorResponse |
| 403 | The plan has no room for another diagram (details says which limit, the plan, the limit, and what is used), the key is an organisation key (orgs.key_wrong_org, with details.organization, the id of its organisation), which publishes with POST /orgs/{org}/diagrams, an organisation requires its members to publish to its library (orgs.publish_required, with details.organizations), or the role may not publish there (orgs.forbidden, orgs.folder_restricted). | ErrorResponse |
| 404 | The organisation named does not exist, or the account is not a member of it. | ErrorResponse |
| 409 | The diagram is already hosted and locked, and the publish names it or files it elsewhere (hosting.diagram_locked; unlock it in the portal first), or several organisations publish their members' diagrams to their library and none is the default (orgs.publish_ambiguous, with details.organizations). | ErrorResponse |
| 413 | The body is larger than the size cap, or the diagram renders larger than the plan hosts. | ErrorResponse |
| 422 | The diagram source has errors; the diagnostics are in details. | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
| 502 | The diagram could not be stored. | ErrorResponse |
| 503 | Hosting is not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type PublishAnswer.
| Field | Type | Required | Description |
|---|
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
| Tool reference | The operations as callable tools |