Pular para o conteúdo
Sursa Developers

GET/v1/groups

Listar os grupos da organização

list_groups

Sem kind, retorna os grupos comuns, “All members” e os grupos de função. Os grupos pessoais (single_user) só são retornados com um kind=single_user explícito. Os membros dos grupos all_members, role e single_user são calculados a partir dos usuários da organização, assim como o members_count deles.

Autenticação

Envie uma chave de API no cabeçalho Authorization: Authorization: Bearer <chave>.

Parâmetros de consulta

  • kindGroupKind
  • limitinteger

    Tamanho da página. Sem limit e cursor, a lista inteira é retornada; com esse parâmetro, no máximo limit itens, e a próxima página é informada nos cabeçalhos Link (rel="next") e X-Next-Cursor.

    ≥ 1, ≤ 200

  • cursorstring

    Cursor da próxima página, vindo de X-Next-Cursor ou de next_cursor da resposta anterior com os mesmos filtros; ele carrega o tamanho da página. Junto com offset: 422 validation.failed; um cursor de outra lista, de outros filtros ou malformado: 400 api.cursor_invalid.

    length ≤ 512

  • updated_sincestring (date-time)

    Só objetos com updated_at igual ou posterior a este momento (RFC 3339 com deslocamento de fuso horário), para sincronização. Com ele, a lista é ordenada por updated_at em ordem crescente e depois por id, e o cursor continua nessa ordem. Objetos excluídos não aparecem na lista: as exclusões chegam como eventos.

    length ≤ 512

Respostas

200Resposta bem-sucedida

Cabeçalhos da resposta

  • Link

    Endereço da próxima página, <…>; rel="next". Sem o cabeçalho, esta é a última página.

  • X-Next-Cursor

    Cursor da próxima página para o parâmetro cursor. Sem o cabeçalho, esta é a última página.

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: GroupList

array of Group
  • idintegerobrigatório
  • org_idintegerobrigatório
  • keystringobrigatório

    Chave estável: all, role:<role>, user:<id> ou a chave de um grupo comum. A interface traduz os grupos internos pela chave.

  • titlestringobrigatório
  • kindGroupKindobrigatório
  • user_idinteger | nullobrigatório

    Só nos grupos pessoais.

  • role_keyRole | nullobrigatório

    Só nos grupos de função.

  • managed_byGroupManagedByobrigatório
  • members_countintegerobrigatório

    Número de membros ativos. Usuários desativados não são membros de grupos.

  • disabledbooleanobrigatório

    O grupo pessoal de um usuário desativado: as concessões dele são mantidas, mas não têm efeito enquanto o usuário está inativo. false em todos os outros grupos.

  • created_atstring (date-time)obrigatório
  • updated_atstring (date-time)obrigatório
401Nenhuma credencial foi enviada (nem cookie de sessão nem chave de API), ou a chave não foi encontrada.

Cabeçalhos da resposta

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

422Erro de validação: o corpo ou os parâmetros não correspondem ao esquema (`detail` é uma lista de erros de validação), ou o valor de um parâmetro está fora do intervalo (`detail` é uma mensagem).

Cabeçalhos da resposta

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

429Requisições demais (`api.rate_limited`), a cota da organização para o minuto, o dia ou o mês se esgotou (`api.quota_exceeded`; `error.details` contém `quota`, `limit` e `reset_at`), o limite da organização foi atingido ou o serviço de respostas está ocupado (`answers.engine_busy`). Aguarde o tempo indicado no cabeçalho `Retry-After`.

Cabeçalhos da resposta

  • Retry-After

    Número de segundos a esperar antes de tentar a requisição novamente.

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

Códigos de erro

Códigos que este endpoint pode retornar em error.code, além dos códigos gerais de qualquer requisição.

Limites de taxa

As respostas trazem os cabeçalhos RateLimit e RateLimit-Policy e os anteriores X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Uma resposta 429 traz Retry-After em segundos: aguarde e tente de novo.

← groups · Referência da API