# Flows and flow tasks

The nine `/v1/tasks/flows` routes call the corresponding `tasks.flow.*` Bitrix24 REST methods. The API key needs the `task` (or `tasks`) scope. READONLY keys can read; creating, updating, deleting, and toggling activity require write access.

`GET /v1/tasks/flows`

`POST /v1/tasks/flows`

`GET /v1/tasks/flows/:flowId`

`PATCH /v1/tasks/flows/:flowId`

`DELETE /v1/tasks/flows/:flowId`

`POST /v1/tasks/flows/:flowId/activate`

`GET /v1/tasks/flows/:flowId/tasks/completed`

`GET /v1/tasks/flows/:flowId/tasks/pending`

`GET /v1/tasks/flows/:flowId/tasks/progress`

| HTTP | Route | Bitrix24 method | Forwarded parameters |
| --- | --- | --- | --- |
| `GET` | `/v1/tasks/flows` | `tasks.flow.Flow.list` | `select`, `filter`, `order`, `group`, `start` from the query |
| `POST` | `/v1/tasks/flows` | `tasks.flow.Flow.create` | `flowData`, optional `analyticsParams` from the JSON body |
| `GET` | `/v1/tasks/flows/:flowId` | `tasks.flow.Flow.get` | `flowId` |
| `PATCH` | `/v1/tasks/flows/:flowId` | `tasks.flow.Flow.update` | `flowData` with `id` from the path, optional `analyticsParams` |
| `DELETE` | `/v1/tasks/flows/:flowId` | `tasks.flow.Flow.delete` | `flowData: { id: flowId }` |
| `POST` | `/v1/tasks/flows/:flowId/activate` | `tasks.flow.Flow.activate` | `flowId` |
| `GET` | `/v1/tasks/flows/:flowId/tasks/completed?days=7` | `tasks.flow.Task.Completed.list` | `flowData: { id: flowId }`, `ago: { days: 7 }`, optional `start` |
| `GET` | `/v1/tasks/flows/:flowId/tasks/pending` | `tasks.flow.Task.Pending.list` | `flowData: { id: flowId }`, optional `start` |
| `GET` | `/v1/tasks/flows/:flowId/tasks/progress` | `tasks.flow.Task.Progress.list` | `flowData: { id: flowId }`, optional `start` |

`flowId` is a positive integer. For create and update, send a `flowData` object with [FlowDto fields](https://apidocs.bitrix24.com/api-reference/tasks/flow/tasks-flow-flow-create.html), such as `name`, `plannedCompletionTime`, `distributionType`, and `responsibleList`. `PATCH` takes the identifier from the path; a supplied `flowData.id` in the body must match it. `activate` **toggles** the current state; it does not set a requested value. Calling it again toggles the state again.

For `GET /v1/tasks/flows`, encode `select` and `group` arrays, and `filter` and `order` objects, as JSON query strings. Example: `?select=%5B%22ID%22%2C%22NAME%22%5D&filter=%7B%22ACTIVE%22%3A%22Y%22%7D&start=50`. Their field names reach Bitrix24 unchanged. `start` is the native REST pagination offset. VibeCode makes one call and does not combine pages. `completed` requires a non-negative `days` value, sent as `ago.days`. The three task lists stay separate: Bitrix24 determines status and order and returns `{ tasks, totalCount }`.

A successful response is `{ "success": true, "data": <Bitrix24 result> }`. `Flow.list` returns an array, `Flow.get/create/update` return an object, `Flow.delete` returns `{ "deleted": true }`, `Flow.activate` returns `true`, and a task list returns `{ "tasks": [...], "totalCount": N }`. Empty and `null` results are not replaced. Bitrix24 determines the actual object fields.

Invalid path, query, or body input returns `400 INVALID_PARAMS`; a missing or invalid key returns `401`; missing scope and a READONLY write attempt return `403`. Bitrix24 refusals use the common `/v1` handler: `422 BITRIX_ERROR`, `429 RATE_LIMITED`, `502 BITRIX_UNAVAILABLE`, `503 BITRIX_TIMEOUT`.