> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acrity.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API pública

> Autenticação, escopos, recursos e boas práticas para usar a API pública da Acrity.

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`:

```bash theme={null}
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

```bash theme={null}
curl \
  -H "X-Acrity-Key: acr_live_..." \
  "https://acrity.io/api/v1/repositories?page=1&pageSize=25"
```

<Tip>
  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.
</Tip>