Hosting
Save edited source over a hosted diagram
Draws the source and puts the new picture in place of the diagram's, keeping its id, name, folder and stable links; the picture link changes, so the answer has the new url.
PUT
/user/diagrams/{id}/sourceTL;DR
| Question | Answer |
|---|---|
| What does it do? | Save edited source over a hosted diagram. |
| What does it take? | A JSON body of type SaveDiagramSourceBody. |
| What does it return? | Status 200 with a body of type EditedDiagram. |
| What can go wrong? | 400 the body is not valid; 401 not signed in; 403 the plan does not include the editor (plan.editor_not_included), the larger picture does not fit the plan (hosting.quota_exceeded), an organisation the account belongs to requires its members to publish to its library (orgs.publish_required), or the request came from an origin that may not make changes; 404 no such diagram; 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 hosting is not set up on this server. Every failure uses the one error envelope. |
What it does
Draws the source and puts the new picture in place of the diagram's, keeping its id, name, folder and stable links; the picture link changes, so the answer has the new url. 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. Needs a plan with the diagram editor (403 plan.editor_not_included).
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
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. | EditedDiagram |
| 400 | The body is not valid. | ErrorResponse |
| 401 | Not signed in. | ErrorResponse |
| 403 | The plan does not include the editor (plan.editor_not_included), the larger picture does not fit the plan (hosting.quota_exceeded), an organisation the account belongs to requires its members to publish to its library (orgs.publish_required), or the request came from an origin that may not make changes. | ErrorResponse |
| 404 | No such diagram. | 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 | Hosting is not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type EditedDiagram.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The handle for managing the diagram (delete). It is not in the link. |
url | string | yes | The public address of the SVG. Anyone with the link can see it; the token in it cannot be guessed. |
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. |
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 plan keeps diagrams until you delete them. |
locked | boolean | yes | True while the diagram is locked: it cannot be deleted, renamed or moved until you unlock it. A lock does not stop it expiring on a plan that expires diagrams. |
lockedAt | integer | null | yes | When it was locked, in milliseconds since the epoch, or null when it is not locked. |
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 |