API pública

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 são criadas em 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`

Prefira uma API key por sistema consumidor. Isso facilita rotação, auditoria e limitação de escopo.

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

Respeite o 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.

Comece aqui

Console

Guias

Segurança

Referência

Base

Autenticação

Escopos

Recursos principais

Paginação e filtros

Erros

Limites de taxa

Exemplo de chamada

​Base

​Autenticação

​Escopos

​Recursos principais

​Paginação e filtros

​Erros

​Limites de taxa

​Exemplo de chamada

Base

Autenticação

Escopos

Recursos principais

Paginação e filtros

Erros

Limites de taxa

Exemplo de chamada