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

Task checklist

Task checklist items are a nested resource of a task. Each item has a title, a completion status, an importance flag, a sort order, members, and (optionally) a parent item for nested checklists. Base path — /v1/tasks/:taskId/checklist. Every operation is addressed by the task identifier :taskId.

Bitrix24 API: task.checklistitem.* Scope: task

Why a separate resource. Bitrix24 does not accept the CHECKLIST field inside POST /v1/tasks (tasks.task.add) — a checklist cannot be created together with the task. The only supported way to manage items is the task.checklistitem.* family of methods, which this resource wraps. First create the task, then add items one by one.

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

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

curl — OAuth application

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

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