# Tasks

Manage tasks in the Bitrix24 account: create, read, update, delete, filter, aggregate. A task is a unit of work with a responsible person, a creator, a deadline, and a status. A single task may have comments and time-tracking records — these are separate nested resources.

Bitrix24 API: `tasks.task.*`
Scope: `tasks`

## Operations

- [Create task](./tasks/create.md) — `POST /v1/tasks`
- [List tasks](./tasks/list.md) — `GET /v1/tasks`
- [Get task](./tasks/get.md) — `GET /v1/tasks/:id`
- [Update task](./tasks/update.md) — `PATCH /v1/tasks/:id`
- [Delete task](./tasks/delete.md) — `DELETE /v1/tasks/:id`
- [Search tasks](./tasks/search.md) — `POST /v1/tasks/search`
- [Task fields](./tasks/fields.md) — `GET /v1/tasks/fields`
- [Aggregate tasks](./tasks/aggregate.md) — `POST /v1/tasks/aggregate`
- [Create a task template](./tasks/templates-create.md) — `POST /v1/task-templates`
- [List task templates](./tasks/templates-list.md) — `GET /v1/task-templates`
- [Get a task template](./tasks/templates-get.md) — `GET /v1/task-templates/:templateId`
- [Update a task template](./tasks/templates-update.md) — `PATCH /v1/task-templates/:templateId`
- [Add to favorites](./tasks/favorite.md) — `POST /v1/tasks/:taskId/favorite`
- [Remove from favorites](./tasks/unfavorite.md) — `DELETE /v1/tasks/:taskId/favorite`
- [Pin task](./tasks/pin.md) — `POST /v1/tasks/:taskId/pin`
- [Unpin task](./tasks/unpin.md) — `DELETE /v1/tasks/:taskId/pin`

### Direct task actions

Each route below makes one call to the Bitrix24 method of the same name with `taskId` from the path. Every route uses `POST`, requires the `task` scope (a key with the `tasks` scope also works), and requires a write-enabled key. The Bitrix24 result is returned unchanged in `data`. Status actions — `start`, `pause`, `complete`, `approve`, `disapprove`, `defer`, `renew` — return `data.task`: a task object whose numbers and flags arrive as strings. Timers return the same `data.task`, or `data: null` on a task with time tracking disabled. A successful `bindCrmItem` returns `{ "success": true }`. Bitrix24 checks the caller's permission for each action.

| Path after `/v1/tasks/:taskId/` | `tasks.task.*` method | JSON body |
| --- | --- | --- |
| [`POST /v1/tasks/:taskId/add-accomplices`](./tasks/add-accomplices.md) | `addAccomplices` | `{"accomplicesIds":[42]}` |
| [`POST /v1/tasks/:taskId/add-auditors`](./tasks/add-auditors.md) | `addAuditors` | `{"auditorsIds":[42]}` |
| [`POST /v1/tasks/:taskId/approve`](./tasks/approve.md) | `approve` | optional |
| [`POST /v1/tasks/:taskId/bind-crm-item`](./tasks/bind-crm-item.md) | `bindCrmItem` | `{"crmItemId":"D_123"}` |
| [`POST /v1/tasks/:taskId/complete`](./tasks/complete.md) | `complete` | optional |
| [`POST /v1/tasks/:taskId/defer`](./tasks/defer.md) | `defer` | optional |
| [`POST /v1/tasks/:taskId/delegate`](./tasks/delegate.md) | `delegate` | `{"userId":42}` |
| [`POST /v1/tasks/:taskId/disapprove`](./tasks/disapprove.md) | `disapprove` | optional |
| [`POST /v1/tasks/:taskId/pause`](./tasks/pause.md) | `pause` | optional |
| [`POST /v1/tasks/:taskId/pause-timer`](./tasks/pause-timer.md) | `pauseTimer` | optional |
| [`POST /v1/tasks/:taskId/renew`](./tasks/renew.md) | `renew` | optional |
| [`POST /v1/tasks/:taskId/start`](./tasks/start.md) | `start` | optional |
| [`POST /v1/tasks/:taskId/start-timer`](./tasks/start-timer.md) | `startTimer` | optional |
| [`POST /v1/tasks/:taskId/take`](./tasks/take.md) | `take` | optional |

Status actions, delegation and timers may include `params`, an object passed to that specific Bitrix24 method. `addAccomplices`, `addAuditors` and `bindCrmItem` do not accept `params`. To stop the previous timer while starting a new one, send `{"params":{"STOP_PREVIOUS":"Y"}}`. Without it, the start is rejected with `422` while a timer is running on another task. The routes do not turn an action into a generic task update or perform further transitions. The `auditorsIds` and `accomplicesIds` arrays are optional: if omitted or empty, Bitrix24 returns the current task without adding users. The availability of individual actions and of CRM binding depends on the permissions and capabilities of the Bitrix24 account.

A task has nested resources with their own CRUD operations: [Task comments](./task-comments.md) (`/v1/tasks/:taskId/comments`), [Task time tracking](./tasks/time.md) (`/v1/tasks/:taskId/time`) and [Task chat](./tasks/chat.md) (`GET /v1/tasks/:taskId/chat/messages`). Scrum placement of a task (backlog/sprint, epic, story points) lives in its own section — [Scrum API](/docs/scrum).

Task change history and current kanban stages are available as separate read-only endpoints: [Task change history](/docs/task-history) (`GET /v1/tasks/:taskId/history`) and [List task kanban stages](/docs/task-stages/list) (`GET /v1/tasks/stages/:entityId`).

