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

Create a stage

POST /v1/scrum/sprints/:sprintId/stages

Adds a column to a sprint board. sprintId comes from the path; sending it in the body is rejected.

Bitrix24 returns only an identifier, so the platform re-reads the created column and returns it in full — including the default values Bitrix24 filled in.

Path parameters

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

Request body

Field Type Required Description
name string yes Column name. Up to 255 characters
type string no NEW, WORK or FINISH. Defaults to WORK
sort number no Column order. Defaults to 100
color string no Six hexadecimal characters, e.g. "00C4FB". A leading # is accepted and stripped

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/scrum/sprints/11/stages \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "In review",
    "type": "WORK",
    "sort": 250,
    "color": "FFAA00"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/scrum/sprints/11/stages \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "In review", "type": "WORK" }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/sprints/11/stages', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'In review', type: 'WORK', sort: 250 }),
})

const { data } = await res.json()
console.log('Stage ID:', data.id)

Response example

JSON 
{
    "success": true,
    "data": {
        "id": 561,
        "name": "In review",
        "type": "WORK",
        "sort": 250,
        "color": "FFAA00",
        "sprintId": 11
    }
}

If the re-read fails, the response degrades to { "id": 561 } — the column itself is created either way.

Errors

HTTP Code Description
400 INVALID_PARAMS name missing; name longer than 255 characters; type outside the set; color longer than six characters; sprintId in the body
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
403 WRITE_BLOCKED_READONLY_KEY The key is read-only
401 TOKEN_MISSING The key has no tokens configured

The full list of common API errors — Errors.

Known specifics

  • Validation is stricter than Bitrix24's, deliberately. Bitrix24 accepts a name longer than 255 characters, a color longer than six characters and any type value, answers with success, and stores a truncated or substituted value. The platform refuses up front so you never get a column you did not ask for.
  • Adding to a completed sprint is allowed — Bitrix24 does not forbid it.

See also