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

Update a stage

PATCH /v1/scrum/stages/:stageId

Renames, recolors and reorders a column. Partial update — send only what changes.

The path carries no sprint segment: Bitrix24 identifies a column by stageId alone.

Path parameters

Parameter Type Required Description
ParameterstageId Typenumber Requiredyes DescriptionStage ID. Obtain with GET /v1/scrum/sprints/:sprintId/stages

Request body

Field Type Required Description
Fieldname Typestring Requiredno DescriptionColumn name. Up to 255 characters
Fieldtype Typestring Requiredno DescriptionNEW, WORK or FINISH
Fieldsort Typenumber Requiredno DescriptionColumn order
Fieldcolor Typestring Requiredno DescriptionSix hexadecimal characters. A leading # is stripped

At least one field is required. The sprintId field is rejected.

Examples

curl — personal key

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/scrum/stages/641 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Under review", "color": "47D1E2" }'

curl — OAuth application

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/scrum/stages/641 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Under review", "color": "47D1E2" }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/stages/641', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Under review', color: '47D1E2' }),
})

const { data } = await res.json()
console.log(data.updated)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/stages/641', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Under review', color: '47D1E2' }),
})

const { data } = await res.json()
console.log(data.updated)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful update
Fielddata.updated Typeboolean DescriptionAlways true in a successful response

The response does not carry the column itself. For current values, see List stages.

Response example

JSON 
{
  "success": true,
  "data": {
    "updated": true
  }
}

Error response example

404 — the stage does not exist or belongs to a scrum project you cannot access:

JSON 
{
  "success": false,
  "error": {
    "code": "STAGE_NOT_FOUND_OR_NO_ACCESS",
    "message": "Stage 999999 does not exist, or it belongs to a scrum project you cannot access."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionEmpty body, stageId is not a positive integer, sprintId sent, or a value failed validation
HTTP404 CodeSTAGE_NOT_FOUND_OR_NO_ACCESS DescriptionThe stage does not exist or belongs to a scrum project you cannot access
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

  • STAGE_NOT_FOUND_OR_NO_ACCESS merges two causes on purpose. Bitrix24 answers "no such stage" and "the stage exists but is not yours" identically, so the two cannot be told apart. A separate code for the second case would confirm that someone else's column exists.
  • Moving to another sprint is not exposed. Bitrix24 can do it, but the column then silently disappears from a live board. Create the column in the target sprint instead.

See also