## Key fields

| Field | Description |
|------|---------|
| `title` | Task title |
| `description` | Task body (supports BB-code, the `descriptionInBbcode` flag) |
| `responsibleId` | Responsible person. Employee list: `GET /v1/users` |
| `createdBy` | Creator. Defaults to the key owner. Can be passed both on create and on update (within the Bitrix24 user's permissions). Employee list: `GET /v1/users` |
| `status` | Task status (number). Value mapping: `GET /v1/tasks/fields` → `fields.status.enum` |
| `priority` | Priority (number). Value mapping: `GET /v1/tasks/fields` → `fields.priority.enum` |
| `deadline` | Deadline (ISO 8601) |
| `groupId` | Workgroup. List: `GET /v1/workgroups` |

Full field list — [`GET /v1/tasks/fields`](./tasks/fields.md).

## What to know before you start

1. **Minimum to create:** `title` and `responsibleId`. If the responsible person is omitted, Bitrix24 returns the error "Assignee not specified."
2. **Status and priority are numeric codes**, not strings. The full mapping table comes in the `GET /v1/tasks/fields` response under `fields.status.enum` / `fields.priority.enum`. For example, `status: 2` means the task is pending, and `status: 5` means it is completed.
3. **The `status` field in the response and the `filter[status]` selector are not the same thing.** In the response, `status` is the actual status of the task, always `1..7`, both in the list and in a single-task response. The `filter[status]` selector works on the Bitrix24 virtual axis: `-1` — overdue, `-2` — unviewed, `-3` — almost overdue. The axis assigns exactly one value to each task, so an overdue task with `status: 2` does not match the condition `filter[status]=2`, and iterating `filter[status]` over the values `1..7` does not return all the tasks in the Bitrix24 account. The virtual value comes in a separate `subStatus` field and only in the [list](./tasks/list.md) — the single-task `GET /v1/tasks/:id` response does not return it. To filter and sort by the actual status, use the name `realStatus`: it works in `filter` and `sort`, but there is no `realStatus` key in the response. Recipes by scenario:
   - "Active excluding overdue, unviewed and almost overdue": `?filter[status][]=2&filter[status][]=3&filter[status][]=4`.
   - "Active including overdue": `?filter[realStatus][]=2&filter[realStatus][]=3&filter[realStatus][]=4`.
   - "Overdue only": `?filter[status]=-1`.
   - "All tasks by status": iterate `filter[realStatus]` from `1` to `7` — the sum matches the total number of tasks.
4. **Numbers come as numbers.** The identifier fields `id`, `responsibleId`, `createdBy`, `groupId` and the numeric enumerations `status`, `priority` come as JSON numbers — `"id": 289`, `"status": 2`. Converting them via `Number(...)` is not required. `subStatus` stays a string, and yes/no flags come as `true` and `false`.
5. **Response dates are UTC.** The fields `createdDate`, `changedDate`, `closedDate`, `deadline` and the other task dates come in UTC with the `Z` suffix — `2026-05-12T08:46:12.000Z`. The Bitrix24 account time zone does not affect the response, so derive the calendar day after converting to the zone you need rather than by slicing the first ten characters of the string. A request may carry a date with an offset — [updating a task](./tasks/update.md) describes how such a value is parsed.
6. **Users inside a task.** The `creator` and `responsible` fields come embedded as objects of the form `{ id, name, link, icon, workPosition }` — a separate request for profiles is not needed.
7. **`accomplices` and `auditors` are arrays of string user identifiers** (participants and observers). If a task has just been created and has no participants or observers, the fields come as empty arrays.

## Typical scenario

1. Find the responsible person: [`GET /v1/users`](/docs/entities/users) (or a filtered search by the desired name).
2. Create the task: [`POST /v1/tasks`](./tasks/create.md) with `title` and `responsibleId`.
3. Fill in details: [`PATCH /v1/tasks/:id`](./tasks/update.md) — `deadline`, `priority`, `description`, `auditors`.
4. Record progress with a comment: [`POST /v1/tasks/:taskId/comments`](./task-comments/create.md).
5. Log time: [`POST /v1/tasks/:taskId/time`](./tasks/time/create.md).
6. Close the task: [`PATCH /v1/tasks/:id`](./tasks/update.md) → `status: 5`.

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| `offset` on large selections | `limit ≤ 500` recommended when `offset ≥ 2500` |
| Time-window splitting for large selections | `POST /v1/tasks/search` with `autoWindow: true` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared across the API — see [Limits and optimization](/docs/optimization) |

## See also

- [Task comments](./task-comments.md)
- [Task time tracking](./tasks/time.md)
- [Task checklist](./tasks/checklist.md)
- [Checklist actions and task file](./tasks/checklist-actions.md)
- [Task dependencies](./tasks/dependencies.md)
- [Task templates](./tasks/templates.md)
- [Task results: REST 3.0](./tasks/results-v3.md)
- [Task results: legacy REST](./tasks/results.md)
- [Flows and flow tasks](./tasks/flows.md)
- [Task change history](/docs/task-history)
- [Task kanban stages](/docs/task-stages)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Limits and optimization](/docs/optimization)

`filter[stagesId]` selects tasks by their position in the key owner's My Plan (STAGES_ID), regardless of stageId. PATCH stageId only accepts a stage of the task's workgroup. For My Plan, use [move-stage](/docs/tasks/move-stage).