AI CodeOps

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

CampoTipoPor defecto
pullRequestURLURLuno de estos dos es obligatorio
commitSHAstring, 7 caracteres o más
blockingSeveritycritical, high, medium, low, infohigh
blockOnTestFailurebooleano: las pruebas que fallan bloquean, y también un cambio de código sin resultado de pruebastrue
blockOnBuildFailurebooleano: un build del repositorio que no pasó bloqueatrue
minCoveragePctnúmero de 0 a 100: un mínimo de cobertura; deniega si no se indicó coberturasin control
requiredWorkflowsarray de stringsninguno
disallowedLicensesarray de strings, comprobado con el SBOM del proyectoninguno
requireDeployedTonombre de entorno, p. ej. stagingninguno
blockOnInFlightbooleano: denegar mientras una ejecución sigue en cursofalse
lookbackMshasta cuándo mirar hacia atrás, en milisegundos14 días
workspaceIDid del espacio de trabajo: solo cuando llamas con una sesión de la consolael 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: true o false
  • summary y reasons: explicaciones en inglés sencillo
  • blockingFindings, testFailures, testEvidenceMissing, coverageShortfall, coverageNotReported, licenseViolations, licenseEvidenceMissing: los detalles que hay detrás de una denegación (licenseEvidenceMissing lista los proyectos sin SBOM que comprobar cuando pasas disallowedLicenses)
  • 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 nada
  • coverageNotReported: { "required": 80 } cuando fijas un mínimo y ninguna ejecución de pruebas indicó cobertura; null cuando existe una cifra de cobertura o no hay ningún mínimo fijado
  • runsConsidered: 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

EstadoSignificado
400JSON no válido o campos no válidos. Con una sesión de la consola: falta workspaceID, y el mensaje lo indica
401No hay clave de API ni sesión de la consola, o la clave no es válida
403El 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
429Má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:

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.

¿Te resultó útil esta página?