Para agentes de IA: markdown de esta página — /docs-content-en/tasks/stages.md índice de la documentación — /llms.txt

Los artículos de la documentación están disponibles actualmente en inglés.

Create a task stage

POST /v1/tasks/stages/:entityId

Adds a stage to a workgroup kanban or to the key owner's My Plan. By default, the stage goes last.

Parameters

Parameter Type Required Description
entityId (path) number yes Workgroup ID, or 0 for the key owner's My Plan. List of groups: GET /v1/workgroups

Request fields (body)

Field Type Required Description
title string yes Stage name. An empty string and a whitespace-only string are rejected
color string no Color in RRGGBB or #RRGGBB format. Stored without #
afterStageId number no ID of a stage in the same kanban after which the new one is placed. List: GET /v1/tasks/stages/:entityId. Cannot be passed together with position
position string no The only value is first: the stage goes first and becomes the default stage. Cannot be passed together with afterStageId

Any other body fields, including sort, are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/stages/155" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Pending approval", "color": "#FF0000"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/stages/155" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Pending approval", "color": "#FF0000"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/stages/155', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ title: 'Pending approval', color: '#FF0000' }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/stages/155', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ title: 'Pending approval', color: '#FF0000' }),
})

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

Response fields

The response comes with HTTP status 201 Created. The stage in the response is reread after creation.

Field Type Description
success boolean Always true on success
data object The created stage
data.id number Stage ID
data.title string Name
data.sort number Position on the board: the lower the value, the further left
data.color string Color in RRGGBB format
data.systemType string | null NEW for the default stage, null for the others
data.entityId number Kanban owner: group ID, or user ID for My Plan
data.entityType string G — group kanban, U — My Plan

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 629,
    "title": "Pending approval",
    "sort": 400,
    "color": "FF0000",
    "systemType": null,
    "entityId": 155,
    "entityType": "G"
  }
}

Error response example

400 — both afterStageId and position are passed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Use either position or afterStageId"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS entityId is not a non-negative integer, or the body has other fields: Invalid entityId or body fields
400 INVALID_PARAMS title is missing or empty, or color or afterStageId has an invalid format: A non-empty title and valid color/afterStageId are required
400 INVALID_PARAMS position is not first: position must be first
400 INVALID_PARAMS Both afterStageId and position are passed: Use either position or afterStageId
400 INVALID_PARAMS afterStageId is 0: Use position:first to make the default stage
400 INVALID_PARAMS afterStageId belongs to a different kanban: afterStageId must belong to this entity
401 MISSING_API_KEY The X-Api-Key header is missing
401 TOKEN_MISSING The key has no valid Bitrix24 token
403 SCOPE_DENIED The key has neither the task nor the tasks scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only
403 BITRIX_ACCESS_DENIED No group with this entityId exists, or the key's user has no rights to its kanban
422 BITRIX_ERROR Bitrix24 did not return a stage ID: Bitrix24 did not return a created stage id; reread stages before retrying
422 BITRIX_ERROR The created stage was not found on reread: Created stage was not found on readback; reread stages before retrying
422 BITRIX_ERROR Bitrix24 rejected the creation, text in message

Full list of common API errors: Errors.

Known specifics

  • The default stage changes for the whole group. The systemType: NEW flag moves from the previous first stage to the new one. New group tasks and tasks without a stage land in the default stage. The order and the default stage are shared by all group members.
  • sort of neighboring stages is recalculated. After a stage is inserted in the middle or at the start, Bitrix24 renumbers the sort values of all stages on the board in steps of 100. Previously saved sort values become stale, so reread the stages.

See also