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, recolours 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
stageId number yes Stage ID. Obtain with GET /v1/scrum/sprints/:sprintId/stages

Request body

Field Type Required Description
name string no Column name. Up to 255 characters
type string no NEW, WORK or FINISH
sort number no Column order
color string no Six 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/561 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -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/561', {
  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)

Response example

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

The response does not carry the column itself: the Bitrix24 method does not report which sprint it belongs to, so it cannot be re-read without an extra request. For current values, see List stages.

Errors

HTTP Code Description
400 INVALID_PARAMS Empty body; stageId is not a positive integer; sprintId sent; a value failed validation
404 STAGE_NOT_FOUND_OR_NO_ACCESS The stage does not exist or belongs to a scrum project you cannot access
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

  • 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 sprint you mean instead.

See also