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 Ajustes del espacio de trabajo → 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, audits:run, findings:read, findings:write, findings:ai-fix, reports:read y agent:check.
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
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. Envía "mode": "FULL" para un análisis completo, que usa 1 crédito del propietario del espacio de trabajo y es obligatorio para una ref distinta de la rama predeterminada. Sin él, la API ejecuta un Quick Scan gratuito (posture, gitleaks y osv sobre el último commit de la rama predeterminada) mientras dure la asignación mensual del propietario. Un análisis completo sin créditos suficientes devuelve 402 INSUFFICIENT_CREDITS.
analyzers elige las comprobaciones que se ejecutan, de la suite Seguridad (posture, gitleaks, secrets-history, osv, vendored, eol, supply-chain, sast, sast-community, bandit, gosec, rust-audit, iac, base-images, workflows), la suite Calidad del código (code-smells, complexity, duplication, tests, docs, accessibility, performance, hygiene), la suite Sostenibilidad (licenses, dep-health, activity), la suite Riesgos de IA en el código (hallucinated-deps, ai-slop, vibe-stack, llm-app, ai-signal) y la suite Preparación para producción (resilience, data-access, operability, openapi, web-assets). Las suites opcionales y sin puntuación Privacidad y protección de datos (beta) (privacy-exposure, privacy-flows, privacy-lifecycle) e Historial de Git (git-history) se eligen del mismo modo. Si lo omites, se ejecutan las comprobaciones predeterminadas del repositorio. GET /orgs/$ORG_ID/analyzers lista todas las comprobaciones e indica si están disponibles en el servidor; si pides una que no lo está, se devuelve 422 ANALYZER_UNAVAILABLE.
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\", \"analyzers\": [\"gitleaks\", \"osv\", \"sast\"]}"{ "id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd", "status": "QUEUED", "ref": "main", "commitSha": "9f3c2e1b7a0d4c55e2f8a61b3d9c07e4a5b6f812", "repository": { "fullName": "acme/payments-api", "htmlUrl": "https://github.com/acme/payments-api" }, "analyzers": ["gitleaks", "osv", "sast"], "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 finalizada incluye summary.grade, summary.overallScore, summary.suiteScores (calificación y puntuación de cada suite ejecutada) y los recuentos por severidad.
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 3done3. Descarga el informe
Elige format=json para el resumen legible por máquina, markdown para un informe legible, sarif para SARIF 2.1.0 o pdf para un informe listo para imprimir (define locale como en, de, es, fr, it, pt, ru o tr para elegir su idioma).
curl "https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID/report?format=sarif" \ -H "Authorization: Bearer $VETKIT_API_KEY" \ -o vetkit.sarifSube 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 |
| GET | /orgs/{orgId}/analyzers | Comprobaciones por suite, con su disponibilidad y los valores predeterminados | audits:read |
| 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, filtrables por severidad, suite, categoría y más; con paginación | findings:read |
| GET | /orgs/{orgId}/audits/{auditId}/report | Informe en json, markdown, sarif o pdf | 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.
{ "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.
{ "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, INSUFFICIENT_CREDITS 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.