Organisations
Save edited source over an organisation diagram
Draws the source with the organisation's brand and icons and stores it in place of the diagram's picture, keeping its id, name and folder; the replaced picture is kept as a previous version.
PUT
/orgs/{org}/diagrams/{id}/sourceTL;DR
| Question | Answer |
|---|---|
| What does it do? | Save edited source over an organisation diagram. |
| What does it take? | A JSON body of type SaveDiagramSourceBody. |
| What does it return? | Status 200 with a body of type EditedOrganisationDiagram. |
| What can go wrong? | 400 the body is not valid; 401 not signed in; 403 the role may not change this diagram (orgs.forbidden), the owner's plan does not include the editor (plan.editor_not_included), the picture does not fit the plan (hosting.quota_exceeded), or the request came from an origin that may not make changes; 404 no such organisation or diagram, the diagram is in a folder the caller may not use, or the caller is not a member; 409 locked (hosting.diagram_locked), saved since (diagram.version_conflict, details.currentversion), or another diagram already has this picture (diagram.duplicate_content); 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 organisations are not set up on this server. Every failure uses the one error envelope. |
What it does
Draws the source with the organisation's brand and icons and stores it in place of the diagram's picture, keeping its id, name and folder; the replaced picture is kept as a previous version. baseVersion is the publishedAt the editor loaded: a diagram saved since is 409 diagram.version_conflict with details.currentVersion. The owner's plan must include the diagram editor.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation's id or its slug. |
id | string | yes |
Request body
The body has the type SaveDiagramSourceBody.
| 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. |
theme | "light" | "dark" | "auto" | no | The color scheme to draw it in: light, dark, or auto. Left out, the theme the diagram has. |
baseVersion | integer | yes | The diagram's publishedAt (milliseconds since the epoch) when the editor loaded it. If the diagram was saved since, the answer is 409 diagram.version_conflict with details.currentVersion. minimum 0. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The diagram as the list shows it, with warnings and changed. | EditedOrganisationDiagram |
| 400 | The body is not valid. | ErrorResponse |
| 401 | Not signed in. | ErrorResponse |
| 403 | The role may not change this diagram (orgs.forbidden), the owner's plan does not include the editor (plan.editor_not_included), the picture does not fit the plan (hosting.quota_exceeded), or the request came from an origin that may not make changes. | ErrorResponse |
| 404 | No such organisation or diagram, the diagram is in a folder the caller may not use, or the caller is not a member. | ErrorResponse |
| 409 | Locked (hosting.diagram_locked), saved since (diagram.version_conflict, details.currentVersion), or another diagram already has this picture (diagram.duplicate_content). | 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 | Organisations are not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type EditedOrganisationDiagram.
| 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. |
warnings | Diagnostic[] | yes | Quality warnings from drawing the source, as draw_diagram gives them. Empty for a restore. |
warnings[].code | "E100" | "E101" | "E110" | "E111" | "E120" | "E121" | "E122" | "E123" | "E124" | "E125" | "E130" | "E131" | "E132" | "E133" | "E134" | "E135" | "E136" | "E137" | "E138" | "E139" | "E140" | "W200" | "W201" | "W202" | "W203" | "W204" | "W205" | "W206" | "W207" | "W500" | "M100" | "M101" | "M102" | "M103" | "M104" | "M110" | "M200" | "M201" | "M202" | "M203" | "M204" | "M205" | "M206" | "M207" | "M208" | "M209" | "M210" | "M211" | "M212" | "M213" | "M214" | "M215" | "M216" | "M217" | "M218" | "E300" | "E301" | "E302" | "E303" | "E304" | "W300" | "W301" | "W302" | "W303" | "M120" | "M220" | "M221" | "M222" | "E340" | "E341" | "E342" | "E343" | "E344" | "E345" | "W320" | "W321" | "W322" | "W323" | "M240" | "M241" | "M242" | "E360" | "E361" | "E362" | "E363" | "E364" | "E365" | "E366" | "E367" | "W330" | "W331" | "W332" | "W333" | "W334" | "M250" | "M251" | "E400" | "E401" | "E402" | "E403" | "W350" | "W351" | "W352" | "W353" | "M270" | "M271" | "E420" | "E421" | "E422" | "E423" | "E424" | "W360" | "W361" | "W362" | "W363" | "W364" | "M180" | "M280" | "M281" | "M282" | "E320" | "E321" | "E322" | "E323" | "E324" | "E325" | "E326" | "E327" | "E328" | "E329" | "E330" | "W310" | "W311" | "W312" | "W313" | "W314" | "M130" | "M131" | "M132" | "M230" | "M231" | "M232" | "M233" | "M234" | "M235" | "M236" | "M237" | "M238" | "E380" | "E381" | "E382" | "E383" | "W340" | "W341" | "W342" | "W343" | "M260" | "I100" | "I101" | "I102" | "I103" | "I104" | "I105" | "I200" | "I201" | "I202" | "I203" | "I204" | "I206" | "R100" | "R101" | "R200" | "R201" | "R202" | "R203" | "R204" | "R205" | "R206" | "R207" | "S100" | "S200" | "S101" | "S102" | "S103" | "S104" | "S201" | "S202" | "S203" | yes | Stable code to branch on; E-codes are errors, W-codes are warnings. |
warnings[].severity | "error" | "warning" | yes | Errors stop rendering; warnings never do. |
warnings[].message | string | yes | What is wrong, in one sentence. |
warnings[].line | integer | yes | 1-based line in the submitted source. minimum 1. |
warnings[].column | integer | yes | 1-based column in that line. minimum 1. |
warnings[].length | integer | yes | Number of characters the problem covers. minimum 1. |
warnings[].hint | string | null | yes | A concrete suggestion for fixing it, or null. |
changed | boolean | yes | False when the source draws the picture the diagram already has: nothing was stored and no version was kept. |
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 |