Для AI-агентов: markdown этой страницы — /docs-content/entities/workgroups/update.md индекс документации — /llms.txt
Обновить рабочую группу
PATCH /v1/workgroups/:id
Обновляет указанные поля рабочей группы. Возвращает полный объект группы после обновления. Неупомянутые в теле поля остаются без изменений.
Параметры
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
Параметрid (path) |
Типnumber | Обяз.★ | ОписаниеИдентификатор рабочей группы. Список: GET /v1/workgroups |
Поля запроса (body)
Передавайте только те поля, которые нужно изменить. Остальные сохраняют текущие значения.
| Поле | Тип | Обяз. | По умолч. | Описание |
|---|---|---|---|---|
Полеname |
Типstring | Обяз.нет | По умолч.текущее значение | ОписаниеНазвание рабочей группы |
Полеdescription |
Типstring | Обяз.нет | По умолч.текущее значение | ОписаниеОписание |
ПолеownerId |
Типnumber | Обяз.нет | По умолч.текущее значение | ОписаниеИдентификатор нового владельца группы. Список: GET /v1/users |
ПолеsubjectId |
Типnumber | Обяз.нет | По умолч.текущее значение | ОписаниеИдентификатор темы |
Полеactive |
Типboolean | Обяз.нет | По умолч.текущее значение | ОписаниеАктивна ли группа |
Полеvisible |
Типboolean | Обяз.нет | По умолч.текущее значение | ОписаниеВидна ли в общих списках |
Полеopened |
Типboolean | Обяз.нет | По умолч.текущее значение | ОписаниеОткрыта ли для вступления без приглашения |
Полеarchived |
Типboolean | Обяз.нет | По умолч.текущее значение | ОписаниеПомещена ли в архив |
ПолеisProject |
Типboolean | Обяз.нет | По умолч.текущее значение | ОписаниеЯвляется ли проектом. У группы-коллаба false не принимается — 422 BITRIX_ERROR |
Полеkeywords |
Типstring | Обяз.нет | По умолч.текущее значение | ОписаниеКлючевые слова для поиска |
Поля id, subjectName, membersCount, dateCreate, dateUpdate, dateActivity, siteId, imageUrl, isExtranet доступны только для чтения. Передача любого из них в теле возвращает 400 READONLY_FIELD.
isExtranet определяется привязкой группы к сайтам в Битрикс24. Имена isExtranet, IS_EXTRANET, is_extranet и isextranet отклоняются до изменения группы: и для 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 PATCH "https://vibecode.bitrix24.tech/v1/workgroups/85" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "Обновлённое описание команды",
"opened": true,
"archived": false
}'
curl — OAuth-приложение
curl -X PATCH "https://vibecode.bitrix24.tech/v1/workgroups/85" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"description": "Обновлённое описание команды",
"opened": true,
"archived": false
}'
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups/85', {
method: 'PATCH',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
description: 'Обновлённое описание команды',
opened: true,
archived: false,
}),
})
const { success, data } = await res.json()
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups/85', {
method: 'PATCH',
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({
description: 'Обновлённое описание команды',
opened: true,
archived: false,
}),
})
const { success, data } = await res.json()
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata |
Типobject | ОписаниеПолный объект рабочей группы после обновления — все поля см. Получить рабочую группу |
Пример ответа
{
"success": true,
"data": {
"id": 85,
"siteId": "s1",
"name": "Маркетинг 2026",
"description": "Обновлённое описание команды",
"dateCreate": "2026-05-12T08:14:21.000Z",
"dateUpdate": "2026-05-26T05:58:08.000Z",
"active": true,
"visible": true,
"opened": true,
"archived": false,
"subjectId": 1,
"ownerId": 1,
"keywords": "проект,команда",
"membersCount": 7,
"dateActivity": "2026-05-26T05:58:08.000Z",
"subjectName": "Рабочие группы",
"isProject": false,
"isExtranet": false
}
}
Пример ответа при ошибке
Битрикс24 не различает «группа не существует» и «нет прав на обновление»:
{
"success": false,
"error": {
"code": "BITRIX_ERROR",
"message": "User has no permissions to update group"
}
}
Ошибки
| HTTP | error.code |
Описание |
|---|---|---|
| HTTP400 | error.codeREADONLY_FIELD |
ОписаниеВ теле передано поле, доступное только для чтения (id, subjectName, membersCount, dateCreate, dateUpdate, dateActivity, siteId, imageUrl, isExtranet) |
| HTTP422 | error.codeBITRIX_ERROR |
ОписаниеБитрикс24 отказал в обновлении. Текст в error.message. Типичные причины: ошибка валидации, конфликт значений, отсутствие прав на изменение, отсутствие рабочей группы с указанным id (два последних случая возвращают одинаковое сообщение) |
| HTTP401 | error.codeMISSING_API_KEY |
ОписаниеВ запросе не передан заголовок X-Api-Key |
| HTTP401 | error.codeINVALID_API_KEY |
ОписаниеКлюч не опознан: такой строки на платформе нет |
| HTTP403 | error.codeSCOPE_DENIED |
ОписаниеУ ключа нет скоупа sonet_group |
Полный список общих ошибок API — Ошибки.
Известные особенности
- Сообщение
User has no permissions to update groupвозвращается и при отсутствии рабочей группы с указаннымid, и при отсутствии прав на её изменение. Чтобы различить эти два случая, сделайте дополнительный запросGET /v1/workgroups/:id: ответ404— группы нет, успешный ответ — нет прав на изменение.