Для AI-агентов: markdown этой страницы — /docs-content/entities/workgroups/list.md индекс документации — /llms.txt
Список рабочих групп
GET /v1/workgroups
Возвращает список рабочих групп портала с поддержкой фильтрации, сортировки и автоматической пагинации.
Параметры
| Параметр | Тип | Обяз. | По умолч. | Описание |
|---|---|---|---|---|
Параметрfilter (query) |
Типobject | Обяз.нет | По умолч.— | ОписаниеФильтрация по полям GET /v1/workgroups/fields. Синтаксис фильтрации. Пример: ?filter[archived]=N |
Параметрselect (query) |
Типarray | Обяз.нет | По умолч.— | ОписаниеСписок полей в ответе. Имена — из GET /v1/workgroups/fields. |
Параметрsort (query) |
Типstring | Обяз.нет | По умолч.— | ОписаниеСортировка: ?sort=dateCreate — по возрастанию, ?sort=-dateCreate — по убыванию. Принимаются и формы ?sort[dateCreate]=DESC и ?order[dateCreate]=desc |
Параметрlimit (query) |
Типnumber | Обяз.нет | По умолч.50 |
ОписаниеМаксимум записей в ответе. Допустимо до 5000. |
Параметрoffset (query) |
Типnumber | Обяз.нет | По умолч.0 |
ОписаниеСмещение от начала выборки. |
Параметрinclude (query) |
Типstring | Обяз.нет | По умолч.— | ОписаниеСвязанные данные: owner — владелец группы. Подробнее — секция «Связанные данные» ниже |
ПараметрwithTotal (query) |
Типstring | Обяз.нет | По умолч.— | ОписаниеРаспознаются значения true и false. Для рабочих групп параметр на ответ не влияет: meta.total приходит и при withTotal=false |
Для limit > 50 Вайбкод автоматически пагинирует запрос на стороне сервера. Максимум — 5000 записей за вызов. Если под фильтр попадает больше — meta.hasMore придёт true.
Получить только проекты
В одной коллекции хранятся и рабочие группы, и проекты. Поле isProject различает их: true — проект, false — обычная рабочая группа. Для выборки проектов передавайте filter[isProject]=Y.
Примеры
curl — личный ключ
curl "https://vibecode.bitrix24.tech/v1/workgroups?limit=3" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl "https://vibecode.bitrix24.tech/v1/workgroups?limit=3" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups?limit=3', {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
},
})
const { success, data, meta } = await res.json()
console.log(`Найдено ${meta.total} рабочих групп`)
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups?limit=3', {
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
},
})
const { success, data, meta } = await res.json()
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata |
Типarray | ОписаниеМассив рабочих групп (все поля — см. Поля рабочей группы) |
Полеmeta.total |
Типnumber | ОписаниеОбщее количество записей, соответствующих фильтру |
Полеmeta.hasMore |
Типboolean | ОписаниеЕсть ли ещё записи за пределами limit |
Полеmeta.includeSkipped |
Типboolean | Описаниеtrue, если в ответе больше 200 записей и связи из include не загружены. Уменьшите limit. При 200 записях и меньше ключа нет |
Связанные данные
Получить владельца каждой группы вместе со списком — параметр include в GET-запросе:
GET /v1/workgroups?limit=2&include=owner
Доступное значение include:
| Имя | По какому полю | Ключ в _included |
Результат |
|---|---|---|---|
Имяowner |
По какому полюownerId — владелец группы |
Ключ в _includedowner |
РезультатКарточка сотрудника |
Карточка сотрудника та же, что в ответе GET /v1/users/:id. Связь читает сотрудника, поэтому ключу кроме sonet_group нужен скоуп user. Результат — в поле _included каждого элемента data:
{
"success": true,
"data": [
{
"id": 79,
"name": "Маркетинг 2026",
"ownerId": 1269,
"isProject": true,
"_included": {
"owner": { "id": 1269, "name": "Иван", "lastName": "Петров", "email": "ivan.petrov@example.com", "active": true }
}
}
],
"meta": { "total": 29, "hasMore": true }
}
Показаны основные поля группы и сотрудника. Полный состав карточки — Поля сотрудника.
Пример ответа
{
"success": true,
"data": [
{
"id": 85,
"siteId": "s1",
"name": "Маркетинг 2026",
"description": null,
"dateCreate": "2026-03-20T06:45:10.000Z",
"dateUpdate": "2026-03-20T06:45:10.000Z",
"active": true,
"visible": true,
"opened": false,
"archived": false,
"subjectId": 1,
"ownerId": 1271,
"keywords": null,
"membersCount": 2,
"dateActivity": "2026-03-20T06:45:10.000Z",
"subjectName": "Рабочие группы",
"isProject": true,
"isExtranet": false
},
{
"id": 83,
"siteId": "s1",
"name": "Команда разработки нового продукта",
"description": null,
"dateCreate": "2026-03-20T06:41:07.000Z",
"dateUpdate": "2026-03-20T06:41:07.000Z",
"active": true,
"visible": true,
"opened": false,
"archived": false,
"subjectId": 1,
"ownerId": 1269,
"keywords": null,
"membersCount": 1,
"dateActivity": "2026-03-20T06:41:07.000Z",
"subjectName": "Рабочие группы",
"isProject": true,
"imageUrl": "https://cdn-ru.bitrix24.ru/example/disk/avatar.jpg",
"isExtranet": false
},
{
"id": 81,
"siteId": "s1",
"name": "Запуск регионального офиса",
"description": null,
"dateCreate": "2026-03-20T06:29:07.000Z",
"dateUpdate": "2026-03-20T06:29:07.000Z",
"active": true,
"visible": true,
"opened": false,
"archived": false,
"subjectId": 1,
"ownerId": 1271,
"keywords": null,
"membersCount": 1,
"dateActivity": "2026-03-20T06:29:07.000Z",
"subjectName": "Рабочие группы",
"isProject": true,
"isExtranet": false
}
],
"meta": {
"total": 33,
"hasMore": true
}
}
Пример ответа при ошибке
401 — нет ключа авторизации:
{
"success": false,
"error": {
"code": "MISSING_API_KEY",
"message": "API key required. Pass via X-Api-Key header."
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодINVALID_INCLUDE |
ОписаниеВ include передано неизвестное имя. Сообщение перечисляет доступные: Unknown include 'bad'. Available: owner |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP401 | КодINVALID_API_KEY |
ОписаниеКлюч не опознан: такой строки на платформе нет |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеКлючу не хватает скоупа sonet_group |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеПередан include=owner, а у ключа нет скоупа user |
| HTTP429 | КодRATE_LIMITED |
ОписаниеПревышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After |
Полный список общих ошибок API — Ошибки.
Известные особенности
Логические поля в фильтре принимают Y / N. В ответе те же поля приходят как true / false, но при фильтрации используйте filter[active]=Y / filter[archived]=N. Значения true / false в фильтре не дадут совпадений и не вызовут ошибку.
Префикс % в имени поля — поиск по подстроке. ?filter[%name]=Маркетинг найдёт все группы, в названии которых встречается «Маркетинг». Без префикса фильтр требует точного совпадения.
limit = 0 не является размером страницы — параметр отбрасывается, применяется значение по умолчанию (50), а в ответ добавляется предупреждение LIMIT_ZERO_IGNORED в meta.warnings. Чтобы прочитать всю коллекцию, передайте явный limit (до 5000). Для пустой выборки используйте фильтр, который заведомо ничего не находит.