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:

Terminal
curl "https://vibecode.bitrix24.com/v1/tasks/stages/0" \
  -H "X-Api-Key: YOUR_API_KEY"
JSON
{
  "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.

javascript
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.

See also