For AI agents: markdown of this page — /docs-content-en/entities/tasks/checklist/create.md documentation index — /llms.txt

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

Examples

curl — personal key

Terminal 
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

Terminal 
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:

Terminal 
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
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — 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".

See also