A API pública da Acrity permite consultar contexto do workspace, repositórios, pull requests, reviews, webhooks, credenciais, bootstrap e security scans, conforme os escopos da API key.
Base
Rotas públicas usam o prefixo /api/v1. A documentação OpenAPI fica disponível no ambiente da Acrity em:
/docs, para visualização interativa;/openapi/v1-public.json, para consumo por ferramentas;- variantes localizadas quando habilitadas, como
/openapi/v1-public.pt-BR.json.
Autenticação
Use o header X-Acrity-Key:
curl \
-H "X-Acrity-Key: acr_live_..." \
"https://acrity.io/api/v1/context"
API Keys. Criar uma API key requer um admin do Workspace.
Escopos
| Família | Leitura | Escrita |
|---|
| Reviews | Reviews.Read | Reviews.Write |
| Repositórios | Repositories.Read | Repositories.Write |
| Credenciais | Credentials.Read | Credentials.Write |
| Webhooks | Webhooks.Read | Webhooks.Write |
| Workspaces | Workspaces.Read | Workspaces.Write |
| Security scans | SecurityScans.Read | SecurityScans.Write |
Recursos principais
| Recurso | Uso comum |
|---|
| Contexto | validar API key, workspace e escopos visíveis |
| Repositórios | listar, consultar status e gerenciar conexões autorizadas |
| Pull requests | localizar mudanças revisadas pela Acrity |
| Reviews | listar histórico, consultar achados e solicitar review quando permitido |
| Webhooks | criar, listar, consultar, atualizar e habilitar ou desabilitar webhooks de saída (sem exclusão definitiva) |
| Workspaces | consultar informações e saúde do workspace |
| Credenciais | consultar metadados e administrar credenciais autorizadas |
| Bootstrap | verificar elegibilidade e acompanhar geração de orientação de arquitetura |
| Security scans | listar, consultar e iniciar scans de dependências |
Paginação e filtros
Listagens podem usar paginação e filtros. Consulte a especificação OpenAPI do seu ambiente para os parâmetros exatos de cada recurso.
O tamanho de página padrão é 20 e o máximo é 50. Uma requisição com tamanho de página acima de 50 retorna 400.
Boas práticas:
- use páginas pequenas em integrações recorrentes;
- mantenha o cursor ou a página processada na automação;
- trate respostas vazias como estado válido;
- aplique backoff em
429.
Erros
| Status | Significado |
|---|
400 | requisição inválida |
401 | API key ausente, inválida, expirada ou inativa |
403 | API key válida, mas sem escopo necessário |
404 | recurso não encontrado ou não visível para o workspace |
409 | conflito com estado atual do recurso |
429 | limite de uso atingido |
5xx | erro temporário ou indisponibilidade |
Limites de taxa
Cada API key é limitada a cerca de 300 requisições por minuto por padrão. Quando você excede o limite, a API retorna 429 junto com estes headers de resposta:
| Header | Significado |
|---|
Retry-After | segundos a aguardar antes de tentar novamente |
X-RateLimit-Limit | requisições permitidas por janela |
X-RateLimit-Remaining | requisições restantes na janela atual |
X-RateLimit-Reset | momento em que a janela atual é reiniciada |
Retry-After e aplique backoff antes de tentar novamente.
Exemplo de chamada
curl \
-H "X-Acrity-Key: acr_live_..." \
"https://acrity.io/api/v1/repositories?page=1&pageSize=25"
Comece por /api/v1/context ao diagnosticar uma integração. Essa chamada confirma se a key está ativa e quais escopos estão disponíveis.
