Ir al contenido
Sursa Developers

GET/v1/groups

Listar los grupos de la organización

list_groups

Sin kind, devuelve los grupos normales, «All members» y los grupos de rol. Los grupos personales (single_user) solo se devuelven con un kind=single_user explícito. La pertenencia a los grupos all_members, role y single_user se calcula a partir de los usuarios de la organización, igual que su members_count.

Autenticación

Envíe una clave de API en el encabezado Authorization: Authorization: Bearer <clave>.

Parámetros de consulta

  • kindGroupKind
  • limitinteger

    Tamaño de página. Sin limit ni cursor se devuelve la lista completa; con él, como máximo limit elementos, y la página siguiente se indica en los encabezados Link (rel="next") y X-Next-Cursor.

    ≥ 1, ≤ 200

  • cursorstring

    Cursor de la página siguiente, tomado de X-Next-Cursor o de next_cursor de la respuesta anterior con los mismos filtros; incluye el tamaño de página. Junto con offset: 422 validation.failed; un cursor de otra lista, de otros filtros o mal formado: 400 api.cursor_invalid.

    length ≤ 512

  • updated_sincestring (date-time)

    Solo los objetos con updated_at igual o posterior a este momento (RFC 3339 con desfase horario), para la sincronización. Con él, la lista se ordena por updated_at ascendente y después por id, y el cursor continúa en ese orden. Los objetos eliminados no aparecen en la lista: las eliminaciones llegan como eventos.

    length ≤ 512

Respuestas

200Respuesta correcta

Encabezados de la respuesta

  • Link

    Dirección de la página siguiente, <…>; rel="next". Si no hay encabezado, es la última página.

  • X-Next-Cursor

    Cursor de la página siguiente para el parámetro cursor. Si no hay encabezado, es la última página.

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: GroupList

array of Group
  • idintegerobligatorio
  • org_idintegerobligatorio
  • keystringobligatorio

    Clave estable: all, role:<role>, user:<id> o la clave de un grupo normal. La interfaz traduce los grupos integrados según su clave.

  • titlestringobligatorio
  • kindGroupKindobligatorio
  • user_idinteger | nullobligatorio

    Solo en los grupos personales.

  • role_keyRole | nullobligatorio

    Solo en los grupos de rol.

  • managed_byGroupManagedByobligatorio
  • members_countintegerobligatorio

    Número de miembros activos. Los usuarios desactivados no son miembros de grupos.

  • disabledbooleanobligatorio

    El grupo personal de un usuario desactivado: sus concesiones se conservan, pero no tienen efecto mientras el usuario esté inactivo. false en todos los demás grupos.

  • created_atstring (date-time)obligatorio
  • updated_atstring (date-time)obligatorio
401No se enviaron credenciales (ni una cookie de sesión ni una clave de API) o no se encontró la clave.

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

422Error de validación: el cuerpo o los parámetros no coinciden con el esquema (`detail` es una lista de errores de validación), o el valor de un parámetro está fuera del rango permitido (`detail` es un mensaje).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

429Demasiadas solicitudes (`api.rate_limited`), se agotó la cuota de la organización para el minuto, el día o el mes (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` y `reset_at`), se alcanzó el límite de la organización o el servicio de respuestas está ocupado (`answers.engine_busy`). Espere el tiempo indicado en el encabezado `Retry-After`.

Encabezados de la respuesta

  • Retry-After

    Número de segundos que hay que esperar antes de reintentar la solicitud.

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

Códigos de error

Códigos que este endpoint puede devolver en error.code, además de los códigos generales de cualquier solicitud.

Límites de frecuencia

Las respuestas incluyen los encabezados RateLimit y RateLimit-Policy y los anteriores X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una respuesta 429 lleva Retry-After en segundos: espere y vuelva a intentarlo.

← groups · Referencia de la API