Organisations
Change one tab of a live whiteboard
Typed edit operations (as edit_diagram takes them) against the version read, rebased on the current source when others changed it since, or a whole new source against the current version; exactly one of operations and source.
POST
/v1/boards/{board}/tabs/{tab}/editsTL;DR
| Question | Answer |
|---|---|
| What does it do? | Change one tab of a live whiteboard. |
| What does it take? | A JSON body of type AgentEditBoardTabBody. |
| What does it return? | Status 200 with a body of type AgentBoardWriteResult. |
| What can go wrong? | 400 the body is not valid; 401 the API key is missing or not valid; 403 the account's plan does not include the REST API (plan.rest_not_included), the key is a person's own or a person's own agent (boards.org_key_required), a trusted publisher (boards.publisher_not_allowed), an organisation key without the boards scope (key.scope_missing), boards are not on for the organisation (boards.not_enabled), or the caller may look but not change the board (boards.forbidden); 404 no such board or tab, or the board is not open to the caller: the cases look alike; 409 the tab changed since baseVersion and the edit no longer applies (diagram.version_conflict, with details.currentVersion and each operation's result), the board has as many tabs as it may (boards.tab_limit), or the organisation is on legal hold; 413 the source is longer than a tab may be (boards.source_too_long), or the board holds as much as it may (boards.storage_full); 422 the result has errors (diagram.invalid, the diagnostics in details), an edit did not apply to the current version (boards.operation_failed, details.results), or it holds something that looks like a secret and the organisation blocks them (boards.secret_blocked); 429 too many requests, or a daily limit is spent; 503 live whiteboards are not set up on this server. Every failure uses the one error envelope. |
What it does
Typed edit operations (as edit_diagram takes them) against the version read, rebased on the current source when others changed it since, or a whole new source against the current version; exactly one of operations and source. The organisation's secret scanning, legal hold and audit apply. Every screen on the board shows the change live, labelled with the agent and its member. The REST twin of edit_board_tab.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
board | string | yes | The board's id: 22 letters and digits. |
tab | string | yes | The tab's id: 12 letters and digits. |
Request body
The body has the type AgentEditBoardTabBody.
| Field | Type | Required | Description |
|---|---|---|---|
revision | string | no | A revision of the tab to change instead of main; baseVersion is then the revision's. at least 12 characters; at most 12 characters; pattern ^[0-9A-Za-z]+$. |
baseVersion | integer | yes | |
operations | object[] | no | |
operations[].op | "rename" | "set" | "add_node" | "remove" | "add_edge" | "remove_edge" | "move" | "replace_text" | yes | |
operations[].target | string | no | Id, label, table.column, or "header". at most 2000 characters. |
operations[].to | string | no | rename: the new name. Edges: the end. at most 2000 characters. |
operations[].from | string | no | Edges: the start. at most 2000 characters. |
operations[].option | string | no | at most 40 characters; pattern ^[a-z][A-Za-z0-9_-]*$. |
operations[].value | string | null | no | set: null removes the option. at most 2000 characters. |
operations[].id | string | no | at most 2000 characters. |
operations[].label | string | no | add_edge on sankey: the amount. at most 2000 characters. |
operations[].type | string | no | add_node: node type, or statement word (c4 person, tree dir). at most 2000 characters. |
operations[].options | object | no | |
operations[].statement | string | no | add_node: the whole line, for a kind with no plain node statement. at most 2000 characters. |
operations[].into | string | null | no | A block; null is the top level. at most 2000 characters. |
operations[].after | string | no | at most 2000 characters. |
operations[].arrow | "<-->" | "-->" | "<->" | "..>" | "->" | "--" | no | |
operations[].find | string | no | at most 2000 characters. |
operations[].replace | string | no | at most 2000 characters. |
operations[].all | boolean | no | |
source | string | no | 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. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The new version and what changed. | AgentBoardWriteResult |
| 400 | The body is not valid. | ErrorResponse |
| 401 | The API key is missing or not valid. | ErrorResponse |
| 403 | The account's plan does not include the REST API (plan.rest_not_included), the key is a person's own or a person's own agent (boards.org_key_required), a trusted publisher (boards.publisher_not_allowed), an organisation key without the boards scope (key.scope_missing), boards are not on for the organisation (boards.not_enabled), or the caller may look but not change the board (boards.forbidden). | ErrorResponse |
| 404 | No such board or tab, or the board is not open to the caller: the cases look alike. | ErrorResponse |
| 409 | The tab changed since baseVersion and the edit no longer applies (diagram.version_conflict, with details.currentVersion and each operation's result), the board has as many tabs as it may (boards.tab_limit), or the organisation is on legal hold. | ErrorResponse |
| 413 | The source is longer than a tab may be (boards.source_too_long), or the board holds as much as it may (boards.storage_full). | ErrorResponse |
| 422 | The result has errors (diagram.invalid, the diagnostics in details), an edit did not apply to the current version (boards.operation_failed, details.results), or it holds something that looks like a secret and the organisation blocks them (boards.secret_blocked). | ErrorResponse |
| 429 | Too many requests, or a daily limit is spent. | ErrorResponse |
| 503 | Live whiteboards are not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type AgentBoardWriteResult.
| Field | Type | Required | Description |
|---|---|---|---|
changed | boolean | yes | False when the write changed nothing; nothing was stored. |
version | integer | yes | The tab's version now: the baseVersion of the next edit. |
tab | any | yes | |
tab.id | string | yes | at least 12 characters; at most 12 characters; pattern ^[0-9A-Za-z]+$. |
tab.name | string | yes | |
tab.kind | string | yes | |
tab.position | number | yes | |
tab.version | integer | yes | Send it as baseVersion with the next edit, and as sinceVersion to learn what changed after it. |
tab.updatedAt | integer | yes | |
tab.updatedBy | string | yes | |
results | object[] | yes | |
results[].op | string | yes | |
results[].applied | boolean | yes | |
results[].lines | integer[] | yes | |
results[].message | string | yes | |
results[].hint | string | null | yes | |
changes | object[] | yes | |
changes[].change | string | yes | |
changes[].subject | string | yes | |
changes[].name | string | yes | |
changes[].line | integer | null | yes | |
changes[].detail | string | yes | |
warnings | Diagnostic[] | yes | |
warnings[].code | "E100" | "E101" | "E110" | "E111" | "E120" | "E121" | "E123" | "E124" | "E125" | "E130" | "E131" | "E132" | "E133" | "E134" | "E135" | "E136" | "E137" | "E138" | "E139" | "E140" | "W200" | "W201" | "W202" | "W203" | "W204" | "W205" | "W206" | "W207" | "W208" | "W500" | "W600" | "W601" | "W700" | "W701" | "W702" | "W703" | "W704" | "W705" | "W706" | "W707" | "W708" | "W709" | "W710" | "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" | "S204" | 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. |
secrets | object | yes | |
secrets.count | integer | yes | |
secrets.kinds | string[] | yes |
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 |