# Checklist actions and task file

These methods save a task checklist in one call, mark an item complete together with its sub-items, reorder items, and add members and files. [Task checklist](./checklist.md) reads and changes the same items one at a time, but its responses have a different shape.

Bitrix24 API: `tasks.task.checklist.*`, `tasks.task.files.attach`
Scope: `task`

## Operations

- [Save a task checklist](./checklist-actions/tree.md) — `POST /v1/tasks/:taskId/checklist/tree`
- [Mark an item complete with its sub-items](./checklist-actions/complete-all.md) — `POST /v1/tasks/:taskId/checklist/:itemId/complete-all`
- [Move an item before another](./checklist-actions/move-before.md) — `POST /v1/tasks/:taskId/checklist/:itemId/move-before`
- [Move an item after another](./checklist-actions/move-after.md) — `POST /v1/tasks/:taskId/checklist/:itemId/move-after`
- [Add item members](./checklist-actions/members.md) — `POST /v1/tasks/:taskId/checklist/:itemId/members`
- [Attach a file to an item by content](./checklist-actions/attachments-content.md) — `POST /v1/tasks/:taskId/checklist/:itemId/attachments/content`
- [Attach Drive files to an item](./checklist-actions/attachments-disk.md) — `POST /v1/tasks/:taskId/checklist/:itemId/attachments/disk`
- [Remove item attachments](./checklist-actions/attachments-remove.md) — `POST /v1/tasks/:taskId/checklist/:itemId/attachments/remove`
- [Attach a file to a task](./files-attach.md) — `POST /v1/tasks/:taskId/files/attach`

## Key fields

Methods that act on a single item return the item in `data.checkListItem`, marking an item complete with its sub-items returns an array of items in `data`, and saving a checklist returns the items in `data.checkListItem.traversedItems`.

| Field | Description |
|------|----------|
| `id` | Item ID. Pass it as `itemId` in the path. Item list: [`GET /v1/tasks/:taskId/checklist`](/docs/entities/tasks/checklist/list) |
| `taskId` | Task ID. List: [`GET /v1/tasks`](/docs/entities/tasks/list). In the items of a saved checklist, the same value arrives in the `entityId` field |
| `parentId` | Parent item ID. `0` means a top-level item, which is also the checklist name |
| `title` | Item text |
| `sortIndex` | Position of the item among items with the same parent: the smaller the number, the higher the item |
| `isComplete` | Whether the item is complete — `true` or `false` |
| `members` | Item members. `type`: `A` — co-assignee, `U` — observer |
| `attachments` | Item attachments: an empty array or an object where the key is the attachment ID and the value is the Drive file ID prefixed with the letter `n` |

## What to know before you start

1. **These methods do not read items.** The item list and item IDs come from [`GET /v1/tasks/:taskId/checklist`](/docs/entities/tasks/checklist/list). There, numbers and flags arrive as strings — `"id": "268"`, `"isComplete": "Y"` — while the responses of the methods in this subsection use numbers and `true` / `false`.
2. **Saving replaces the whole checklist.** An item missing from the passed array is deleted, and an item without an `ID` is re-created with a new ID. If saving fails, some of the changes may already have been written — check the result in the [item list](/docs/entities/tasks/checklist/list).
3. **An item member becomes a task member.** Role `A` adds the employee to the task's co-assignees, and role `U` adds them to its observers. To remove a member from an item, [update the item](/docs/entities/tasks/checklist/update): the `members` field replaces the whole set. The employee remains a task member.
4. **A missing task or item returns `422` on the tested Bitrix24 accounts.** If the task or item does not exist, or the employee cannot see the task, the item methods return `422 BITRIX_ERROR`. The error text is in the Bitrix24 account language, for example `Access to task was denied`. The API specification declares `404 TASK_NOT_FOUND` and `404 NOT_FOUND` for this case, but they are not returned on the tested Bitrix24 accounts.
5. **A read-only key changes nothing.** Every method in this subsection rejects such a key with `403 WRITE_BLOCKED_READONLY_KEY`.
6. **The member removal method finds a member by position, not by ID.** `POST /v1/tasks/:taskId/checklist/:itemId/members/remove` matches the numbers in `membersIds` against positions in the item's `members` list, counted from `0`. A number lower than the member count removes whoever holds that position. An employee ID equal to or greater than the member count removes nobody. Both cases return `200`. To remove a member, [update the item](/docs/entities/tasks/checklist/update): the `members` field sets the final list in full.

## Typical scenario

1. Find the task: [`GET /v1/tasks`](/docs/entities/tasks/list).
2. Save the checklist in one call: [`POST /v1/tasks/:taskId/checklist/tree`](./checklist-actions/tree.md).
3. Reorder items: [before another item](./checklist-actions/move-before.md) or [after it](./checklist-actions/move-after.md).
4. Assign an item member: [`POST /v1/tasks/:taskId/checklist/:itemId/members`](./checklist-actions/members.md).
5. Attach a file [from Drive](./checklist-actions/attachments-disk.md) or [by content](./checklist-actions/attachments-content.md).
6. Close an item with all its sub-items: [`POST /v1/tasks/:taskId/checklist/:itemId/complete-all`](./checklist-actions/complete-all.md).
7. Check the result: [`GET /v1/tasks/:taskId/checklist`](/docs/entities/tasks/checklist/list).

## Limits

| Limit | Value |
|-------|----------|
| Items per call | Saving — the whole task checklist. Marking complete with sub-items — the item and all its sub-items. Other methods — one item |
| Request body size | 1 MiB, including the file content in base64 |
| Request rate | Common API limits — [Limits and optimization](/docs/optimization) |

## See also

- [Task checklist](./checklist.md)
- [Tasks](/docs/entities/tasks)
- [Files](/docs/entities/files)