## List checklist items

`GET /v1/tasks/:taskId/checklist`

Returns all items of a task's checklist, including nested (child) items.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `taskId` (path) | integer | yes | Task ID. List: [`GET /v1/tasks`](/docs/entities/tasks/list) |
| `sort` (query) | string | no | Sorting in the `field:direction` format, for example `sortIndex:asc`. Fields: `id`, `parentId`, `createdBy`, `title`, `sortIndex`, `isComplete`, `isImportant`, `toggledBy`, `toggledDate`. Direction: `asc` or `desc` (default `asc`). Without the parameter, items are ordered by `sortIndex` ascending, as with `sortIndex:asc` |
| `start` (query) | integer | no | Accepted but does not shift the result: any value returns every checklist item. Must be a non-negative integer, otherwise `400 INVALID_PARAMS` |

**Pagination.** There is no paging: all checklist items come in one response, and `meta.total` equals the number of elements in `data`.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/tasks/3943/checklist?sort=sortIndex:asc" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/tasks/3943/checklist?sort=sortIndex:asc" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch(
  "https://vibecode.bitrix24.com/v1/tasks/3943/checklist?sort=sortIndex:asc",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const { data } = await res.json();
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  "https://vibecode.bitrix24.com/v1/tasks/3943/checklist?sort=sortIndex:asc",
  {
    headers: {
      "X-Api-Key": "YOUR_APP_KEY",
      "Authorization": "Bearer USER_SESSION_TOKEN",
    },
  }
);
const { data } = await res.json();
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of checklist items |
| `data[].id` | string | Item ID |
| `data[].taskId` | string | Parent task ID |
| `data[].parentId` | integer / string | ID of the parent item from the same list. `0` — a top-level item (itself a checklist) |
| `data[].title` | string | Item text |
| `data[].sortIndex` | string | Sort index |
| `data[].isComplete` | string | Completion status — `"Y"` / `"N"` |
| `data[].isImportant` | string | Importance flag — `"Y"` / `"N"` |
| `data[].createdBy` | string | ID of the item author. Employee list: [`GET /v1/users`](/docs/entities/users/list) |
| `data[].toggledBy` | string \| null | ID of the employee who last changed the completion status. Employee list: [`GET /v1/users`](/docs/entities/users/list) |
| `data[].toggledDate` | string | When the status was last changed. An empty string if never changed |
| `data[].members` | array | Item members — objects `{ id, type, name, personalPhoto, personalGender, image, isCollaber }`. `id` — the employee ID from [`GET /v1/users`](/docs/entities/users/list) |
| `data[].attachments` | array \| object | Item attachments. Without attachments — an empty array. With attachments — an object keyed by attachment ID, each value an object with the fields `attachmentId`, `name`, `size`, `fileId` (the Drive file ID), `downloadUrl`, `viewUrl` |
| `meta.total` | number | Total number of items in the result set |

## Response example

```json
{
  "success": true,
  "data": [
    {
      "id": "211",
      "taskId": "3943",
      "parentId": 0,
      "createdBy": "1317",
      "title": "Documents",
      "sortIndex": "1",
      "isComplete": "N",
      "isImportant": "N",
      "toggledBy": null,
      "toggledDate": "",
      "members": [],
      "attachments": []
    },
    {
      "id": "213",
      "taskId": "3943",
      "parentId": "211",
      "createdBy": "1317",
      "title": "Collect and check documents",
      "sortIndex": "100",
      "isComplete": "N",
      "isImportant": "Y",
      "toggledBy": null,
      "toggledDate": "",
      "members": [
        {
          "id": "1317",
          "type": "A",
          "name": "Jane Doe",
          "personalPhoto": "35959",
          "personalGender": "",
          "image": "https://example.bitrix24.com/...",
          "isCollaber": false
        }
      ],
      "attachments": []
    }
  ],
  "meta": { "total": 2 }
}
```

## Error response example

`404` — Bitrix24 reported that the task does not exist or is not accessible:

```json
{
  "success": false,
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task not found or not accessible."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `taskId` is not a positive integer, the sort field is unknown, or `start` is not a non-negative integer |
| 404 | `TASK_NOT_FOUND` | Bitrix24 reported `TASK_NOT_FOUND_OR_NOT_ACCESSIBLE`: the task is missing or not accessible to the key |
| 422 | `BITRIX_ERROR` | Any other Bitrix24 error without a more specific error code |
| 429 | `RATE_LIMITED` | Bitrix24 throttled the request. Respect the `Retry-After` header |
| 403 | `SCOPE_DENIED` | The API key lacks the `task` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 400 | `UNSUPPORTED_FILTER` | A `filter` parameter was passed, and this endpoint has none. The error text names what to use instead |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **An existing task without items returns `200` with an empty array.**

- **`parentId: 0` — a top-level item that is itself a checklist.** Child items reference its `id` via their own `parentId`.
- **Numeric values and flags are strings.** `id`, `taskId`, `sortIndex` arrive as strings. `isComplete` / `isImportant` are the strings `"Y"`/`"N"`, not booleans.

## See also

- [Get an item](./get.md)
- [Add an item](./create.md)
- [Save a task checklist](/docs/entities/tasks/checklist-actions/tree)
- [Tasks](/docs/entities/tasks)