Для 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 — личный ключ

Terminal
curl "https://vibecode.bitrix24.tech/v1/workgroups?limit=3" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal
curl "https://vibecode.bitrix24.tech/v1/workgroups?limit=3" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

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-приложение

javascript
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:

JSON
{
  "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 }
}

Показаны основные поля группы и сотрудника. Полный состав карточки — Поля сотрудника.

Пример ответа

JSON
{
  "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 — нет ключа авторизации:

JSON
{
  "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). Для пустой выборки используйте фильтр, который заведомо ничего не находит.

Смотрите также