## Create task `POST /v1/tasks` Creates a new task. Requires at least a title and a responsible person. ## Request fields (body) | Field | Type | Req. | Description | |------|-----|:-----:|---------| | `title` | string | ★ | Task title | | `responsibleId` | number | ★ | Responsible person. Employee list: `GET /v1/users` | | `description` | string | | Task description. Supports BB-code (`[USER=ID]Name[/USER]`, `[B]...[/B]`, `[QUOTE]...[/QUOTE]`) | | `priority` | number | | Priority: `0` — low, `1` — normal (default), `2` — high | | `status` | number | | Status. Defaults to `2` (pending). Full value list: `GET /v1/tasks/fields` → `fields.status.enum` | | `deadline` | datetime | | Deadline (ISO 8601) | | `startDatePlan` | datetime | | Planned start date | | `endDatePlan` | datetime | | Planned end date | | `timeEstimate` | number | | Effort estimate in seconds | | `groupId` | number | | Workgroup. List: `GET /v1/workgroups` | | `parentId` | number | | Parent task. List: `GET /v1/tasks` | | `accomplices` | number[] | | Participants. Employee list: `GET /v1/users` | | `auditors` | number[] | | Observers. Employee list: `GET /v1/users` | | `tags` | string[] | | Task tags (an array of tag names; accepted directly on create) | | `ufTaskWebdavFiles` | string[] | | Task files. An array of strings shaped as `n`, where `id` is the file identifier from the [`POST /v1/files/upload`](../files/upload.md) response. For example, `["n9759"]`. The full rule for file fields — [Task fields](./fields.md) | | `createdBy` | number | | Creator. Defaults to the key owner. An override is applied within the calling user's permissions. An existing employee only — see the warning below the table. Employee list: `GET /v1/users` | | `changedBy` | number | | Service field: who changed the task last. Accepted on write — see the section below the table. Employee list: `GET /v1/users` | | `closedBy` | number | | Service field: who closed the task. Accepted on write — see the section below the table. Employee list: `GET /v1/users` | | `statusChangedBy` | number | | Service field: who changed the status last. Accepted on write — see the section below the table. Employee list: `GET /v1/users` | | `createdDate` | datetime | | Service field: task creation date, ISO 8601. Accepted on write — see the section below the table | | `changedDate` | datetime | | Service field: last change date, ISO 8601. The value you send is stored instead of the current time — see the section below the table | | `closedDate` | datetime | | Service field: closing date, ISO 8601. Accepted on write even for a task that was never closed — see the section below the table | Full field list — [`GET /v1/tasks/fields`](./fields.md). The fields `id`, `dateStart`, `activityDate`, `realStatus` are set by the system and are not passed in the body. ### The task service fields can be set Besides `createdBy`, creation also accepts `changedBy`, `closedBy`, `statusChangedBy`, `createdDate`, `changedDate` and `closedDate`. Bitrix24 stores the submitted values, and Vibecode is a wrapper over it that does not forbid what the platform allows. Both spellings are accepted — `createdBy` and `CREATED_BY` alike. Send one of the two rather than both: with both in one body the later one wins. The same fields are accepted on [update](./update.md) — that page also covers what the task log keeps and how a date without a timezone behaves. > **Pass an existing employee only.** Bitrix24 does not check that the user ID exists — neither in `createdBy` nor in `changedBy`, `closedBy`, `statusChangedBy`. It stores any number. A task whose creator does not exist stops being manageable through the API: a further update and a deletion are both refused, even for an administrator key and even directly in Bitrix24, bypassing us. It cannot be undone through the API. Employee list: [`GET /v1/users`](/docs/entities/users). > **Important:** a title longer than 250 characters is not rejected — Bitrix24 silently truncates it to 250. Emoji are replaced with an internal escape sequence before truncation, so a title containing emoji is truncated earlier. Check `title` in the response when the title length matters. ## Examples ### curl — personal key ```bash curl -X POST "https://vibecode.bitrix24.com/v1/tasks" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Prepare the quarterly report", "responsibleId": 1, "priority": 2, "deadline": "2026-05-19T18:00:00+00:00" }' ``` ### curl — OAuth application ```bash curl -X POST "https://vibecode.bitrix24.com/v1/tasks" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Prepare the quarterly report", "responsibleId": 1, "priority": 2, "deadline": "2026-05-19T18:00:00+00:00" }' ``` ### JavaScript — personal key ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/tasks', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ title: 'Prepare the quarterly report', responsibleId: 1, priority: 2, deadline: '2026-05-19T18:00:00+00:00', }), }) const { success, data } = await res.json() console.log('New task ID:', data.id) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/tasks', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ title: 'Prepare the quarterly report', responsibleId: 1, priority: 2, deadline: '2026-05-19T18:00:00+00:00', }), }) const { success, data } = await res.json() ``` ## Response fields | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | object | Full object of the created task (same as `GET /v1/tasks/:id`) — see [Task fields](./fields.md) | The task card URL in Bitrix24 is built from the `id` and the employee ID: ``` https://.bitrix24.com/company/personal/user//tasks/task/view// ``` `` — the responsible person's ID (the `responsibleId` field in the response): the task opens in their personal workspace. The `user/<...>` segment determines whose workspace the tasks page is shown in — substitute the ID of the employee you need, for example the current one. `` — the Bitrix24 account domain. Access is limited by the employee's permissions in Bitrix24. ## Response example ```json { "success": true, "data": { "id": "3871", "title": "Prepare the quarterly report", "description": "", "status": "2", "priority": "2", "responsibleId": "1", "createdBy": "1", "createdDate": "2026-05-12T11:46:12+00:00", "deadline": "2026-05-19T18:00:00+00:00", "groupId": "0", "accomplices": [], "auditors": [], "creator": { "id": "1", "name": "Current user", "link": "/company/personal/user/1/" }, "responsible": { "id": "1", "name": "Current user", "link": "/company/personal/user/1/" } } } ``` ## Error response example 422 — responsible person not specified: ```json { "success": false, "error": { "code": "BITRIX_ERROR", "message": "Assignee not specified" } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 422 | `BITRIX_ERROR` | Bitrix24 rejected the task creation — for example, a required field (`title` or `responsibleId`) was not passed, or a submitted value was rejected by the portal | | 400 | `READONLY_FIELD` | A read-only field was passed in the request body (`id`, `dateStart`, `activityDate`, `realStatus`) | | 400 | `INVALID_DISK_ATTACHMENT_VALUE` | A file field was passed as something other than an array of `n` strings — a number, a string without the prefix, or a single string instead of an array | | 403 | `SCOPE_DENIED` | The API key does not have the `tasks` scope | | 401 | `TOKEN_MISSING` | The API key has no configured tokens | The full list of common API errors — [Errors](/docs/errors). ## See also - [Task fields](./fields.md) - [Get task](./get.md) - [Update task](./update.md) - [List tasks](./list.md) - [Upload file](../files/upload.md) - [Batch requests](/docs/batch) - [Limits and optimization](/docs/optimization)