## List checklist items

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

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

## Parameters

| Parameter | Type | Req. | Description |
|----------|-----|:-----:|---------|
| `taskId` (path) | integer | yes | Task ID |
| `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` / `desc` (default `asc`). Without the parameter, Bitrix24 sorts by `id` descending |
| `start` (query) | integer | no | Offset in the result set. Bitrix24 returns pages of 50 items — for the next page pass `start=50`, then `100`, and so on |

## 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 | Parent item ID. `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 | Item author |
| `data[].toggledBy` | string \| null | Who last changed the completion status |
| `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 }` |
| `data[].attachments` | array | Attached files |
| `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

`422` — the task does not exist or is not accessible:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "TASKS_ERROR_EXCEPTION_#8; Action failed; 8/TE/ACTION_FAILED_TO_BE_PROCESSED",
    "b24Code": "ERROR_CORE"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `taskId` is not a positive integer, or an unknown sort field |
| 422 | `BITRIX_ERROR` | The task with the given `taskId` does not exist or is not accessible to the key — Bitrix24 threw an exception. An existing task with no items answers `200` with an empty array |
| 403 | `SCOPE_DENIED` | The API key lacks the `task` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

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

## Known specifics

- **`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)
- [Tasks](/docs/entities/tasks)