Для AI-агентов: markdown этой страницы — /docs-content/entities/workgroups/create.md индекс документации — /llms.txt
Создать рабочую группу
POST /v1/workgroups
Создаёт новую рабочую группу на портале. Возвращает полный объект созданной группы. Обязательное поле одно — name; остальные параметры опциональны.
Поля запроса (body)
| Поле | Тип | Обяз. | По умолч. | Описание |
|---|---|---|---|---|
Полеname |
Типstring | Обяз.★ | По умолч.— | ОписаниеНазвание рабочей группы |
Полеdescription |
Типstring | Обяз.нет | По умолч.— | ОписаниеОписание |
ПолеownerId |
Типnumber | Обяз.нет | По умолч.текущий пользователь ключа | ОписаниеИдентификатор владельца группы. Список: GET /v1/users |
ПолеsubjectId |
Типnumber | Обяз.нет | По умолч.тема портала по умолчанию | ОписаниеИдентификатор темы |
Полеactive |
Типboolean | Обяз.нет | По умолч.true |
ОписаниеАктивна ли группа |
Полеvisible |
Типboolean | Обяз.нет | По умолч.— | ОписаниеВидна ли в общих списках. Фактическое значение — в ответе, см. «Группа создаётся коллабом» |
Полеopened |
Типboolean | Обяз.нет | По умолч.false |
ОписаниеОткрыта ли для вступления без приглашения. Фактическое значение — в ответе, см. «Группа создаётся коллабом» |
Полеarchived |
Типboolean | Обяз.нет | По умолч.false |
ОписаниеПоместить в архив сразу при создании |
ПолеisProject |
Типboolean | Обяз.нет | По умолч.— | ОписаниеСоздать как проект. Фактическое значение — в ответе, см. «Группа создаётся коллабом» |
Полеkeywords |
Типstring | Обяз.нет | По умолч.— | ОписаниеКлючевые слова для поиска. При создании не сохраняются, см. «Ключевые слова при создании не сохраняются» |
isExtranet доступен только для чтения и определяется привязкой группы к сайтам в Битрикс24. Передача isExtranet, IS_EXTRANET, is_extranet или isextranet возвращает 400 READONLY_FIELD до создания группы: и для false, и для true, включая повтор текущего значения. Уберите это поле из тела записи; фактический признак остаётся в ответах чтения.
В POST /v1/workgroups/batch с action: create или action: update такое поле вызывает 400 BATCH_ITEM_VALIDATION до отправки всего пакета. В POST /v1/batch отклонённая операция получает READONLY_FIELD в data.errors.<id>; если отклонены все операции, HTTP-статус — 400, при смешанном результате — 200, а допустимые соседние операции выполняются.
Примеры
curl — личный ключ
curl -X POST "https://vibecode.bitrix24.tech/v1/workgroups" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Маркетинг 2026",
"description": "Координация рекламных кампаний",
"opened": true,
"isProject": true
}'
curl — OAuth-приложение
curl -X POST "https://vibecode.bitrix24.tech/v1/workgroups" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Маркетинг 2026",
"description": "Координация рекламных кампаний",
"opened": true,
"isProject": true
}'
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Маркетинг 2026',
description: 'Координация рекламных кампаний',
opened: true,
isProject: true,
}),
})
const { success, data } = await res.json()
console.log('Workgroup ID:', data.id)
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Маркетинг 2026',
description: 'Координация рекламных кампаний',
opened: true,
isProject: true,
}),
})
const { success, data } = await res.json()
Поля ответа
Возвращается полный объект созданной рабочей группы.
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata |
Типobject | ОписаниеОбъект созданной рабочей группы. Полное описание полей — Получить рабочую группу или Поля рабочей группы |
Пример ответа
{
"success": true,
"data": {
"id": 201,
"siteId": "ex",
"name": "Маркетинг 2026",
"description": "Координация рекламных кампаний",
"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": "Рабочие группы",
"isProject": true,
"isExtranet": true
}
}
Пример ответа при ошибке
422 — не передано обязательное поле name:
{
"success": false,
"error": {
"code": "BITRIX_ERROR",
"message": "Не указано название"
}
}
Ошибки
| HTTP | error.code |
Описание |
|---|---|---|
| HTTP400 | error.codeREADONLY_FIELD |
ОписаниеПередано поле только для чтения, включая isExtranet или IS_EXTRANET |
| HTTP422 | error.codeBITRIX_ERROR |
ОписаниеБитрикс24 отказал в создании группы — текст причины в error.message. Типичная причина: отсутствует обязательное поле name |
| HTTP401 | error.codeMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP401 | error.codeINVALID_API_KEY |
ОписаниеКлюч не опознан: такой строки на платформе нет |
| HTTP403 | error.codeSCOPE_DENIED |
ОписаниеУ ключа нет скоупа sonet_group |
Полный список общих ошибок API — Ошибки.
Известные особенности
Группа создаётся коллабом. На проверенных порталах новая группа создаётся коллабом при любом теле запроса. В ответе isProject: true, siteId: "ex", isExtranet: true, visible: false и opened: false, даже если в запросе передано isProject: false или opened: true. Признак проекта у такой группы не снимается: PATCH /v1/workgroups/:id с isProject: false отвечает 422 BITRIX_ERROR с текстом Field 'PROJECT' can not be updated from 'Y' for collab. Фактические значения полей читайте в ответе создания.
Ключевые слова при создании не сохраняются. Битрикс24 не сохраняет keywords, переданное при создании группы: в ответе создания и при последующем чтении keywords равно null. То же для action: create в POST /v1/workgroups/batch и POST /v1/batch. Чтобы задать ключевые слова, после создания отправьте PATCH /v1/workgroups/:id с полем keywords — обновление значение сохраняет.
Чат группы создаётся вместе с ней. Сразу после создания у группы есть один чат — чат коллаба. В его карточке type равен collab, entityType — SONET_GROUP, entityId — id группы. Отдельного главного чата нет. dialogId этого чата возвращает ID диалога по внешнему идентификатору с externalId вида sgN, где N — id из ответа. Создавать группе чат через POST /v1/chats не нужно: type: "COLLAB" с её entityId создаст второй чат коллаба.
В чат группы вместе с участником приходит BitrixGPT. Пока в чат никого не добавили, в нём только владелец. Когда в чат в режиме v2 добавляют участника, человека или бота, в составе появляется и системный бот BitrixGPT с bot: true. Ни одно поле запроса этого не отключает. Бота можно удалить из чата в режиме v2, передав его userId, но при следующем добавлении участника он вернётся. В обычном режиме список участников показывает BitrixGPT, а в режиме v2 бота нет ни в users, ни в relations.
Аватар и права чата группы через API не задаются. Аватар, права на сообщения и изменение в режиме v2 отвечают на чат коллаба 403 BITRIX_ACCESS_DENIED, в том числе владельцу. Поле imageUrl рабочей группы только для чтения: PATCH /v1/workgroups/:id с ним возвращает 400 READONLY_FIELD. Другого метода Вайбкод, который задаёт аватар этого чата, нет.