Перейти к содержанию
Sursa для разработчиков

GET/v1/groups

Получить список групп организации

list_groups

Без kind возвращает обычные группы, «Все участники» и группы ролей. Личные группы (single_user) возвращаются только при явном kind=single_user. Состав групп all_members, role и single_user вычисляется по пользователям организации, как и их members_count.

Аутентификация

Передайте ключ API в заголовке Authorization: Authorization: Bearer <ключ>.

Параметры запроса

  • kindGroupKind
  • limitinteger

    Размер страницы. Без limit и cursor возвращается весь список; с ним — не больше limit элементов, а следующая страница указывается в заголовках Link (rel="next") и X-Next-Cursor.

    ≥ 1, ≤ 200

  • cursorstring

    Курсор следующей страницы из X-Next-Cursor или next_cursor предыдущего ответа с теми же фильтрами; он несёт размер страницы. Вместе с offset — 422 validation.failed; курсор другого списка, других фильтров или испорченный — 400 api.cursor_invalid.

    length ≤ 512

  • updated_sincestring (date-time)

    Только объекты, у которых updated_at не раньше этого момента (RFC 3339 со смещением), — для синхронизации. С этим параметром список сортируется по updated_at по возрастанию, затем по id, и курсор продолжает в том же порядке. Удалённые объекты в список не попадают: об удалениях сообщают события.

    length ≤ 512

Ответы

200Успешный ответ

Заголовки ответа

  • Link

    Адрес следующей страницы, <…>; rel="next". Нет заголовка — это последняя страница.

  • X-Next-Cursor

    Курсор следующей страницы для параметра cursor. Нет заголовка — это последняя страница.

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: GroupList

array of Group
  • idintegerобязательно
  • org_idintegerобязательно
  • keystringобязательно

    Постоянный ключ: all, role:<role>, user:<id> или ключ обычной группы. Встроенные группы интерфейс переводит по ключу.

  • titlestringобязательно
  • kindGroupKindобязательно
  • user_idinteger | nullобязательно

    Только у личных групп.

  • role_keyRole | nullобязательно

    Только у групп ролей.

  • managed_byGroupManagedByобязательно
  • members_countintegerобязательно

    Число активных участников. Деактивированные пользователи в группах не состоят.

  • disabledbooleanобязательно

    Личная группа деактивированного пользователя: её назначения сохраняются, но не действуют, пока пользователь неактивен. false у всех остальных групп.

  • created_atstring (date-time)обязательно
  • updated_atstring (date-time)обязательно
401Учётные данные не переданы (нет ни cookie сессии, ни ключа API) или ключ не найден.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

422Ошибка проверки: тело или параметры не соответствуют схеме (`detail` — список ошибок проверки) либо значение параметра вне допустимого диапазона (`detail` — сообщение).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

429Слишком много запросов (`api.rate_limited`), квота организации на минуту, день или месяц исчерпана (`api.quota_exceeded`; в `error.details` — `quota`, `limit` и `reset_at`), достигнут лимит организации или сервис ответов занят (`answers.engine_busy`). Подождите время, указанное в заголовке `Retry-After`.

Заголовки ответа

  • Retry-After

    Сколько секунд подождать перед повтором запроса.

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

Коды ошибок

Коды, которые эта операция может вернуть в error.code, помимо общих кодов любого запроса.

Лимиты частоты

В ответах есть заголовки RateLimit и RateLimit-Policy, а также прежние X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. В ответе 429 есть Retry-After в секундах: подождите и повторите запрос.

← groups · Справочник API