Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
READ

get_board_snapshot

Reads a project's board as the Board page draws it, the columns the project keeps in order with their limits, tallies and cards, for the running sprint, a sprint by id, every open item or the unplanned ones; a guest token reads none.

Read the board before you pick up a card, so you know what the team committed to, which columns have room and what nobody holds. The answer carries scope (its kind: sprint, all or unplanned, and for a sprint its sprint_id, sprint_name, sprint_status, ends_on and days_left) and columns in the board's order, each with its status and label, its wip_limit (null when the project does not cap it), count, full (true when the column holds its limit or more, so a move into it is refused), points and its items in the board's order: id, reference, title, type, status, priority, story_points, assignee_id, assignee_name, epic_id, epic_reference, sprint_id and position. The columns the project hides are left out. The default scope is active, the running sprint, or every open item when no sprint runs; all adds the items finished or dropped in the last two weeks; unplanned is the items in no sprint; a sprint's UUID reads that sprint. assignee_id and search narrow the cards, never the tallies. To move a card use move_work_item, which the same limits and lifecycle gate; to take one use assign_work_item. A client guest's token reads no board.

Requires ability

work-item:view-any

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Annotations

Read-only

It reads and never changes anything.

Arguments

project_id*string

UUID of the project.

scopestringoptional

What the board shows: active (the running sprint; the default), all, unplanned, or a sprint UUID.

assignee_idstringoptional

Narrow the cards to one person, by user UUID.

searchstringoptional

Words the reference or the title must contain.

What it returns

{  "data": {    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "scope": {      "kind": "sprint",      "sprint_id": "8b3f6a02-2d5c-4e9f-8c4b-7d8e9f0a1b22",      "sprint_name": "Sprint 3",      "sprint_status": "active",      "ends_on": "2026-11-22",      "days_left": 9    },    "columns": [      {        "status": "backlog",        "label": "Backlog",        "wip_limit": null,        "count": 0,        "full": false,        "points": 0,        "items": []      },      {        "status": "ready",        "label": "Ready",        "wip_limit": null,        "count": 1,        "full": false,        "points": 5,        "items": [          {            "id": "4f1c2d3e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",            "reference": "CRM-142",            "title": "Reset a forgotten password",            "type": "story",            "status": "ready",            "priority": "high",            "story_points": "5",            "assignee_id": null,            "assignee_name": null,            "epic_id": "2c1b0a9f-8e7d-4c6b-a5f4-3e2d1c0b9a88",            "epic_reference": "CRM-12",            "sprint_id": "8b3f6a02-2d5c-4e9f-8c4b-7d8e9f0a1b22",            "position": 1000          }        ]      },      {        "status": "in_progress",        "label": "In progress",        "wip_limit": 2,        "count": 2,        "full": true,        "points": 8,        "items": [          {            "id": "5a2d3e4f-6b7c-4d8e-9f0a-1b2c3d4e5f60",            "reference": "CRM-143",            "title": "See my orders",            "type": "story",            "status": "in_progress",            "priority": "medium",            "story_points": "3",            "assignee_id": "3f8a1c2e-7b4d-4e5f-9a6b-1c2d3e4f5a6b",            "assignee_name": "Pat Manager",            "epic_id": "2c1b0a9f-8e7d-4c6b-a5f4-3e2d1c0b9a88",            "epic_reference": "CRM-12",            "sprint_id": "8b3f6a02-2d5c-4e9f-8c4b-7d8e9f0a1b22",            "position": 2000          },          {            "id": "6b3e4f50-7c8d-4e9f-8a1b-2c3d4e5f6a71",            "reference": "CRM-147",            "title": "Export my invoices",            "type": "bug",            "status": "in_progress",            "priority": "high",            "story_points": "5",            "assignee_id": null,            "assignee_name": null,            "epic_id": null,            "epic_reference": null,            "sprint_id": "8b3f6a02-2d5c-4e9f-8c4b-7d8e9f0a1b22",            "position": 3000          }        ]      },      {        "status": "in_review",        "label": "In review",        "wip_limit": null,        "count": 0,        "full": false,        "points": 0,        "items": []      },      {        "status": "in_qa",        "label": "In QA",        "wip_limit": null,        "count": 0,        "full": false,        "points": 0,        "items": []      },      {        "status": "done",        "label": "Done",        "wip_limit": null,        "count": 0,        "full": false,        "points": 0,        "items": []      }    ],    "item_count": 3  }}

How it fails

VALIDATION_FAILED

scope is not active, all, unplanned or a UUID.

RESOURCE_NOT_FOUND

unknown project_id, a project outside the token's scope, or a scope UUID that is not one of the project's sprints.

FORBIDDEN

the holder's role on the project does not carry work-item:view-any, or the token is a client guest's.

TOKEN_MISSING_ABILITY

token lacks work-item:view-any.

Related

move_work_itemmove a card to another column, under the same lifecycle and limits.assign_work_itemtake a card or hand it to someone.get_sprintthe sprint the board follows, with its points and dates.list_work_itemsthe same items as a list, with every filter.Work items APIthe rank endpoint that changes a card's place.

How is this guide?

Last updated on