# Task checklist

Task checklist items are a nested resource of a task. Each item has a title, a completion status, an importance flag, a sort order, members, and (optionally) a parent item for nested checklists. The base path is `/v1/tasks/:taskId/checklist`. Every operation is addressed by the task identifier `:taskId`.

Bitrix24 API: `task.checklistitem.*`
Scope: `task`

> **Why a separate resource.** The `CHECKLIST` field is not accepted in the body of `POST /v1/tasks` — a checklist cannot be created together with the task. Saving the whole checklist, reordering items, and adding members and attachments are done with [checklist actions](./checklist-actions.md).

## Operations

- [List items](./checklist/list.md) — `GET /v1/tasks/:taskId/checklist`
- [Get an item](./checklist/get.md) — `GET /v1/tasks/:taskId/checklist/:itemId`
- [Add an item](./checklist/create.md) — `POST /v1/tasks/:taskId/checklist`
- [Update an item](./checklist/update.md) — `PATCH /v1/tasks/:taskId/checklist/:itemId`
- [Delete an item](./checklist/delete.md) — `DELETE /v1/tasks/:taskId/checklist/:itemId`
- [Mark complete](./checklist/complete.md) — `POST /v1/tasks/:taskId/checklist/:itemId/complete`
- [Reopen](./checklist/renew.md) — `POST /v1/tasks/:taskId/checklist/:itemId/renew`

## Item fields

| Field | Type | Read-only | Description |
|------|-----|:---:|---------|
| `title` | string | | Item text. **Required on creation.** If `parentId = 0`, `title` becomes the name of the new checklist |
| `sortIndex` | integer | | Sort index. The smaller the value, the higher the item appears in the list |
| `isComplete` | boolean / `Y`,`N` | | Completion status. Accepts `true`/`false` or `"Y"`/`"N"` on write. Returned as `"Y"`/`"N"` |
| `isImportant` | boolean / `Y`,`N` | | Importance flag. Same format as `isComplete` |
| `parentId` | integer | | ID of the parent item for nested checklists. **`0` creates a new checklist** in the task |
| `members` | object (request) / array (response) | | Item members — the write and read shapes differ, see "Known specifics" below |
| `id` | string | yes | Item ID |
| `taskId` | string | yes | Parent task ID |
| `createdBy` | string | yes | Item author |
| `toggledBy` | string | yes | Who last changed the completion status |
| `toggledDate` | string | yes | When the status was last changed |
| `attachments` | array / object | yes | Item attachments: an empty array or an object keyed by attachment ID. Added with [checklist actions](./checklist-actions.md) |

## Known specifics

- **A missing task returns `404 TASK_NOT_FOUND`.** When Bitrix24 reports `TASK_NOT_FOUND_OR_NOT_ACCESSIBLE`, every route in this family maps it to this code. Scope refusals and throttling keep their own status. Some Bitrix24 write operations return success without checking the task, so successfully updating, completing, reopening or deleting an item does not confirm that the task or item exists.
- **Case and types in the response.** Responses arrive in camelCase (`id`, `taskId`, `sortIndex`, `isComplete`). Bitrix24 serializes numeric values as **strings** (`"id": "477"`, `"sortIndex": "2"`) — convert via `Number(value)` for arithmetic. The `isComplete` / `isImportant` flags are the strings `"Y"` / `"N"`, not booleans.
- **`members` has different shapes on write and read.** When creating or updating an item, `members` is an object of the form `{ "<userId>": { "type": "A" | "U" } }` (`A` — co-assignee, `U` — observer, employee list — [`GET /v1/users`](/docs/entities/users)). In the response (list, get) `members` is an **array** of enriched member objects: `[{ "id", "type", "name", "personalPhoto", "personalGender", "image", "isCollaber" }]`. Code that reads members from a response must not expect the request shape.
- **An item without an explicit `parentId` can land inside an existing checklist automatically.** If the task already has a checklist container (an item with `parentId: 0`), Bitrix24 assigns that container as the parent of items created without an explicit `parentId`, instead of leaving them at the top level.

## Typical scenario

1. Create a task: [`POST /v1/tasks`](../tasks/create.md).
2. (Optional) create a checklist container: [`POST /v1/tasks/:taskId/checklist`](./checklist/create.md) with `parentId: 0`.
3. Add items: [`POST /v1/tasks/:taskId/checklist`](./checklist/create.md) (one at a time).
4. Mark an item complete: [`POST /v1/tasks/:taskId/checklist/:itemId/complete`](./checklist/complete.md).
5. Check progress: [`GET /v1/tasks/:taskId/checklist`](./checklist/list.md).

## Limits

| Limit | Value |
|-------|-------|
| Items per call | Create, update, delete, mark complete and reopen — one item. To save the whole checklist in one call, see [Save a task checklist](./checklist-actions/tree.md) |
| Request body size | 1 MiB |
| Request rate | Common API limits — [Limits and optimization](/docs/optimization) |

## See also

- [Checklist actions and task file](./checklist-actions.md)
- [Tasks](../tasks.md)
- [Time tracking](./time.md)
- [Task comments](/docs/entities/task-comments)
- [Employees](/docs/entities/users)
- [Limits and optimization](/docs/optimization)