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 Required Description
ParametertaskId (path) Typeinteger Requiredyes DescriptionTask ID

Request fields (body)

Field Type Required Description
Fieldtitle Typestring Requiredyes DescriptionItem text. If parentId: 0, becomes the name of the new checklist
FieldsortIndex Typeinteger Requiredno DescriptionSort index. The smaller the value, the higher the item appears in the list
FieldisImportant Typeboolean / Y,N Requiredno DescriptionImportance flag
FieldisComplete Typeboolean / Y,N Requiredno DescriptionCompletion status at creation
FieldparentId Typeinteger Requiredno DescriptionParent item ID. 0 creates a new checklist container in the task
Fieldmembers Typeobject Requiredno DescriptionItem 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionID 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
HTTP400 CodeINVALID_PARAMS Descriptiontitle is missing, taskId is not a positive integer, an unknown members shape, or a negative parentId
HTTP404 CodeTASK_NOT_FOUND DescriptionThe 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
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the task scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode. Open the path from error.details.switchUrl: a personal key points to /keys, an application key with a card to /applications, a standalone OAuth key to /apps, and a management key to /management-keys. Switch it to read and write there
HTTP401 CodeTOKEN_MISSING DescriptionThe 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