Para agentes de IA: markdown desta página — /docs-content-en/tasks.md índice da documentação — /llms.txt
Os artigos da documentação estão disponíveis atualmente em inglês.
Tasks: kanban, My Plan and the day plan
Stages of a workgroup kanban and of the personal My Plan, moving tasks between stages with ordering, and reading the day plan. The tasks themselves are read and changed in the Tasks section.
Scope: task | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key
Quick start | Full example | Endpoint reference | Error codes
A task can sit in three independent places, and each one is read differently:
| What | Whose | How it is set | How it is read |
|---|---|---|---|
| WhatGroup kanban | Whoseshared by all group members | How it is setentityId — group ID |
How it is readthe task's stageId field, GET /v1/tasks/stages/:entityId |
| WhatMy Plan | Whosethe key owner's personal kanban | How it is setentityId equals 0 |
How it is readthe filter[stagesId] filter in the task list |
| WhatDay plan | Whosethe key owner's personal list for the day | How it is setmanually in the workday widget | How it is readGET /v1/tasks/day-plan |
Moving a task in My Plan does not change the task's stageId in the group, and the day plan is not linked to either board.
Quick start
Read the stages of the key owner's My Plan:
curl "https://vibecode.bitrix24.com/v1/tasks/stages/0" \
-H "X-Api-Key: YOUR_API_KEY"
{
"success": true,
"data": [
{
"id": 489,
"title": "Not planned",
"sort": 100,
"color": "00C4FB",
"systemType": "NEW",
"entityId": 1317,
"entityType": "U"
},
{
"id": 491,
"title": "This week",
"sort": 200,
"color": "47D1E2",
"systemType": null,
"entityId": 1317,
"entityType": "U"
}
]
}
For a group kanban, pass the group ID from GET /v1/workgroups instead of 0.
Full example: a new stage and moving tasks
The scenario adds a stage to a group kanban, moves two tasks onto it in the required order, reads the board and removes the stage. Substitute the ID of your group and of two of its tasks.
const VIBE_URL = 'https://vibecode.bitrix24.com'
const VIBE_API_KEY = process.env.VIBE_API_KEY
const GROUP_ID = 155 // workgroup ID, GET /v1/workgroups
const TASK_ID = 4127 // the task of this group being moved
const ANCHOR_ID = 4125 // the task it will be placed before
async function api(method, path, body) {
const res = await fetch(`${VIBE_URL}/v1${path}`, {
method,
headers: { 'X-Api-Key': VIBE_API_KEY, 'Content-Type': 'application/json' },
body: body ? JSON.stringify(body) : undefined,
})
const json = res.status === 204 ? null : await res.json()
if (!res.ok) throw new Error(`${method} ${path}: ${json?.error?.code} ${json?.error?.message}`)
return json?.data
}
// Step 1. Make sure the key's user can sort the group kanban.
const { canMove } = await api('GET', `/tasks/stages/${GROUP_ID}/can-move`)
if (!canMove) throw new Error('No permission to move tasks in this group kanban')
// Step 2. Add a stage to the end of the kanban.
const stage = await api('POST', `/tasks/stages/${GROUP_ID}`, { title: 'Pending approval', color: 'FF8800' })
console.log('New stage:', stage.id, stage.title)
// Step 3. Move the tasks to the new stage. The anchor task must be on
// the same board, so move it first, then place the second one before it.
await api('POST', `/tasks/${ANCHOR_ID}/move-stage`, { stageId: stage.id })
await api('POST', `/tasks/${TASK_ID}/move-stage`, { stageId: stage.id, beforeTaskId: ANCHOR_ID })
// Step 4. Re-read the board: stages come in ascending sort order.
const stages = await api('GET', `/tasks/stages/${GROUP_ID}`)
for (const s of stages) console.log(s.sort, s.id, s.title, s.systemType ?? '')
// Step 5. Remove the stage. Only an empty stage can be deleted, so first
// move the tasks to the first stage of the board.
const first = stages[0]
await api('POST', `/tasks/${TASK_ID}/move-stage`, { stageId: first.id })
await api('POST', `/tasks/${ANCHOR_ID}/move-stage`, { stageId: first.id })
await api('DELETE', `/task-stages/${stage.id}`)
console.log('Stage deleted')
The first stage of the board is the default stage with systemType: NEW. It cannot be deleted, and when the first stage changes, tasks without a stage stay assigned to the former first stage. Details are on the stage update and delete pages.
Endpoint reference
| Method | Path | Bitrix24 method | Description |
|---|---|---|---|
| MethodGET | Path/v1/tasks/stages/:entityId |
Bitrix24 methodtask.stages.get | DescriptionStages of a group kanban or My Plan |
| MethodPOST | Path/v1/tasks/stages/:entityId |
Bitrix24 methodtask.stages.add | DescriptionCreate a stage |
| MethodPATCH | Path/v1/task-stages/:stageId |
Bitrix24 methodtask.stages.update | DescriptionUpdate a stage |
| MethodDELETE | Path/v1/task-stages/:stageId |
Bitrix24 methodtask.stages.delete | DescriptionDelete an empty stage |
| MethodPOST | Path/v1/tasks/:taskId/move-stage |
Bitrix24 methodtask.stages.movetask | DescriptionMove a task with ordering |
| MethodGET | Path/v1/tasks/stages/:entityId/can-move |
Bitrix24 methodtask.stages.canmovetask | DescriptionPermission to sort a group kanban |
| MethodGET | Path/v1/tasks/day-plan |
Bitrix24 methodtask.planner.getlist | DescriptionThe key owner's day plan |
A task update with the stageId field also changes the task's stage in the group kanban, but without ordering and only within the task's group.
Error codes
Section errors
| HTTP | Code | Description |
|---|---|---|
| HTTP400 | CodeINVALID_PARAMS |
DescriptionParameter or body validation failed. The conditions are listed on each method's page |
| HTTP404 | CodeENTITY_NOT_FOUND |
DescriptionNo task or stage with this ID |
| HTTP409 | CodeTASK_NOT_IN_PLAN |
DescriptionA move in My Plan, but the task is not in the key owner's plan |
| HTTP409 | CodeSTAGE_NOT_EMPTY |
DescriptionDeleting a stage that contains tasks |
| HTTP409 | CodeSTAGE_IS_SYSTEM |
DescriptionDeleting the first stage of the board |
System errors
| HTTP | Code | Description |
|---|---|---|
| HTTP400 | CodeUNSUPPORTED_FILTER |
DescriptionA filter was passed in the stages request: the stage list is always returned in full |
| 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 |
DescriptionA read-only key attempted a create, update, delete or move |
| HTTP403 | CodeBITRIX_ACCESS_DENIED |
DescriptionThe key's user has no permissions for the group or the task |
| HTTP422 | CodeBITRIX_ERROR |
DescriptionBitrix24 rejected the request or did not confirm the change |
| HTTP502 | CodeBITRIX_ERROR |
DescriptionBitrix24 returned an unexpectedly structured response to the permission check or the day plan read |
Full list of common API errors — Errors.