Referencia de la API
codqual es una API REST. Apunta hacia ella cualquier cliente HTTP o agente de programación con un token. Esta página documenta cada endpoint que una clave de API puede alcanzar.
Contrato estable para agentes
GET /issues, GET /reviews y GET /reviews/:id son la superficie pública estable, cubierta por tests de contrato — descrita por la especificación OpenAPI en https://api.codqual.com/openapi.json. Los demás endpoints de esta página funcionan con la misma key pero pueden evolucionar con el dashboard.
Autenticación
La API REST de codqual vive en una sola URL base. Cada petición debe incluir una clave de API como token en el encabezado Authorization.
https://api.codqual.com
Authorization: Bearer cc_...Crea claves en Configuración → API Keys, o copia la que se muestra una sola vez al registrarte. El secreto se muestra una sola vez; puedes revocar una clave cuando quieras.
curl -H "Authorization: Bearer $CODQUAL_API_KEY" https://api.codqual.com/reviewsEndpoints de lectura
Cada endpoint de lectura acepta el mismo token. Las listas regresan de más reciente a más antigua y se paginan con un cursor — pasa el valor cursor del último elemento para obtener la siguiente página.
| Endpoint | Devuelve | Parámetros útiles |
|---|---|---|
GET /reviews |
Tus revisiones, de más reciente a más antigua. | repo, focus, source, cursor (ISO date), limit (max 100) |
GET /reviews/:id |
Una revisión y todos sus hallazgos. | (UUID) |
GET /issues |
El estado de tus issues abiertos, deduplicado (hasta 500 issues). | repo, branch, status (default open), module, severity |
GET /issues/:id/timeline |
El historial completo de un issue — cada observación, cambio de estado y fusión. | — |
GET /scans/:id |
Una ejecución de escaneo. Consúltala en intervalos hasta que run.reviewId esté definido — eso es la finalización — y la misma respuesta entonces trae el escaneo y sus hallazgos. | — |
GET /repositories |
Los repositorios que puedes ver. | — |
GET /repositories/:fullName |
El detalle de un repositorio y su historial de revisiones. | — |
GET /repositories/:fullName/branches |
La lista de ramas en vivo del repositorio. | — |
GET /activity |
El feed de revisiones y escaneos de tu organización. | source, cursor |
GET /maturity |
El resultado actual de la rúbrica de madurez de 25 verificaciones para un repositorio. | repo |
GET /maturity/history |
La tendencia de la puntuación de madurez de un repositorio (hasta 90 puntos). | — |
curl -H "Authorization: Bearer $CODQUAL_API_KEY" "https://api.codqual.com/issues?status=open&severity=high"La API es de solo lectura
Una clave de API es una credencial de lectura. Lee los resultados que codqual ya produjo — tus issues, revisiones, hallazgos, escaneos y puntuaciones de madurez — y nada de esta página inicia un análisis.
El análisis tiene exactamente dos disparadores. La GitHub App revisa un pull request en cada push que le hagas. El panel escanea el repositorio completo cuando presionas Escanear ahora, o cuando corre el calendario semanal.
El panel también es dueño del resto de la superficie de escritura: crear y revocar claves de API, cambiar el estado de un issue, suprimir hallazgos, y administrar repositorios, equipos y webhooks. La retroalimentación sobre un hallazgo regresa por los comandos /codqual en comentarios de PR.
Errores
| Estado | Significado |
|---|---|
401 |
Tu clave de API falta o es inválida. |
404 |
No encontrado — o no es tuyo. codqual devuelve 404 en lugar de 403, para nunca confirmar que existe un recurso que no puedes ver. |
429 |
Se alcanzó el límite de tasa — 120 peticiones por minuto en los endpoints de lectura. |
Webhooks salientes
Configura los endpoints de webhook en Configuración → Webhooks (solo desde el panel). codqual envía por POST los eventos review.completed y finding.created a tu URL HTTPS, cada uno firmado con un secreto HMAC que se muestra una sola vez cuando creas el endpoint.