Organisations
Publish a diagram to an organisation
Renders the source and stores the SVG in the organisation's private library; there is no public link, only a viewUrl for signed-in members.
POST
/orgs/{org}/diagramsTL;DR
| Question | Answer |
|---|---|
| What does it do? | Publish a diagram to an organisation. |
| What does it take? | A JSON body of type PublishOrganisationDiagramBody. |
| What does it return? | Status 200 with a body of type PublishedOrganisationDiagram. |
| What can go wrong? | 400 the body failed schema validation; 401 not signed in, or the key is not valid; 403 the caller's role may not publish (orgs.forbidden), the folder is restricted to others (orgs.folder_restricted), the organisation's plan has no room for another diagram (hosting.quota_exceeded), or the request came from an origin that may not make changes; 404 no such organisation, the caller is not a member of it, or the key belongs to another organisation; 409 the diagram is already in the library and locked, and the publish names it or files it elsewhere (hosting.diagram_locked). only the owner can unlock it; 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, or the daily limit is used up; 502 the diagram could not be stored; 503 organisations are not set up on this server. Every failure uses the one error envelope. |
What it does
Renders the source and stores the SVG in the organisation's private library; there is no public link, only a viewUrl for signed-in members. The same diagram published again keeps its place (200, created false) and moves its expiry out. 403 hosting.quota_exceeded carries the organisation's numbers; 413 hosting.too_large says the diagram is larger than the plan hosts.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation's id or its slug. |
Request body
The body has the type PublishOrganisationDiagramBody.
| 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 diagram can be edited later; every member who can open it can then read the source. The same diagram published with and without it is two pictures. Left out, the organisation's keepEditable setting decides (false unless the owner turned it on); false always leaves the source out. |
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. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The diagram was already in the library; it was kept. | PublishedOrganisationDiagram |
| 201 | The diagram was stored. | PublishedOrganisationDiagram |
| 400 | The body failed schema validation. | ErrorResponse |
| 401 | Not signed in, or the key is not valid. | ErrorResponse |
| 403 | The caller's role may not publish (orgs.forbidden), the folder is restricted to others (orgs.folder_restricted), the organisation's plan has no room for another diagram (hosting.quota_exceeded), or the request came from an origin that may not make changes. | ErrorResponse |
| 404 | No such organisation, the caller is not a member of it, or the key belongs to another organisation. | ErrorResponse |
| 409 | The diagram is already in the library and locked, and the publish names it or files it elsewhere (hosting.diagram_locked). Only the owner can unlock it. | 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, or the daily limit is used up. | ErrorResponse |
| 502 | The diagram could not be stored. | ErrorResponse |
| 503 | Organisations are not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type PublishedOrganisationDiagram.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The handle for the diagram in the routes below. |
name | string | null | yes | The label given at publish, or null. |
folder | string | null | yes | The folder it is filed in, such as Payments/Checkout, or null for the top level. |
theme | "light" | "dark" | "auto" | yes | The color scheme it was drawn in: light, dark, or auto. |
bytes | integer | yes | Size of the stored SVG in bytes. |
createdBy | string | null | yes | The account that published it, or null when that account has left or an organisation key published it. |
createdAt | integer | yes | When it was first published, in milliseconds since the epoch. |
publishedAt | integer | yes | When it was last published, in milliseconds since the epoch. Publishing the same diagram again moves it. |
expiresAt | integer | null | yes | When it will be deleted, in milliseconds since the epoch, or null when the owner's plan keeps diagrams until they are deleted. |
viewUrl | string | yes | A page in the portal that shows the diagram to a signed-in member. It is not a link anyone can open: an organisation's diagrams have no public address. |
locked | boolean | yes | True while the owner has the diagram locked: nobody can delete, rename or move it, its publisher and the owner included, until the owner unlocks it. A lock does not stop it expiring on a plan that expires diagrams. |
lockedAt | integer | null | yes | When the owner locked it, in milliseconds since the epoch, or null when it is not locked. |
restricted | true | no | Present, and true, when the owner has restricted this diagram's folder and the caller is allowed in it, so the portal can show it as locked. Absent otherwise. A diagram in a folder the caller may not use is not listed at all. |
created | boolean | yes | True when this call stored a new diagram; false when the same diagram was already in the library and was kept. |
sourceEmbedded | boolean | yes | True when the stored picture carries the diagram source: the call sent embedSource true, or left it out while the organisation's keepEditable is on. |
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 |