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:

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

See also