Documentación · API REST

API REST

Una API JSON sobre HTTPS para todo lo que hace la app de vetkit. Úsala para iniciar auditorías desde CI, condicionar los lanzamientos a una calificación o enviar SARIF al code scanning de GitHub.

Descripción general

URL base	`https://api.vetkit.dev/v1`
OpenAPI	`https://api.vetkit.dev/v1/openapi.json` — la referencia completa y legible por máquina de todas las rutas y esquemas
Formato	Cuerpos de solicitud y respuesta en JSON, marcas de tiempo ISO 8601, identificadores UUID
Errores	RFC 9457 `application/problem+json`

Esta página cubre lo esencial. Genera un cliente o explora los esquemas individuales en el documento OpenAPI; el servidor MCP se basa en la misma API.

Autenticación

Crea una clave en Configuración → Claves de API (solo propietarios y administradores) y envíala como token Bearer. Cada clave pertenece a una organización y tiene ámbitos explícitos: repos:read, repos:write, audits:read, audits:write, findings:read, findings:write y reports:read.

Comprueba tu clave

$ curl https://api.vetkit.dev/v1/me \  -H "Authorization: Bearer $VETKIT_API_KEY"

La respuesta indica los ámbitos de la clave y, en organizations, la organización a la que pertenece: usa ese id como ORG_ID en los pasos siguientes.

Mantén las claves fuera del control de versiones

Guarda las claves en el almacén de secretos de tu proveedor de CI, nunca en el código. El secreto se muestra una sola vez y solo se almacena como hash; si se filtra, revócalo en la app: la revocación es inmediata.

Una auditoría paso a paso

1. Inicia una auditoría

Pasa el id de un repositorio conectado y, opcionalmente, una rama, una etiqueta o el SHA de un commit. Sin ref, se audita la rama predeterminada. La API responde con 202 Accepted y la auditoría en cola. Si ya hay una auditoría en curso para el mismo commit, recibes esa en lugar de un duplicado.

Crear una auditoría

$ curl -X POST https://api.vetkit.dev/v1/orgs/$ORG_ID/audits \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -H "Content-Type: application/json" \  -d "{\"repositoryId\": \"$REPO_ID\", \"ref\": \"main\"}"

202 Accepted

{  "id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",  "status": "QUEUED",  "ref": "main",  "commitSha": "9f3c2e1b7a0d4c55e2f8a61b3d9c07e4a5b6f812",  "repository": { "fullName": "acme/payments-api", "htmlUrl": "https://github.com/acme/payments-api" },  "steps": [],  "summary": null}

2. Consulta el estado hasta que termine

Consulta el estado cada pocos segundos hasta que status sea SUCCEEDED, FAILED o CANCELLED. Una auditoría terminada incluye summary.grade, summary.overallScore y los recuentos por severidad.

Consultar el estado con curl y jq

$ while :; do$   STATUS=$(curl -s https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID \    -H "Authorization: Bearer $VETKIT_API_KEY" | jq -r .status)$   echo "$STATUS"$   case "$STATUS" in SUCCEEDED|FAILED|CANCELLED) break ;; esac$   sleep 3$ done

3. Descarga el informe

Elige format=json para el resumen legible por máquina, markdown para un informe legible o sarif para SARIF 2.1.0.

Descargar SARIF

$ curl "https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID/report?format=sarif" \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -o vetkit.sarif

Sube el archivo con la acción github/codeql-action/upload-sarif de GitHub para ver los hallazgos en las alertas de code scanning de tu repositorio.

Endpoints principales

Las rutas son relativas a https://api.vetkit.dev/v1. Consulta el documento OpenAPI para ver los parámetros y los esquemas de respuesta.

Método	Ruta	Descripción	Ámbito
GET	/me	Identifica la clave y su organización	cualquiera
GET	/orgs/{orgId}/repos	Lista los repositorios conectados	repos:read
POST	/orgs/{orgId}/repos	Conecta un repositorio por URL	repos:write
POST	/orgs/{orgId}/audits	Inicia una auditoría (202 Accepted)	audits:write
GET	/orgs/{orgId}/audits	Lista auditorías, con filtro por repositorio o estado	audits:read
GET	/orgs/{orgId}/audits/{auditId}	Estado, pasos y resumen de la auditoría	audits:read
POST	/orgs/{orgId}/audits/{auditId}/cancel	Cancela una auditoría en cola o en curso	audits:write
DELETE	/orgs/{orgId}/audits/{auditId}	Elimina de forma permanente una auditoría finalizada y su informe	audits:write
GET	/orgs/{orgId}/audits/{auditId}/findings	Hallazgos, con filtros y paginación	findings:read
GET	/orgs/{orgId}/audits/{auditId}/report	Informe en json, markdown o sarif	reports:read

Al conectar un repositorio cuyo propietario no ha instalado la GitHub App, se devuelve 409 INSTALLATION_REQUIRED con un installUrl en details.

Paginación

Los endpoints de listado usan paginación por cursor. Pasa limit (1–100, valor predeterminado 25) y, para la página siguiente, el nextCursor de la respuesta anterior como cursor. Un nextCursor con valor null significa que has llegado al final.

Estructura de una página

{ "items": [ … ], "nextCursor": "eyJpZCI6…" }

Errores

Los errores usan application/problem+json con un code estable y legible por máquina. Incluye el requestId cuando te pongas en contacto con soporte.

403 Forbidden

{  "type": "https://vetkit.dev/problems/insufficient-scope",  "title": "Forbidden",  "status": 403,  "detail": "This API key is missing the audits:write scope.",  "code": "INSUFFICIENT_SCOPE",  "requestId": "req_01J9Z3K8V4M2"}

Códigos habituales: API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED, INSUFFICIENT_SCOPE, VALIDATION_FAILED, NOT_FOUND, INSTALLATION_REQUIRED, AUDIT_CONCURRENCY_LIMIT y RATE_LIMITED.

Límites de solicitudes

Por clave: 60 solicitudes por minuto de forma predeterminada, configurable hasta 600 al crear la clave.
Auditorías simultáneas: hasta 3 auditorías en cola o en curso por organización; si se supera, se devuelve 409 AUDIT_CONCURRENCY_LIMIT.
Inicios de auditoría: 30 por hora por organización.

Si superas un límite de solicitudes, se devuelve 429 RATE_LIMITED con un encabezado Retry-After: espera ese número de segundos antes de volver a intentarlo. Los límites pueden cambiar durante la beta; la sección de precios indica los valores actuales.