For AI agents: markdown of this page — /docs-content-en/tasks/move-stage.md documentation index — /llms.txt

Move a task with ordering

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

Bitrix24 REST: task.stages.movetask. Scope: task.

Body: stageId, beforeTaskId? or afterTaskId? (never both). Stage must belong to the task group or the key owner My Plan. The ordering task must belong to the same group or My Plan; a foreign stage/task gives 400. Returns {taskId,stageId,moved:true}. Missing record: 404. A My Plan move is checked with STAGES_ID; if Bitrix24 returned true but did nothing, the wrapper returns 409 TASK_NOT_IN_PLAN. It does not add tasks to My Plan.

Group card ordering is shared by all members. For Scrum use POST /v1/scrum/sprints/:sprintId/kanban/tasks/:taskId: the legacy upstream method may complete a task when moving to a final sprint stage and ignores ordering. My Plan position is independent of the task stageId; verify it with GET /v1/tasks?filter[stagesId]=.

Example

Terminal

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

Writes require a READWRITE key. No automatic retry after timeout: reread the object before retrying. Bitrix24 permission refusals return 403; other business refusals return 422.

Stage list