## Add a checklist item

`POST /v1/tasks/:taskId/checklist`

Adds an item to a task's checklist. `title` is required. Returns the `id` of the new item.

## Parameters

| Parameter | Type | Req. | Description |
|----------|-----|:-----:|---------|
| `taskId` (path) | integer | yes | Task ID |

## Request fields (body)

| Field | Type | Req. | Description |
|------|-----|:-----:|---------|
| `title` | string | yes | Item text. If `parentId: 0`, becomes the name of the new checklist |
| `sortIndex` | integer | no | Sort index. The smaller the value, the higher the item appears in the list |
| `isImportant` | boolean / `Y`,`N` | no | Importance flag |
| `isComplete` | boolean / `Y`,`N` | no | Completion status at creation |
| `parentId` | integer | no | Parent item ID. `0` creates a new checklist container in the task |
| `members` | object | no | Item members: `{ "<userId>": { "type": "A" \| "U" } }`. `A` — co-assignee, `U` — observer. Employee list — [`GET /v1/users`](/docs/entities/users) |

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/3943/checklist" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Collect and check documents",
    "sortIndex": 100,
    "isImportant": true
  }'
```

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/3943/checklist" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Collect and check documents",
    "sortIndex": 100,
    "isImportant": true
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch("https://vibecode.bitrix24.com/v1/tasks/3943/checklist", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Collect and check documents",
    sortIndex: 100,
    isImportant: true,
  }),
});
const { data } = await res.json();
```

### JavaScript — OAuth application

```javascript
const res = await fetch("https://vibecode.bitrix24.com/v1/tasks/3943/checklist", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_APP_KEY",
    "Authorization": "Bearer USER_SESSION_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Collect and check documents",
    sortIndex: 100,
    isImportant: true,
  }),
});
const { data } = await res.json();
```

To create a **new checklist** (a top-level container), pass `parentId: 0` — in this case `title` becomes the name of the checklist:

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/3943/checklist" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Documents", "parentId": 0 }'
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.id` | number | ID of the new item |

## Response example

```json
{ "success": true, "data": { "id": 221 } }
```

## Error response example

`400` — the required `title` was not provided:

```json
{
  "success": false,
  "error": { "code": "INVALID_PARAMS", "message": "`title` is required" }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `title` is missing, `taskId` is not a positive integer, an unknown `members` shape, or a negative `parentId` |
| 404 | `TASK_NOT_FOUND` | The `taskId` task does not exist or is not accessible to the key — Vibecode checks the parent task with a separate call before adding an item |
| 403 | `SCOPE_DENIED` | The API key lacks the `task` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in "read-only" mode — switch it to read+write in [/keys](/keys) |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

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

## Known specifics

- **`parentId: 0` creates a new checklist container**, not a regular item — `title` becomes the container's name in this case.
- **An item without an explicit `parentId` can land inside an existing checklist.** If the task already has a container (`parentId: 0`), Bitrix24 assigns new items to it instead of leaving them at the top level — create a container explicitly via `parentId: 0` if you need an independent one.
- **`members` on write is an object keyed by `userId`**, not an array. The response shape (in `GET`) differs — see ["List items"](./list.md).

## See also

- [List items](./list.md)
- [Update an item](./update.md)
- [Employees](/docs/entities/users)
- [Tasks](/docs/entities/tasks)