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

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

Move a task with ordering

POST /v1/tasks/:taskId/move-stage

Moves a task to a stage of its workgroup kanban or to a stage of the key owner's My Plan, and optionally places it before or after another task.

Parameters

Parameter Type Required Description
ParametertaskId (path) Typenumber Requiredyes DescriptionID of the task to move. List: GET /v1/tasks

Request fields (body)

Field Type Required Description
FieldstageId Typenumber Requiredyes DescriptionID of the target stage: a stage of the task's group kanban or a My Plan stage. List: GET /v1/tasks/stages/:entityId, with the group ID for a group and 0 for My Plan
FieldbeforeTaskId Typenumber Requiredno DescriptionID of the task the moved task is placed before. A task from the same group when moving on the group kanban, or from My Plan when moving on the plan. Not sent together with afterTaskId
FieldafterTaskId Typenumber Requiredno DescriptionID of the task the moved task is placed after. Same conditions as beforeTaskId. Not sent together with beforeTaskId

Any other body fields are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/4127/move-stage" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stageId": 625, "beforeTaskId": 4125}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/4127/move-stage" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stageId": 625, "beforeTaskId": 4125}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/4127/move-stage', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ stageId: 625, beforeTaskId: 4125 }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/4127/move-stage', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ stageId: 625, beforeTaskId: 4125 }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionMove result
Fielddata.taskId Typenumber DescriptionID of the moved task
Fielddata.stageId Typenumber DescriptionID of the stage the task ended up on
Fielddata.moved Typeboolean DescriptionAlways true: the move is verified by rereading the task

Response example

JSON 
{
  "success": true,
  "data": {
    "taskId": 4127,
    "stageId": 625,
    "moved": true
  }
}

Error response example

409 — the task is not in the key owner's My Plan, the move was not performed:

JSON 
{
  "success": false,
  "error": {
    "code": "TASK_NOT_IN_PLAN",
    "message": "The task is not in your My Plan and was not moved"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptiontaskId or stageId is not a positive integer, or the body has other fields: taskId and stageId must be positive integers
HTTP400 CodeINVALID_PARAMS DescriptionBoth beforeTaskId and afterTaskId are sent: Use either beforeTaskId or afterTaskId
HTTP400 CodeINVALID_PARAMS DescriptionThe ordering task is the task being moved or is not a positive integer: The ordering task must be a different positive task id
HTTP400 CodeINVALID_PARAMS DescriptionThe stage belongs neither to the task's group kanban nor to My Plan: stageId must belong to the task group or your My Plan
HTTP400 CodeINVALID_PARAMS DescriptionMoving on the group kanban, and the ordering task is from another group or does not exist: Ordering task must belong to the same group
HTTP400 CodeINVALID_PARAMS DescriptionMoving on My Plan, and the ordering task is not in it: Ordering task must belong to your My Plan
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 DescriptionThe key's user has no permission for the task or the group kanban
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo task with this taskId: Task was not found
HTTP409 CodeTASK_NOT_IN_PLAN DescriptionMoving on My Plan, and the task is not in the key owner's plan: The task is not in your My Plan and was not moved
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not confirm the move: Bitrix24 did not confirm the move; reread the task before retrying
HTTP422 CodeBITRIX_ERROR DescriptionAfter a move on the group kanban, the task is not on the requested stage: Bitrix24 did not move the task to the requested stage; reread the task before retrying
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the move, the reason is in message

Full list of common API errors: Errors.

Known specifics

  • My Plan is independent of the group kanban. A move on My Plan does not change the task's stageId in the group. Read the task's position in the plan by filtering the task list with filter[stagesId]=<stage ID>.
  • Tasks are not added to My Plan. The plan contains only tasks the key owner takes part in, for example as creator or assignee.
  • Group kanban ordering is shared. All group members see the cards in the same order, so beforeTaskId and afterTaskId change the board for everyone.
  • Scrum sprint tasks are moved by a different method. For a sprint board, use Scrum kanban stages.

See also