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, and 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
ParametersprintId Typenumber Requiredyes DescriptionSprint ID. Obtain with GET /v1/scrum/sprints?groupId=N

Request body

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionColumn name. Up to 255 characters
Fieldtype Typestring Requiredno DescriptionNEW, WORK or FINISH. Defaults to WORK
Fieldsort Typenumber Requiredno DescriptionColumn order. Defaults to 100
Fieldcolor Typestring Requiredno DescriptionSix 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/23/stages \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "In review", "type": "WORK", "sort": 250 }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/scrum/sprints/23/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", "sort": 250 }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/sprints/23/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)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/sprints/23/stages', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    '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 fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on successful creation, HTTP status 201
Fielddata.id Typenumber DescriptionID of the created column
Fielddata.name Typestring DescriptionColumn name
Fielddata.sort Typenumber DescriptionColumn order
Fielddata.type Typestring DescriptionNEW, WORK or FINISH
Fielddata.sprintId Typenumber DescriptionSprint ID from the request path
Fielddata.color Typestring DescriptionSix hexadecimal characters without #. Defaults to 00C4FB if color is not sent

If the column cannot be re-read, data contains only id — the column itself is created either way.

Response example

No color was sent in the request, so the response carries the default value:

JSON 
{
  "success": true,
  "data": {
    "id": 641,
    "name": "In review",
    "sort": 250,
    "type": "WORK",
    "sprintId": 23,
    "color": "00C4FB"
  }
}

Error response example

404 — no sprint with this ID:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Sprint not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionname missing, name longer than 255 characters, type outside the set, color longer than six characters, or sprintId sent in the body
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo sprint with this ID exists
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 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
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe Bitrix24 user the key acts as has no access to the sprint's scrum project
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the task scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP401 CodeTOKEN_MISSING DescriptionThe 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, responds 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