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

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

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
ParameterentityId (path) Typenumber Requiredyes DescriptionWorkgroup ID, or 0 for the key owner's My Plan. List of groups: GET /v1/workgroups

Request fields (body)

Field Type Required Description
Fieldtitle Typestring Requiredyes DescriptionStage name. An empty string and a whitespace-only string are rejected
Fieldcolor Typestring Requiredno DescriptionColor in RRGGBB or #RRGGBB format. Stored without #
FieldafterStageId Typenumber Requiredno DescriptionID 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
Fieldposition Typestring Requiredno DescriptionThe 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created stage
Fielddata.id Typenumber DescriptionStage ID
Fielddata.title Typestring DescriptionName
Fielddata.sort Typenumber DescriptionPosition on the board: the lower the value, the further left
Fielddata.color Typestring DescriptionColor in RRGGBB format
Fielddata.systemType Typestring | null DescriptionNEW for the default stage, null for the others
Fielddata.entityId Typenumber DescriptionKanban owner: group ID, or user ID for My Plan
Fielddata.entityType Typestring DescriptionG — 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
HTTP400 CodeINVALID_PARAMS DescriptionentityId is not a non-negative integer, or the body has other fields: Invalid entityId or body fields
HTTP400 CodeINVALID_PARAMS Descriptiontitle is missing or empty, or color or afterStageId has an invalid format: A non-empty title and valid color/afterStageId are required
HTTP400 CodeINVALID_PARAMS Descriptionposition is not first: position must be first
HTTP400 CodeINVALID_PARAMS DescriptionBoth afterStageId and position are passed: Use either position or afterStageId
HTTP400 CodeINVALID_PARAMS DescriptionafterStageId is 0: Use position:first to make the default stage
HTTP400 CodeINVALID_PARAMS DescriptionafterStageId belongs to a different kanban: afterStageId must belong to this entity
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 has neither the task nor the tasks scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo group with this entityId exists, or the key's user has no rights to its kanban
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not return a stage ID: Bitrix24 did not return a created stage id; reread stages before retrying
HTTP422 CodeBITRIX_ERROR DescriptionThe created stage was not found on reread: Created stage was not found on readback; reread stages before retrying
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 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