For AI agents: markdown of this page — /docs-content-en/entities/tasks/create.md documentation index — /llms.txt

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<id>`, where `id` is the file identifier from the `POST /v1/files/upload` response. For example, `["n9759"]`. The full rule for file fields — Task fields
`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. 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 — 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.

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

Terminal

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

Terminal

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

The task card URL in Bitrix24 is built from the id and the employee ID:

https://<portal>.bitrix24.com/company/personal/user/<responsibleId>/tasks/task/view/<id>/

<responsibleId> — 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. <portal> — 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: