> ## 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

> Autenticación, alcances, recursos y buenas prácticas para usar la API pública de Acrity.

La API pública de Acrity permite consultar contexto del workspace, repositorios, pull requests, reviews, webhooks, credenciales, bootstrap y security scans, conforme a los alcances de la API key.

## Base

Las rutas públicas usan el prefijo `/api/v1`. La documentación OpenAPI está disponible en el ambiente de Acrity en:

* `/docs`, para visualización interactiva;
* `/openapi/v1-public.json`, para consumo por herramientas;
* variantes localizadas cuando estén habilitadas, como `/openapi/v1-public.pt-BR.json`.

## Autenticación

Usa el header `X-Acrity-Key`:

```bash theme={null}
curl \
  -H "X-Acrity-Key: acr_live_..." \
  "https://acrity.io/api/v1/context"
```

Las API keys se crean en `API Keys`. Crear una API key requiere un administrador del Workspace (los administradores de plataforma también tienen acceso).

## Alcances

| Familia        | Lectura              | Escritura             |
| -------------- | -------------------- | --------------------- |
| Reviews        | `Reviews.Read`       | `Reviews.Write`       |
| Repositorios   | `Repositories.Read`  | `Repositories.Write`  |
| Credenciales   | `Credentials.Read`   | `Credentials.Write`   |
| Webhooks       | `Webhooks.Read`      | `Webhooks.Write`      |
| Workspaces     | `Workspaces.Read`    | `Workspaces.Write`    |
| Security scans | `SecurityScans.Read` | `SecurityScans.Write` |

Prefiere una API key por sistema consumidor. Esto facilita la rotación, la auditoría y la limitación de alcance.

## Recursos principales

| Recurso        | Uso común                                                                                                      |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| Contexto       | validar API key, workspace y alcances visibles                                                                 |
| Repositorios   | listar, consultar estado y gestionar conexiones autorizadas                                                    |
| Pull requests  | ubicar cambios revisados por Acrity                                                                            |
| Reviews        | listar historial, consultar hallazgos y solicitar review cuando esté permitido                                 |
| Webhooks       | crear, listar, consultar, actualizar y habilitar o deshabilitar webhooks outbound (sin eliminación definitiva) |
| Workspaces     | consultar la información y la salud del workspace                                                              |
| Credenciales   | consultar metadatos y administrar credenciales autorizadas                                                     |
| Bootstrap      | verificar elegibilidad y dar seguimiento a la generación de orientación de arquitectura                        |
| Security scans | listar, consultar e iniciar scans de dependencias                                                              |

## Paginación y filtros

Los listados pueden usar paginación y filtros. Consulta la especificación OpenAPI de tu ambiente para conocer los parámetros exactos de cada recurso.

El tamaño de página predeterminado es 20 y el máximo es 50. Una solicitud con un tamaño de página superior a 50 devuelve `400`.

Buenas prácticas:

* usa páginas pequeñas en integraciones recurrentes;
* mantén el cursor o la página procesada en la automatización;
* trata las respuestas vacías como un estado válido;
* aplica backoff en `429`.

## Errores

| Status | Significado                                          |
| ------ | ---------------------------------------------------- |
| `400`  | solicitud inválida                                   |
| `401`  | API key ausente, inválida, expirada o inactiva       |
| `403`  | API key válida, pero sin el alcance requerido        |
| `404`  | recurso no encontrado o no visible para el workspace |
| `409`  | conflicto con el estado actual del recurso           |
| `429`  | límite de uso alcanzado                              |
| `5xx`  | error temporal o indisponibilidad                    |

## Límites de tasa

Cada API key está limitada a aproximadamente 300 solicitudes por minuto de forma predeterminada. Cuando superas el límite, la API devuelve `429` junto con estos headers de respuesta:

| Header                  | Significado                                  |
| ----------------------- | -------------------------------------------- |
| `Retry-After`           | segundos a esperar antes de reintentar       |
| `X-RateLimit-Limit`     | solicitudes permitidas por ventana           |
| `X-RateLimit-Remaining` | solicitudes restantes en la ventana actual   |
| `X-RateLimit-Reset`     | momento en que se reinicia la ventana actual |

Respeta `Retry-After` y aplica backoff antes de reintentar.

## Ejemplo de llamada

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

<Tip>
  Empieza por `/api/v1/context` al diagnosticar una integración. Esa llamada confirma si la key está activa y qué alcances están disponibles.
</Tip>