# 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](/docs/entities/tasks) section.

**Scope:** `task` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`

[Quick start](#quick-start) | [Full example](#full-example-a-new-stage-and-moving-tasks) | [Endpoint reference](#endpoint-reference) | [Error codes](#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`](/docs/task-stages/list) |
| My Plan | the key owner's personal kanban | `entityId` equals `0` | the `filter[stagesId]` filter in the [task list](/docs/entities/tasks/list) |
| Day plan | the key owner's personal list for the day | manually in the workday widget | [`GET /v1/tasks/day-plan`](/docs/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:

```bash
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`](/docs/entities/workgroups/list) 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](/docs/task-stages/update) and [delete](/docs/task-stages/delete) pages.

## Endpoint reference

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|----------|
| GET | [`/v1/tasks/stages/:entityId`](/docs/task-stages/list) | task.stages.get | Stages of a group kanban or My Plan |
| POST | [`/v1/tasks/stages/:entityId`](/docs/tasks/stages) | task.stages.add | Create a stage |
| PATCH | [`/v1/task-stages/:stageId`](/docs/task-stages/update) | task.stages.update | Update a stage |
| DELETE | [`/v1/task-stages/:stageId`](/docs/task-stages/delete) | task.stages.delete | Delete an empty stage |
| POST | [`/v1/tasks/:taskId/move-stage`](/docs/tasks/move-stage) | task.stages.movetask | Move a task with ordering |
| GET | [`/v1/tasks/stages/:entityId/can-move`](/docs/tasks/stages-can-move) | task.stages.canmovetask | Permission to sort a group kanban |
| GET | [`/v1/tasks/day-plan`](/docs/tasks/day-plan) | task.planner.getlist | The key owner's day plan |

A [task update](/docs/entities/tasks/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](/docs/errors).

## See also

- [Tasks](/docs/entities/tasks)
- [Task change history](/docs/task-history)
- [Scrum kanban stages](/docs/scrum/stages)
- [Workgroups](/docs/entities/workgroups)
- [Workday](/docs/workday)