For AI agents: markdown of this page — /docs-content-en/task-stages.md documentation index — /llms.txt

Task kanban stages

GET /v1/tasks/stages/:entityId

Returns the current kanban columns of a workgroup or the personal "My tasks" plan of the current user. Use it to display the board's set of stages and their order.

Bitrix24 API: task.stages.get Scope: task

Parameters

Parameter Type Required Default Description
entityId (path) number yes — Owner of the stages: workgroup identifier or 0 — the personal "My tasks" plan of the current user. Group source: GET /v1/workgroups

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/tasks/stages/7" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/tasks/stages/7" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/stages/7', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/stages/7', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Array of columns, sorted by sort
data[].id number Stage identifier
data[].title string Column name
data[].sort number Sort order on the board
data[].color string Column color in RRGGBB format
data[].systemType string System stage type: NEW, WORK, REVIEW, FINISH. For custom columns — null
data[].entityId number Owner identifier — group or user
data[].entityType string Owner type: G — group, U — personal plan

Response example

Kanban stages of group 7:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 87,
      "title": "New",
      "sort": 100,
      "color": "00C4FB",
      "systemType": "NEW",
      "entityId": 7,
      "entityType": "G"
    },
    {
      "id": 88,
      "title": "In progress",
      "sort": 200,
      "color": "47D1E2",
      "systemType": null,
      "entityId": 7,
      "entityType": "G"
    },
    {
      "id": 89,
      "title": "Done",
      "sort": 300,
      "color": "75D900",
      "systemType": null,
      "entityId": 7,
      "entityType": "G"
    }
  ]
}

Error response example

400 — entityId is less than zero:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "entityId must be a non-negative integer (0 = personal plan)"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS entityId is less than zero or not a number
403 BITRIX_ACCESS_DENIED No access to this group's tasks, or no group exists with the given entityId
403 SCOPE_DENIED The key lacks the task scope
401 TOKEN_MISSING The key has no access tokens configured
401 MISSING_API_KEY The X-Api-Key header was not passed

Full list of common API errors — Errors.

Known specifics

Group columns and task history do not match. The method returns the current columns of the group kanban. In the task history the STAGE event stores the stage name at the moment of transition — it may differ from the group's current columns, and sprint stages are not part of the group kanban. To analyze past transitions, rely on the value from the history rather than on this reference.

See also