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

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

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
taskId (path) number yes ID of the task to move. List: GET /v1/tasks

Request fields (body)

Field Type Required Description
stageId number yes ID 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
beforeTaskId number no ID 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
afterTaskId number no ID 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
success boolean Always true on success
data object Move result
data.taskId number ID of the moved task
data.stageId number ID of the stage the task ended up on
data.moved boolean Always 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
400 INVALID_PARAMS taskId or stageId is not a positive integer, or the body has other fields: taskId and stageId must be positive integers
400 INVALID_PARAMS Both beforeTaskId and afterTaskId are sent: Use either beforeTaskId or afterTaskId
400 INVALID_PARAMS The ordering task is the task being moved or is not a positive integer: The ordering task must be a different positive task id
400 INVALID_PARAMS The stage belongs neither to the task's group kanban nor to My Plan: stageId must belong to the task group or your My Plan
400 INVALID_PARAMS Moving on the group kanban, and the ordering task is from another group or does not exist: Ordering task must belong to the same group
400 INVALID_PARAMS Moving on My Plan, and the ordering task is not in it: Ordering task must belong to your My Plan
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 The key's user has no permission for the task or the group kanban
404 ENTITY_NOT_FOUND No task with this taskId: Task was not found
409 TASK_NOT_IN_PLAN Moving 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
422 BITRIX_ERROR Bitrix24 did not confirm the move: Bitrix24 did not confirm the move; reread the task before retrying
422 BITRIX_ERROR After 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
422 BITRIX_ERROR Bitrix24 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