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

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 counter.

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. There is one required field — name; the rest of the parameters are optional.

Request fields (body)

Field Type Req. Default Description
name string ★ — Workgroup name
description string no — Description
ownerId number no current key user Group owner identifier. List: GET /v1/users
subjectId number no default Bitrix24 account subject Subject identifier
active boolean no true Whether the group is active
visible boolean no true Whether it is visible in shared lists
opened boolean no false Whether it is open for joining without an invitation
archived boolean no false Place into the archive immediately on creation
isProject boolean no false Create as a project
isExtranet boolean no false Extranet group
keywords string no — Keywords for search

Examples

curl — personal key

Terminal 
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": false
  }'

curl — OAuth application

Terminal 
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": false
  }'

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: false,
  }),
})

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: false,
  }),
})

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 or Workgroup fields

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 173,
    "siteId": "s1",
    "name": "Marketing 2026",
    "description": "Coordinating ad campaigns",
    "dateCreate": "2026-05-26T05:56:40.000Z",
    "dateUpdate": "2026-05-26T05:56:40.000Z",
    "active": true,
    "visible": true,
    "opened": true,
    "archived": false,
    "subjectId": 1,
    "ownerId": 1,
    "keywords": null,
    "membersCount": 1,
    "dateActivity": "2026-05-26T05:56:40.000Z",
    "subjectName": "Workgroups",
    "isProject": false,
    "isExtranet": false
  }
}

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
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 provided key was not recognized
403 SCOPE_DENIED The key does not have the sonet_group scope

Full list of common API errors — Errors.

See also