Перейти до вмісту
Sursa Developers

GET/v1/groups

Отримати список груп організації

list_groups

Без kind повертає звичайні групи, «All members» і групи ролей. Особисті групи (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