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

Scrum kanban stages

The columns of a sprint board: creating, reading and updating. Stages belong to a sprint, not to a workgroup — different sprints in the same project have independent sets of columns.

Scope: task | Base URL: https://vibecode.bitrix24.com/v1 | Auth: X-Api-Key

How to obtain a `sprintId`

Every stage operation needs a sprint ID. Obtain it from the sprint list or request the project's active sprint.

List stages

GET /v1/scrum/sprints/:sprintId/stages

Returns the columns of one sprint board. A planned sprint whose board does not exist yet returns an empty array — that is not an error.

Path parameters

Parameter Type Required Description
sprintId number yes Sprint ID. Obtain with GET /v1/scrum/sprints?groupId=N

Examples

curl — personal key

Terminal 
curl https://vibecode.bitrix24.com/v1/scrum/sprints/11/stages \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/scrum/sprints/11/stages \
  -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/scrum/sprints/11/stages', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log(data.map((stage) => stage.name))

Response fields

Field Type Description
id number Stage ID
name string Column name
type string NEW, WORK or FINISH
sort number Column order
color string Color, six characters without #
sprintId number Sprint ID

Bitrix24 returns these fields as strings; the platform converts id, sort and sprintId to numbers. A value that is not a decimal integer arrives as null.

Response example

JSON 
{
    "success": true,
    "data": [
        { "id": 431, "name": "New", "sort": 100, "type": "NEW", "sprintId": 11, "color": "00C4FB" },
        { "id": 433, "name": "In progress", "sort": 200, "type": "WORK", "sprintId": 11, "color": "47D1E2" },
        { "id": 435, "name": "Done", "sort": 300, "type": "FINISH", "sprintId": 11, "color": "75D900" }
    ]
}

Errors

HTTP Code Description
400 INVALID_PARAMS sprintId is not a positive integer
404 ENTITY_NOT_FOUND No sprint with this ID exists
422 BITRIX_ERROR Bitrix24 returned an error the platform could not map to any of the other codes in this table; a permission refusal does NOT land here — it arrives as 403 BITRIX_ACCESS_DENIED
403 BITRIX_ACCESS_DENIED The Bitrix24 user the key acts as has no access to the sprint's scrum project
403 SCOPE_DENIED The key lacks the task scope
401 TOKEN_MISSING The key has no tokens configured

The full list of common API errors — Errors.

Known specifics

  • It must be a sprintId. Bitrix24 does not accept a workgroup or backlog ID and answers 404; the message does not hint that an ID of a different kind was passed.

See also