Organisations
Add a tab to a board
Adds a tab, empty or with source, after the tab named (at the end when none).
POST
/orgs/{org}/boards/{board}/tabsTL;DR
| Question | Answer |
|---|---|
| What does it do? | Add a tab to a board. |
| What does it take? | A JSON body of type AddBoardTabBody. |
| What does it return? | Status 200 with a body of type BoardWriteResult. |
| What can go wrong? | 400 the body is not valid; 401 not signed in; 403 boards are not turned on for this organisation (boards.not_enabled), the caller may look but not change it (boards.forbidden), or the request came from an origin that may not make changes; 404 no such organisation, board or tab, or the board is not open to the caller: the cases look alike; 409 the tab changed since the version sent (diagram.version_conflict, details.currentVersion), the board has as many tabs as it may (boards.tab_limit), the last tab cannot go (boards.last_tab), or the organisation is on legal hold (orgs.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 source has errors (diagram.invalid, the diagnostics in details), an edit did not apply (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; 503 organisations or boards are not set up on this server. Every failure uses the one error envelope. |
What it does
Adds a tab, empty or with source, after the tab named (at the end when none). Its source must parse and passes the organisation secret scan. Every open browser sees it at once.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation's id or its slug. |
board | string | yes | The board's id: 22 letters and digits. |
Request body
The body has the type AddBoardTabBody.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | at least 1 character; at most 60 characters. |
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. |
after | string | null | no | at least 12 characters; at most 12 characters; pattern ^[0-9A-Za-z]+$. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The new version, what changed, and the board. | BoardWriteResult |
| 400 | The body is not valid. | ErrorResponse |
| 401 | Not signed in. | ErrorResponse |
| 403 | Boards are not turned on for this organisation (boards.not_enabled), the caller may look but not change it (boards.forbidden), or the request came from an origin that may not make changes. | ErrorResponse |
| 404 | No such organisation, board or tab, or the board is not open to the caller: the cases look alike. | ErrorResponse |
| 409 | The tab changed since the version sent (diagram.version_conflict, details.currentVersion), the board has as many tabs as it may (boards.tab_limit), the last tab cannot go (boards.last_tab), or the organisation is on legal hold (orgs.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 source has errors (diagram.invalid, the diagnostics in details), an edit did not apply (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. | ErrorResponse |
| 503 | Organisations or boards are not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type BoardWriteResult.
| Field | Type | Required | Description |
|---|---|---|---|
changed | boolean | yes | False when the write changed nothing; nothing was stored. |
version | integer | yes | |
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 | The kind the source declares, such as flow. |
tab.position | number | yes | |
tab.version | integer | yes | |
tab.updatedAt | integer | yes | |
tab.updatedBy | string | yes | Who changed it last: an email address, an agent and its member, or a key name. |
tab.library | object | null | yes | |
tab.library.diagramId | string | yes | |
tab.library.version | integer | yes | |
tab.library.saved | boolean | yes | True while the tab holds what was saved or imported. |
head | BoardHead | yes | |
head.id | string | yes | at least 22 characters; at most 22 characters; pattern ^[0-9A-Za-z]+$. |
head.orgId | string | yes | |
head.version | integer | yes | |
head.tabs | BoardTab[] | yes | |
head.tabs[].id | string | yes | at least 12 characters; at most 12 characters; pattern ^[0-9A-Za-z]+$. |
head.tabs[].name | string | yes | |
head.tabs[].kind | string | yes | The kind the source declares, such as flow. |
head.tabs[].position | number | yes | |
head.tabs[].version | integer | yes | |
head.tabs[].updatedAt | integer | yes | |
head.tabs[].updatedBy | string | yes | Who changed it last: an email address, an agent and its member, or a key name. |
head.tabs[].library | object | null | 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 |