Aller au contenu
Sursa Developers

GET/v1/groups

Lister les groupes de l’organisation

list_groups

Sans kind, renvoie les groupes ordinaires, « All members » et les groupes de rôle. Les groupes personnels (single_user) ne sont renvoyés qu’avec un kind=single_user explicite. L’appartenance aux groupes all_members, role et single_user est calculée à partir des utilisateurs de l’organisation, de même que leur members_count.

Authentification

Envoyez une clé API dans l’en-tête Authorization : Authorization: Bearer <clé>.

Paramètres de requête

  • kindGroupKind
  • limitinteger

    Taille de page. Sans limit ni cursor, la liste entière est renvoyée ; avec ces paramètres, au plus limit éléments, et la page suivante est indiquée dans les en-têtes Link (rel="next") et X-Next-Cursor.

    ≥ 1, ≤ 200

  • cursorstring

    Curseur de la page suivante, tiré de X-Next-Cursor ou de next_cursor de la réponse précédente avec les mêmes filtres ; il porte la taille de page. Avec offset : 422 validation.failed ; curseur d’une autre liste, d’autres filtres ou mal formé : 400 api.cursor_invalid.

    length ≤ 512

  • updated_sincestring (date-time)

    Uniquement les objets dont updated_at est égal ou postérieur à ce moment (RFC 3339 avec décalage horaire), pour la synchronisation. Avec ce paramètre, la liste est triée par updated_at croissant, puis par id, et le curseur suit cet ordre. Les objets supprimés ne sont pas listés : les suppressions arrivent sous forme d’événements.

    length ≤ 512

Réponses

200Réponse réussie

En-têtes de la réponse

  • Link

    Adresse de la page suivante, <…>; rel="next". L’absence de cet en-tête signifie qu’il s’agit de la dernière page.

  • X-Next-Cursor

    Curseur de la page suivante pour le paramètre cursor. L’absence de cet en-tête signifie qu’il s’agit de la dernière page.

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : GroupList

array of Group
  • idintegerobligatoire
  • org_idintegerobligatoire
  • keystringobligatoire

    Clé stable : all, role:<role>, user:<id> ou la clé d’un groupe ordinaire. L’interface traduit les groupes intégrés d’après leur clé.

  • titlestringobligatoire
  • kindGroupKindobligatoire
  • user_idinteger | nullobligatoire

    Groupes personnels uniquement.

  • role_keyRole | nullobligatoire

    Groupes de rôle uniquement.

  • managed_byGroupManagedByobligatoire
  • members_countintegerobligatoire

    Nombre de membres actifs. Les utilisateurs désactivés ne sont membres d’aucun groupe.

  • disabledbooleanobligatoire

    Groupe personnel d’un utilisateur désactivé : ses attributions sont conservées mais restent sans effet tant que l’utilisateur est inactif. false pour tous les autres groupes.

  • created_atstring (date-time)obligatoire
  • updated_atstring (date-time)obligatoire
401Aucun identifiant n’a été envoyé (ni cookie de session ni clé API), ou la clé est introuvable.

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

422Erreur de validation : le corps ou les paramètres ne correspondent pas au schéma (`detail` est une liste d’erreurs de validation), ou la valeur d’un paramètre est hors des limites admises (`detail` est un message).

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

429Trop de requêtes (`api.rate_limited`), quota de l’organisation pour la minute, le jour ou le mois épuisé (`api.quota_exceeded` ; `error.details` contient `quota`, `limit` et `reset_at`), limite de l’organisation atteinte, ou service de réponses occupé (`answers.engine_busy`). Attendez le délai indiqué dans l’en-tête `Retry-After`.

En-têtes de la réponse

  • Retry-After

    Nombre de secondes à attendre avant de réessayer la requête.

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

Codes d’erreur

Codes que ce point de terminaison peut renvoyer dans error.code, en plus des codes généraux communs à toutes les requêtes.

Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy, ainsi que les anciens X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 contient Retry-After en secondes : attendez, puis réessayez.

← groups · Référence de l’API