Organisations
Open a live whiteboard as an agent
The board's tabs with their versions (no sources), the caller's role, who is on it now, and its address in the portal.
GET
/v1/boards/{board}TL;DR
| Question | Answer |
|---|---|
| What does it do? | Open a live whiteboard as an agent. |
| What does it take? | board in the path. |
| What does it return? | Status 200 with a body of type AgentBoard. |
| What can go wrong? | 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; 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
The board's tabs with their versions (no sources), the caller's role, who is on it now, and its address in the portal. Everyone on the board sees the agent reading it. The REST twin of open_board.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
board | string | yes | The board's id: 22 letters and digits. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The board. | AgentBoard |
| 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 |
| 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 AgentBoard.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | at least 22 characters; at most 22 characters; pattern ^[0-9A-Za-z]+$. |
name | string | yes | |
classification | "public" | "internal" | "confidential" | yes | |
role | "view" | "edit" | "manage" | yes | What the caller may do: view, edit, or manage. An agent has its member's role; a key the role every member gets. |
version | integer | yes | The version of the tab list: it moves when a tab is added, renamed, moved or deleted. |
url | string | yes | The board's address in the portal, for the person. |
tabs | AgentBoardTab[] | yes | |
tabs[].id | string | yes | at least 12 characters; at most 12 characters; pattern ^[0-9A-Za-z]+$. |
tabs[].name | string | yes | |
tabs[].kind | string | yes | |
tabs[].position | number | yes | |
tabs[].version | integer | yes | Send it as baseVersion with the next edit, and as sinceVersion to learn what changed after it. |
tabs[].updatedAt | integer | yes | |
tabs[].updatedBy | string | yes | |
present | object[] | yes | Who is on the board now: people with it open, and agents that acted in the last two minutes. |
present[].label | string | yes | |
present[].kind | "person" | "agent" | yes | |
messages | BoardAgentMessage[] | yes | Messages the caller's person sent it on the board that it had not read, each given once. Answer each with reply_board_message. |
messages[].id | string | yes | |
messages[].at | integer | yes | |
messages[].from | string | yes | |
messages[].text | string | yes | |
messages[].tab | string | null | yes | |
messages[].tabName | string | null | yes | |
messages[].revision | string | null | yes | |
messages[].problems | BoardAgentProblem[] | yes | |
messages[].problems[].code | string | yes | pattern ^[A-Z]\d{3,4}$. |
messages[].problems[].severity | "error" | "warning" | yes | |
messages[].problems[].line | integer | yes | minimum 1; maximum 1000000. |
messages[].problems[].column | integer | yes | minimum 1; maximum 1000000. |
messages[].problems[].message | string | yes | at least 1 character; at most 500 characters. |
messages[].problems[].hint | string | null | yes | at least 1 character; at most 500 characters. |
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 |