Whiteboards

One whiteboard for each list: task cards, sticky notes and text laid out on a canvas. A board is as open as its list: it can be read by whoever can open the list, and changed by whoever can edit the project while the list, its folders and the project are active. The title of a task card is shown only to someone who may open that task.

Read a whiteboard

GET /api/v2/whiteboards/:projectId/:sprintId · beta

Returns the board of a list: its cards, notes and texts.

A list that has no board yet answers with an empty one at revision 0.


Auth	Session or API token with the `read` scope
Token limited to projects	Refused
Permission	The caller must be able to open the list

Path parameters

Name	Type	Description
`projectId`	id	The project.
`sprintId`	id	The list.

Request

http

GET /api/v2/whiteboards/<projectId>/<sprintId>
Authorization: Bearer <token>
companyid: <company id>

Response

json

{
  "status": true,
  "statusText": "Whiteboard fetched.",
  "data": {
    "boardId": "<board id>",
    "revision": 3,
    "elements": [
      {
        "id": "card1",
        "type": "task",
        "x": 120,
        "y": 80,
        "z": 0,
        "taskId": "<task id>",
        "title": "Write the release notes",
        "taskKey": "WEB-12"
      },
      {
        "id": "note1",
        "type": "note",
        "text": "Ask design",
        "tone": "amber",
        "x": 400,
        "y": 80,
        "w": 200,
        "h": 120,
        "z": 1
      }
    ],
    "savedBy": "<user id>",
    "savedAt": "2026-10-01T09:30:00.000Z",
    "canEdit": true,
    "limits": { "elements": 2000, "notes": 500, "text": 2000 }
  }
}

Field	Description
`elements`	A `task` card (`id`, `type`, `x`, `y`, `z`, `taskId`, `title`, `taskKey`), a `note` (`text`, `tone`, `x`, `y`, `w`, `h`, `z`) or a `text` (the same without `tone`). A card for a task the caller may not open carries only its place and `withheld: true`. A card whose task was deleted or moved to another list is left out.
`revision`	The number a save names as `baseRevision`.
`canEdit`	Whether the caller may change the board now.
`limits`	The most cards, notes and texts a board holds, and the longest text.

Errors

Status	When
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `read` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
404	The project or list does not exist, or the caller cannot open it.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

Save a whiteboard

PATCH /api/v2/whiteboards/:projectId/:sprintId · beta

Adds, moves and removes elements on a board, as a change on the revision the caller last read.

A card names the task it stands for and a task has one card: a second card for it moves the first. A note or a text is replaced whole. A new card is left out, with no word of why, when its task is not a live task of the list or one the caller may not open. A save that changes nothing is answered without a new revision.

The state a save replaces is kept in the history: when someone else is about to change the board, when the save touches half the board or more, and otherwise at most once every ten minutes. The history holds the last 20 states.


Auth	Session or API token with the `write` scope
Token limited to projects	Refused
Permission	The caller must be able to edit the project, and the list, its folders and the project must be active

Path parameters

Name	Type	Description
`projectId`	id	The project.
`sprintId`	id	The list.

Body

Field	Type	Required	Description
`baseRevision`	integer	yes	The `revision` the change was made on.
`upsert`	object[]		The elements to add or replace, at most 2500 of them, each named once. A `task` card carries `id`, `type`, `taskId`, `x`, `y` and `z`. A `note` carries `id`, `type`, `text`, `tone`, `x`, `y`, `w`, `h` and `z`; a `text` the same without `tone`.
`remove`	string[]		The ids of the elements to take off.

Name at least one of upsert and remove. An element id is up to 40 letters, digits, - and _. x and y are numbers from 0 to 100000, w from 40 to 1200, h from 24 to 1200, z a whole number up to 1000000 (default 0), text up to 2000 characters, tone one of amber, green, red, violet, brand or grey. A board holds at most 2000 cards and 500 notes and texts. One save is at most 512 KB. Any other key is refused.

Request

http

PATCH /api/v2/whiteboards/<projectId>/<sprintId>
Authorization: Bearer <token>
companyid: <company id>
Content-Type: application/json

