## Create a workgroup `POST /v1/workgroups` Creates a new workgroup in the Bitrix24 account. Returns the full object of the created group. The only required field is `name`; all other parameters are optional. ## Request fields (body) | Field | Type | Required | Default | Description | |------|-----|:-----:|-----------|---------| | `name` | string | ★ | — | Workgroup name | | `description` | string | no | — | Description | | `ownerId` | number | no | the key's user | Group owner identifier. List: `GET /v1/users` | | `subjectId` | number | no | the Bitrix24 account's default subject | Subject identifier | | `active` | boolean | no | `true` | Whether the group is active | | `visible` | boolean | no | — | Whether it is visible in shared lists. The actual value is in the response, see "The group is created as a collab" | | `opened` | boolean | no | `false` | Whether it is open for joining without an invitation. The actual value is in the response, see "The group is created as a collab" | | `archived` | boolean | no | `false` | Archive the group immediately on creation | | `isProject` | boolean | no | — | Create as a project. The actual value is in the response, see "The group is created as a collab" | | `keywords` | string | no | — | Keywords for search. Not saved on create, see "Keywords are not saved on create" | `isExtranet` is read-only and derived from the group's site bindings in Bitrix24. Passing `isExtranet`, `IS_EXTRANET`, `is_extranet` or `isextranet` returns `400 READONLY_FIELD` before the group is created: both `false` and `true` are rejected, including the current value. Remove this field from write bodies; reads still return the actual flag. In `POST /v1/workgroups/batch` with `action: create` or `action: update`, this field causes `400 BATCH_ITEM_VALIDATION` before the entire batch is sent. In `POST /v1/batch`, a rejected operation receives `READONLY_FIELD` in `data.errors.`; the HTTP status is 400 if all operations are rejected, or 200 for a mixed result, with valid sibling operations executed. ## Examples ### curl — personal key ```bash curl -X POST "https://vibecode.bitrix24.com/v1/workgroups" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Marketing 2026", "description": "Coordinating ad campaigns", "opened": true, "isProject": true }' ``` ### curl — OAuth application ```bash curl -X POST "https://vibecode.bitrix24.com/v1/workgroups" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Marketing 2026", "description": "Coordinating ad campaigns", "opened": true, "isProject": true }' ``` ### JavaScript — personal key ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Marketing 2026', description: 'Coordinating ad campaigns', opened: true, isProject: true, }), }) const { success, data } = await res.json() console.log('Workgroup ID:', data.id) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Marketing 2026', description: 'Coordinating ad campaigns', opened: true, isProject: true, }), }) const { success, data } = await res.json() ``` ## Response fields Returns the full object of the created workgroup. | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | object | The created workgroup object. Full field description — [Get a workgroup](./get.md) or [Workgroup fields](./fields.md) | ## Response example ```json { "success": true, "data": { "id": 201, "siteId": "ex", "name": "Marketing 2026", "description": "Coordinating ad campaigns", "dateCreate": "2026-10-20T06:48:43.000Z", "dateUpdate": "2026-10-20T06:48:43.000Z", "active": true, "visible": false, "opened": false, "archived": false, "subjectId": 1, "ownerId": 1317, "keywords": null, "membersCount": 1, "dateActivity": "2026-10-20T06:48:43.000Z", "subjectName": "Workgroups", "isProject": true, "isExtranet": true } } ``` ## Error response example 422 — the required `name` field was not passed: ```json { "success": false, "error": { "code": "BITRIX_ERROR", "message": "Title not specified" } } ``` ## Errors | HTTP | `error.code` | Description | |------|--------------|---------| | 400 | `READONLY_FIELD` | A read-only field was passed, including `isExtranet` or `IS_EXTRANET` | | 422 | `BITRIX_ERROR` | Bitrix24 declined to create the group — the reason text is in `error.message`. Typical reason: the required `name` field is missing | | 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed | | 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform | | 403 | `SCOPE_DENIED` | The key does not have the `sonet_group` scope | Full list of common API errors — [Errors](/docs/errors). ## Known specifics **The group is created as a collab.** On the Bitrix24 accounts we checked, a new group is created as a collab regardless of the request body. The response carries `isProject: true`, `siteId: "ex"`, `isExtranet: true`, `visible: false` and `opened: false`, even when the request passed `isProject: false` or `opened: true`. The project flag cannot be cleared on such a group: [`PATCH /v1/workgroups/:id`](./update.md) with `isProject: false` returns `422 BITRIX_ERROR` with the text `Field 'PROJECT' can not be updated from 'Y' for collab`. Read the actual field values from the create response. **Keywords are not saved on create.** Bitrix24 does not save `keywords` passed when the group is created: the create response and later reads return `keywords: null`. The same applies to `action: create` in `POST /v1/workgroups/batch` and `POST /v1/batch`. To set keywords, send [`PATCH /v1/workgroups/:id`](./update.md) with the `keywords` field after the group is created — the update saves the value. **The group chat is created together with the group.** Right after creation the group has one chat, a collab chat. Its card has `type` set to `collab`, `entityType` set to `SONET_GROUP` and `entityId` set to the group `id`. There is no separate main chat. [Dialog ID by external identifier](/docs/chats/discovery/dialog-id) returns this chat's `dialogId` for an `externalId` of the form `sgN`, where `N` is the `id` from the response. You do not need to create a chat for the group with [`POST /v1/chats`](/docs/chats/management/create): `type: "COLLAB"` with its `entityId` creates a second collab chat. **CoPilot joins the group chat along with a new member.** Until someone is added to the chat, only the owner is in it. When a member — a person or a bot — is [added to the chat](/docs/chats/members/add) in the v2 mode, the CoPilot system bot with `bot: true` also appears among the members. No request field turns this off. You can [remove the bot from the chat](/docs/chats/members/remove) in the v2 mode by passing its `userId`, but it comes back the next time a member is added. In the regular mode the [member list](/docs/chats/members/list) shows CoPilot, while in the v2 mode the bot is absent from both `users` and `relations`. **The avatar and permissions of the group chat cannot be set through the API.** The [avatar](/docs/chats/management/avatar), [message permissions](/docs/chats/management/permissions-messages) and [v2-mode update](/docs/chats/management/rename) methods return `403 BITRIX_ACCESS_DENIED` for a collab chat, even for its owner. The workgroup `imageUrl` field is read-only: [`PATCH /v1/workgroups/:id`](./update.md) with it returns `400 READONLY_FIELD`. No other Vibecode API method sets the avatar of this chat. ## See also - [List workgroups](./list.md) - [Get a workgroup](./get.md) - [Update a workgroup](./update.md) - [Workgroup fields](./fields.md)