- Inicio
- Documentación
- La API
La API
Lo que puedes llamar hoy por API: el control de publicación para CI con una clave de API del espacio de trabajo y las claves públicas de los paquetes de evidencias. La API es limitada en la beta.
AI CodeOps se usa en el navegador. Durante la beta abierta, la API programática es pequeña a propósito: un endpoint para CI, más las claves públicas que permiten a cualquiera comprobar un paquete de evidencias. Todo lo demás de la consola necesita una sesión iniciada en el navegador y no es una API con soporte.
Claves de API del espacio de trabajo
Crea una clave en Configure → API Keys. Dale un nombre; el secreto (empieza por sk-) se muestra una sola vez, así que cópialo entonces. AI CodeOps solo guarda un hash.
- Una clave actúa como el miembro que la creó, con el rol actual de ese miembro. Si se elimina al miembro o su rol pierde un permiso, la clave también lo pierde.
- Los roles Owner, Admin, Developer y Member pueden crear claves. El rol Viewer no.
- Los Admin ven todas las claves del espacio de trabajo; los demás ven las suyas.
- Delete revoca una clave de inmediato. Las integraciones que la usan dejan de funcionar al instante.
Donde tu plan incluya la limitación del alcance de las claves, un administrador puede elegir Scope para limitar una clave a una lista de IP permitidas (rangos CIDR), a un límite de peticiones por minuto, a una fecha de caducidad y a aquello para lo que se puede usar: llamadas a la pasarela de modelos, la comprobación del control de publicación o ambas (el valor por defecto).
Envía la clave como un token Bearer:
Authorization: Bearer sk-...
Comprobación del control de publicación
POST /api/release/check responde a una pregunta para tu CI: ¿puede entregarse este pull request o este commit? Aplica las mismas comprobaciones que los controles de calidad en todas las sesiones que tocaron el cambio. La clave necesita el permiso workspace:read.
curl -sf -X POST "https://console.aicodeops.dev/api/release/check" \
-H "Authorization: Bearer $WORKSPACE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pullRequestURL":"https://github.com/acme/api/pull/42"}'
Usa el mismo host en el que abres la consola. El control de publicación en CI tiene jobs para copiar en GitHub Actions, GitLab CI, Bitbucket Pipelines, y Forgejo y Gitea Actions.
Campos de la petición
| Campo | Tipo | Por defecto |
|---|---|---|
pullRequestURL | URL | uno de estos dos es obligatorio |
commitSHA | string, 7 caracteres o más | |
blockingSeverity | critical, high, medium, low, info | high |
blockOnTestFailure | booleano: las pruebas que fallan bloquean, y también un cambio de código sin resultado de pruebas | true |
blockOnBuildFailure | booleano: un build del repositorio que no pasó bloquea | true |
minCoveragePct | número de 0 a 100: un mínimo de cobertura; deniega si no se indicó cobertura | sin control |
requiredWorkflows | array de strings | ninguno |
disallowedLicenses | array de strings, comprobado con el SBOM del proyecto | ninguno |
requireDeployedTo | nombre de entorno, p. ej. staging | ninguno |
blockOnInFlight | booleano: denegar mientras una ejecución sigue en curso | false |
lookbackMs | hasta cuándo mirar hacia atrás, en milisegundos | 14 días |
workspaceID | id del espacio de trabajo: solo cuando llamas con una sesión de la consola | el espacio de trabajo de la clave de API |
GET /api/release/check acepta los mismos nombres como parámetros de consulta (las listas, separadas por comas).
Evidencia de pruebas. Con blockOnTestFailure activado, que es el valor por defecto, toda sesión que cambió código en un proyecto necesita un resultado de pruebas con recuentos. Si no se ejecutó ninguna prueba para ella, o el comando de pruebas se ejecutó pero no indicó recuentos de pruebas, la comprobación deniega: "The test command ran but reported no test counts, so nothing shows a test passed. Check the project's test command". La falta de evidencia no equivale a superar el control. Para un proyecto sin suite de pruebas, activa Don't run tests for this project en los ajustes del proyecto, en Plan → Projects; la comprobación no exige entonces ningún resultado de pruebas. La regla tampoco se aplica a una sesión que no cambió código, ni cuando envías "blockOnTestFailure": false.
Mínimo de cobertura. Con minCoveragePct fijado, la ejecución de pruebas más reciente que indicó cobertura debe cumplirlo. Si ninguna ejecución de pruebas del cambio indicó cobertura, la comprobación deniega: "Coverage wasn't reported, so the 80% floor can't be checked". Un mínimo que no se puede comprobar no se da por superado. Haz que el comando de pruebas del proyecto imprima un resumen de cobertura antes de fijar un mínimo. Si omites minCoveragePct, la cobertura no se somete al control.
Llamar con una sesión de la consola. Una clave de API lleva consigo su espacio de trabajo, así que CI no envía ningún workspaceID. Una sesión iniciada en la consola también puede llamar al endpoint, y debe indicar el espacio de trabajo: añade ?workspaceID=<id> a la URL, o pon workspaceID en el cuerpo JSON de un POST. Sin él, la respuesta es 400. El id es la parte que va después de /workspace/ en la dirección de la consola.
Respuesta
El endpoint devuelve 200 en ambos casos. Lee allowed:
allowed:trueofalsesummaryyreasons: explicaciones en inglés sencilloblockingFindings,testFailures,testEvidenceMissing,coverageShortfall,coverageNotReported,licenseViolations,licenseEvidenceMissing: los detalles que hay detrás de una denegación (licenseEvidenceMissinglista los proyectos sin SBOM que comprobar cuando pasasdisallowedLicenses)testEvidenceMissing: un{ "workflowRunID", "reason" }por cada sesión que cambió código y no tiene un resultado de pruebas con recuentos; una lista vacía cuando no falta nadacoverageNotReported:{ "required": 80 }cuando fijas un mínimo y ninguna ejecución de pruebas indicó cobertura;nullcuando existe una cifra de cobertura o no hay ningún mínimo fijadorunsConsidered: las sesiones en las que se basó el veredicto
Un cambio sin sesiones que coincidan se deniega ("No workflow runs found for …"). También un cambio de código sin resultado de pruebas, como se describe en Evidencia de pruebas, más arriba. Si la evaluación falla, recibes allowed: false con el resumen "Evaluation failed", de modo que una comprobación rota nunca da por bueno un cambio.
Errores
| Estado | Significado |
|---|---|
| 400 | JSON no válido o campos no válidos. Con una sesión de la consola: falta workspaceID, y el mensaje lo indica |
| 401 | No hay clave de API ni sesión de la consola, o la clave no es válida |
| 403 | El Scope de la clave o el rol de su creador no lo permiten, o la clave pertenece a otro espacio de trabajo. Con una sesión: no eres miembro del espacio de trabajo |
| 429 | Más de 60 comprobaciones por minuto para el espacio de trabajo; consulta Retry-After |
La misma comprobación está en la consola en Review & Gate → Release gate, con un job de CI para copiar.
Claves de los paquetes de evidencias
GET /api/evidence?action=keys es público y no necesita ninguna clave. Devuelve las claves públicas Ed25519 que firman los paquetes de evidencias, para que puedas verificar un paquete sin conexión. Descargar un paquete requiere un miembro con la sesión iniciada y acceso de auditoría; no está disponible con una clave de API.
Referencia de la API
Una página por endpoint, generada a partir de la especificación OpenAPI:
- Comprobar si un pull request o un commit puede entregarse
- Las claves que firman los paquetes de evidencias
- Verificar un paquete de evidencias
- Liveness y readiness
- Estado de los componentes
Siguientes pasos
Preguntas frecuentes
¿Hay una API REST completa para sesiones y proyectos?
Todavía no. Durante la beta abierta, la consola es la forma de ejecutar sesiones y gestionar proyectos. Los endpoints de esta página son los que aceptan acceso programático.
¿Las claves de API caducan?
No por defecto. Una clave funciona hasta que se elimina, hasta que su creador deja el espacio de trabajo o hasta que pasa una fecha de caducidad fijada en su Scope.