لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/task-stages/update.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Update a task stage

PATCH /v1/task-stages/:stageId

Changes the title, color or position of a stage in a workgroup kanban or in My Plan.

Parameters

Parameter Type Required Description
ParameterstageId (path) Typenumber Requiredyes DescriptionStage ID. List: GET /v1/tasks/stages/:entityId

Request fields (body)

Field Type Required Description
Fieldtitle Typestring Requiredno DescriptionNew title. An empty string and a whitespace-only string are refused
Fieldcolor Typestring Requiredno DescriptionColor in RRGGBB or #RRGGBB format. Stored without #
FieldafterStageId Typenumber Requiredno DescriptionID of a stage on the same kanban; the updated stage is placed after it. 0 places the stage first and makes it the default stage

At least one field is required. An empty body and any other fields, including sort, are refused with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/task-stages/629" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Approval", "color": "FF8800"}'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/task-stages/629" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Approval", "color": "FF8800"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/task-stages/629', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ title: 'Approval', color: 'FF8800' }),
})

const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/task-stages/629', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ title: 'Approval', color: 'FF8800' }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionUpdate result
Fielddata.id Typenumber DescriptionID of the updated stage
Fielddata.updated Typeboolean DescriptionAlways true

The response does not contain the stage itself. Read the new values and order with GET /v1/tasks/stages/:entityId.

Response example

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

Error response example

400 — an empty body or a field not listed in the table, for example sort:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Provide title, color or afterStageId; unsupported fields are refused"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionstageId is not a positive integer, the body is empty, the body contains other fields, title is empty, color has an invalid format, or afterStageId is not a non-negative integer: Provide title, color or afterStageId; unsupported fields are refused
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no valid Bitrix24 token
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the task or tasks scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no rights to the group kanban
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo stage with this stageId exists. The message text comes from Bitrix24 in the Bitrix24 account language
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not confirm the update: Bitrix24 did not confirm the update; reread stages before retrying
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused the update; the reason is in message

Full list of common API errors: Errors.

Known specifics

  • afterStageId: 0 assigns tasks without a stage to the previous default stage. Group tasks that had no stage (stageId: 0) get the stage that was first before the update. No move entry appears in the history of these tasks.
  • afterStageId from another kanban does not return an error. The response is 200, and the stage moves to the end of its own board.
  • sort values of neighboring stages are recalculated. After a stage is moved, Bitrix24 renumbers the sort values of all stages on the board in steps of 100.

See also