{
  "baseRevision": 3,
  "upsert": [
    {
      "id": "note1",
      "type": "note",
      "text": "Ask design",
      "tone": "amber",
      "x": 400,
      "y": 80,
      "w": 200,
      "h": 120
    }
  ],
  "remove": ["card2"]
}

Response

json

{
  "status": true,
  "statusText": "Whiteboard saved.",
  "data": {
    "boardId": "<board id>",
    "revision": 4,
    "elements": [],
    "savedBy": "<user id>",
    "savedAt": "2026-10-01T09:30:00.000Z",
    "canEdit": true,
    "limits": { "elements": 2000, "notes": 500, "text": 2000 }
  }
}

data is the board after the save, as in Read a whiteboard; the example leaves elements empty.

Errors

Status	When
400	A key that is not known, a field of the wrong type or size, or a save that changes nothing. The answer names the `field`.
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `write` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
409	The board changed since `baseRevision`. The answer has `code: "revision_conflict"` and the current board in `data`.
413	The save, or the board it would make, is too large.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

List a whiteboard's history

GET /api/v2/whiteboards/:projectId/:sprintId/history · beta

Lists the earlier states kept for a board, newest first.

Needs a project and list the caller can open; anything else answers 404 Whiteboard not found.. Answers with data: the earlier states kept for the board, newest first, each with revision, savedBy, savedAt, cards (how many elements) and reason.


Auth	Session or API token with the `read` scope
Token limited to projects	Refused
Permission	The caller must be able to open the list

Path parameters

Name	Type	Description
`projectId`	id	The project.
`sprintId`	id	The list.

Request

http

GET /api/v2/whiteboards/<projectId>/<sprintId>/history
Authorization: Bearer <token>
companyid: <company id>

Response

json

{
  "status": true,
  "statusText": "Whiteboard history fetched.",
  "data": [
    {
      "revision": 3,
      "savedBy": "<user id>",
      "savedAt": "2026-10-01T09:30:00.000Z",
      "cards": 12,
      "reason": "interval"
    }
  ]
}

revision is the state to name in a restore. cards counts every element of that state. reason says why it was kept: author (someone else was about to change the board), bulk (a save touched half the board or more), interval (ten minutes had passed) or restore (the state before a restore).

Paging

None. A board keeps at most 20 states.

Errors

Status	When
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `read` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
404	The project or list does not exist, or the caller cannot open it.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

Restore a whiteboard

POST /api/v2/whiteboards/:projectId/:sprintId/restore · beta

Puts an earlier state of a board back, as a new revision.

The state being replaced is kept in the history. Cards whose tasks are gone are left out.


Auth	Session or API token with the `write` scope
Token limited to projects	Refused
Permission	The caller must be able to edit the project, and the list, its folders and the project must be active

Path parameters

Name	Type	Description
`projectId`	id	The project.
`sprintId`	id	The list.

Body

Field	Type	Required	Description
`revision`	integer	yes	The `revision` of a state in the history, 1 or more.

Request

http

POST /api/v2/whiteboards/<projectId>/<sprintId>/restore
Authorization: Bearer <token>
companyid: <company id>
Content-Type: application/json

{ "revision": 3 }

Response

json

{
  "status": true,
  "statusText": "Whiteboard restored.",
  "data": {
    "boardId": "<board id>",
    "revision": 5,
    "elements": [],
    "savedBy": "<user id>",
    "savedAt": "2026-10-01T09:30:00.000Z",
    "canEdit": true,
    "limits": { "elements": 2000, "notes": 500, "text": 2000 }
  }
}

data is the board after the restore, as in Read a whiteboard; the example leaves elements empty.

Errors

Status	When
400	`revision` is not a whole number of 1 or more.
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `write` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
404	The project or list does not exist, or the caller cannot open it; or that earlier state is no longer kept.
409	The board changed while it was being restored. The answer has `code: "revision_conflict"` and the current board in `data`.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

Whiteboards ​

Read a whiteboard ​

Save a whiteboard ​

List a whiteboard's history ​

Restore a whiteboard ​

Whiteboards

Read a whiteboard

Save a whiteboard

List a whiteboard's history

Restore a whiteboard