Para agentes de IA: markdown de esta página — /docs-content-en/tasks.md índice de la documentación — /llms.txt
Los artículos de la documentación están disponibles actualmente en 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 |
|---|---|---|---|
| Group kanban | shared by all group members | entityId — group ID |
the task's stageId field, GET /v1/tasks/stages/:entityId |
| My Plan | the key owner's personal kanban | entityId equals 0 |
the filter[stagesId] filter in the task list |
| Day plan | the key owner's personal list for the day | manually in the workday widget | GET /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 |
|---|---|---|---|
| GET | /v1/tasks/stages/:entityId |
task.stages.get | Stages of a group kanban or My Plan |
| POST | /v1/tasks/stages/:entityId |
task.stages.add | Create a stage |
| PATCH | /v1/task-stages/:stageId |
task.stages.update | Update a stage |
| DELETE | /v1/task-stages/:stageId |
task.stages.delete | Delete an empty stage |
| POST | /v1/tasks/:taskId/move-stage |
task.stages.movetask | Move a task with ordering |
| GET | /v1/tasks/stages/:entityId/can-move |
task.stages.canmovetask | Permission to sort a group kanban |
| GET | /v1/tasks/day-plan |
task.planner.getlist | The 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 |
|---|---|---|
| 400 | INVALID_PARAMS |
Parameter or body validation failed. The conditions are listed on each method's page |
| 404 | ENTITY_NOT_FOUND |
No task or stage with this ID |
| 409 | TASK_NOT_IN_PLAN |
A move in My Plan, but the task is not in the key owner's plan |
| 409 | STAGE_NOT_EMPTY |
Deleting a stage that contains tasks |
| 409 | STAGE_IS_SYSTEM |
Deleting the first stage of the board |
System errors
| HTTP | Code | Description |
|---|---|---|
| 400 | UNSUPPORTED_FILTER |
A filter was passed in the stages request: the stage list is always returned in full |
| 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 |
A read-only key attempted a create, update, delete or move |
| 403 | BITRIX_ACCESS_DENIED |
The key's user has no permissions for the group or the task |
| 422 | BITRIX_ERROR |
Bitrix24 rejected the request or did not confirm the change |
| 502 | BITRIX_ERROR |
Bitrix24 returned an unexpectedly structured response to the permission check or the day plan read |
Full list of common API errors — Errors.