# Tasks

Manage Bitrix24 account tasks: 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`
- [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`

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 [Task kanban stages](/docs/task-stages) (`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's user; can be passed on create (within the Bitrix24 user's permissions). Employee list: `GET /v1/users` |
| `status` | Task status (number). Value decoding: `GET /v1/tasks/fields` → `fields.status.enum` |
| `priority` | Priority (number). Value decoding: `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, the Bitrix24 account 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` — the task is pending, `status: 5` — completed.
3. **`realStatus` is a FILTER-only name; it is not in responses.** `status` (virtual) comes in both the list and the card; `subStatus` comes **only in the list** — the `GET /v1/tasks/:id` card does NOT return it (the overdue sub-status `-1`/`-2`/`-3` is read only from the list). For overdue and almost-overdue tasks, `status`/`subStatus` take the values `-1` / `-2` / `-3` on top of the real `1..7`. `REAL_STATUS` is a filterable Bitrix24 field (the real stored status, always `1..7`); there is no `realStatus` key in the JSON response — read `status` + `subStatus`. This produces a filtering pitfall: a request `?filter[STATUS][]=2&filter[STATUS][]=3&filter[STATUS][]=4` silently drops overdue tasks — their `STATUS = -2`, even though `REAL_STATUS` is still `2`. Recipes by scenario:
   - "Active excluding overdue": `filter[STATUS][]=2&filter[STATUS][]=3&filter[STATUS][]=4`.
   - "Active including overdue": `filter[REAL_STATUS][]=2&filter[REAL_STATUS][]=3&filter[REAL_STATUS][]=4`.
   - "Overdue only": `filter[STATUS]=-2`.
4. **Numeric fields are serialized as strings.** In list and single-task responses, identifier fields (`id`, `responsibleId`, `createdBy`, `groupId`) and numeric enumerations (`status`, `priority`) come as strings, for example `"id": "289"`, `"status": "2"`. Convert on the client side with a simple `Number(...)`.
5. **Dates are in the Bitrix24 account's own timezone.** The fields `createdDate`, `changedDate`, `closedDate`, `deadline`, and similar come in ISO 8601 format with an offset (`2026-05-12T11:46:12+02:00`), not in UTC. For calculations, convert to `Date` or `Date.parse`.
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** (collaborators and watchers). If a task was just created and has no collaborators or watchers, 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 — 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 change history](/docs/task-history)
- [Task kanban stages](/docs/task-stages)
- [Entity reference](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch requests](/docs/batch)
- [Limits and optimization](/docs/optimization)