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:
curl \
-H "X-Acrity-Key: acr_live_..." \
"https://acrity.io/api/v1/context"
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 |
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 |
Retry-After y aplica backoff antes de reintentar.
Ejemplo de llamada
curl \
-H "X-Acrity-Key: acr_live_..." \
"https://acrity.io/api/v1/repositories?page=1&pageSize=25"
Empieza por /api/v1/context al diagnosticar una integración. Esa llamada confirma si la key está activa y qué alcances están disponibles.
