GET/v1/catalog/services
Listar os serviços do catálogo
list_catalog_services
Retorna itens do catálogo global de serviços externos (SaaS e fornecedores): busca por substring, sem diferenciar maiúsculas de minúsculas, no nome, no grupo ou no domínio do site, filtro por categoria e paginação. A contagem total para o filtro fica no cabeçalho X-Total-Count. O catálogo é compartilhado por todas as organizações e está disponível para qualquer usuário autenticado. Os dados dele vêm com o Sursa e são atualizados a cada versão (a versão fica em GET /v1/catalog/categories e no campo version do icon_url de cada item).
Autenticação
Envie uma chave de API no cabeçalho Authorization: Authorization: Bearer <chave>.
Parâmetros de consulta
qstring | nullSubstring do nome, do grupo ou do domínio do site (sem diferenciar maiúsculas de minúsculas).
length ≤ 200
categorystring | nullSlug da categoria (
GET /v1/catalog/categories).offsetintegerPadrão: 0≥ 0
limitintegerPadrão: 50≥ 1, ≤ 500
cursorstringCursor da próxima página, vindo de
X-Next-Cursorou denext_cursorda resposta anterior com os mesmos filtros; ele carrega o tamanho da página. Junto comoffset:422 validation.failed; um cursor de outra lista, de outros filtros ou malformado:400 api.cursor_invalid.length ≤ 512
Parâmetros de cabeçalho
X-View-AsstringSó para chaves de API com a função
admin. Faz a requisição como o perfil de dados<profile>[:viewer|verifier|editor], por exemplo,employee:viewer. A chave de instalação não pode usar este cabeçalho (403).
Parâmetros de cookie
kb_view_asstringCookie do modo “View as” (ver a base como um perfil de dados a vê) de uma sessão.
POST /auth/view-aso define eDELETE /auth/view-aso remove.
Respostas
200Resposta bem-sucedida
Cabeçalhos da resposta
LinkEndereço da próxima página,
<…>; rel="next". Sem o cabeçalho, esta é a última página.X-Next-CursorCursor da próxima página para o parâmetro
cursor. Sem o cabeçalho, esta é a última página.X-Total-CountNúmero total de itens que correspondem ao filtro, independentemente de
limiteoffset.RateLimit-PolicyLimites 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,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
categorystringobrigatórioSlug da categoria (
GET /v1/catalog/categories).description_enstring | nullobrigatórioDescrição curta em inglês.
nullse não há descrição.domainstring | nullobrigatórioDomínio do site sem
www..nullse não há site.group_namestring | nullobrigatórioGrupo (fornecedor) se o serviço pertence a uma família de produtos, por exemplo Atlassian; caso contrário,
null.iconbooleanobrigatórioIndica se um ícone vem junto com o Sursa.
icon_urlstring | nullobrigatórioURL do ícone (
/v1/catalog/services/{service_id}/icon?v=…ou um endereço externo configurado pela instalação).nullse não há ícone.idstring (uuid)obrigatórionamestringobrigatórioslugstringobrigatóriowebsitestring | nullobrigatórioURL do site (
https://…) ounull.
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-PolicyLimites 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,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
403A ação não é permitida: a função é insuficiente, não há acesso à coleção ou ao cartão, a requisição é executada no modo “View as” ou a organização está suspensa ou excluída (`detail` é um objeto com `code: org_suspended | org_deleted`).
Cabeçalhos da resposta
RateLimit-PolicyLimites 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,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
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-PolicyLimites 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,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
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-AfterNúmero de segundos a esperar antes de tentar a requisição novamente.
RateLimit-PolicyLimites 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,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
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.