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. The base path is /v1/tasks/:taskId/checklist. Every operation is addressed by the task identifier :taskId.

Bitrix24 API: task.checklistitem.* Scope: task

Why a separate resource. The CHECKLIST field is not accepted in the body of POST /v1/tasks — a checklist cannot be created together with the task. Saving the whole checklist, reordering items, and adding members and attachments are done with checklist actions.

List checklist items

GET /v1/tasks/:taskId/checklist

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

Parameters

Parameter Type Required Description
ParametertaskId (path) Typeinteger Requiredyes DescriptionTask ID. List: GET /v1/tasks
Parametersort (query) Typestring Requiredno DescriptionSorting in the field:direction format, for example sortIndex:asc. Fields: id, parentId, createdBy, title, sortIndex, isComplete, isImportant, toggledBy, toggledDate. Direction: asc or desc (default asc). Without the parameter, items are ordered by sortIndex ascending, as with sortIndex:asc
Parameterstart (query) Typeinteger Requiredno DescriptionAccepted but does not shift the result: any value returns every checklist item. Must be a non-negative integer, otherwise 400 INVALID_PARAMS

Pagination. There is no paging: all checklist items come in one response, and meta.total equals the number of elements in data.

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of checklist items
Fielddata[].id Typestring DescriptionItem ID
Fielddata[].taskId Typestring DescriptionParent task ID
Fielddata[].parentId Typeinteger / string DescriptionID of the parent item from the same list. 0 — a top-level item (itself a checklist)
Fielddata[].title Typestring DescriptionItem text
Fielddata[].sortIndex Typestring DescriptionSort index
Fielddata[].isComplete Typestring DescriptionCompletion status — "Y" / "N"
Fielddata[].isImportant Typestring DescriptionImportance flag — "Y" / "N"
Fielddata[].createdBy Typestring DescriptionID of the item author. Employee list: GET /v1/users
Fielddata[].toggledBy Typestring | null DescriptionID of the employee who last changed the completion status. Employee list: GET /v1/users
Fielddata[].toggledDate Typestring DescriptionWhen the status was last changed. An empty string if never changed
Fielddata[].members Typearray DescriptionItem members — objects { id, type, name, personalPhoto, personalGender, image, isCollaber }. id — the employee ID from GET /v1/users
Fielddata[].attachments Typearray | object DescriptionItem attachments. Without attachments — an empty array. With attachments — an object keyed by attachment ID, each value an object with the fields attachmentId, name, size, fileId (the Drive file ID), downloadUrl, viewUrl
Fieldmeta.total Typenumber DescriptionTotal 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

404 — Bitrix24 reported that the task does not exist or is not accessible:

JSON 
{
  "success": false,
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task not found or not accessible."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptiontaskId is not a positive integer, the sort field is unknown, or start is not a non-negative integer
HTTP404 CodeTASK_NOT_FOUND DescriptionBitrix24 reported TASK_NOT_FOUND_OR_NOT_ACCESSIBLE: the task is missing or not accessible to the key
HTTP422 CodeBITRIX_ERROR DescriptionAny other Bitrix24 error without a more specific error code
HTTP429 CodeRATE_LIMITED DescriptionBitrix24 throttled the request. Respect the Retry-After header
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the task scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP400 CodeUNSUPPORTED_FILTER DescriptionA filter parameter was passed, and this endpoint has none. The error text names what to use instead

Full list of common API errors — Errors.

Known specifics

  • An existing task without items returns 200 with an empty array.

  • 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