Workgroups

Manage Bitrix24 account workgroups and projects: create, get, update, delete, search. A workgroup brings employees together around a shared topic or project — it has an owner, a subject, openness and archiving flags, and a member count.

Bitrix24 API: sonet_group.* Scope: sonet_group

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)

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.<id>; 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

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

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

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

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.

Response example

{
  "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:

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Title not specified"
  }
}

Errors

Full list of common API errors — 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 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 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 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: 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 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 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 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, message permissions and v2-mode update 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 with it returns 400 READONLY_FIELD. No other Vibecode API method sets the avatar of this chat.

See also

• List workgroups
• Get a workgroup
• Update a workgroup
• Workgroup fields