Saltar al contenido

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 basehttps://api.vetkit.dev/v1
OpenAPIhttps://api.vetkit.dev/v1/openapi.json — la referencia completa y legible por máquina de todas las rutas y esquemas
FormatoCuerpos de solicitud y respuesta en JSON, marcas de tiempo ISO 8601, identificadores UUID
ErroresRFC 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.

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. 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.

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\", \"analyzers\": [\"gitleaks\", \"osv\", \"sast\"]}"
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" },  "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.

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 3done

3. 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).

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étodoRutaDescripciónÁmbito
GET/meIdentifica la clave y su organizacióncualquiera
GET/orgs/{orgId}/reposLista los repositorios conectadosrepos:read
POST/orgs/{orgId}/reposConecta un repositorio por URLrepos:write
GET/orgs/{orgId}/analyzersComprobaciones por suite, con su disponibilidad y los valores predeterminadosaudits:read
POST/orgs/{orgId}/auditsInicia una auditoría (202 Accepted)audits:write
GET/orgs/{orgId}/auditsLista auditorías, con filtro por repositorio o estadoaudits:read
GET/orgs/{orgId}/audits/{auditId}Estado, pasos y resumen de la auditoríaaudits:read
POST/orgs/{orgId}/audits/{auditId}/cancelCancela una auditoría en cola o en cursoaudits:write
DELETE/orgs/{orgId}/audits/{auditId}Elimina de forma permanente una auditoría finalizada y su informeaudits:write
GET/orgs/{orgId}/audits/{auditId}/findingsHallazgos, filtrables por severidad, suite, categoría y más; con paginaciónfindings:read
GET/orgs/{orgId}/audits/{auditId}/reportInforme en json, markdown, sarif o pdfreports: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, 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.

Solicita acceso anticipado

Cuéntanos un poco sobre tu equipo y los repositorios que quieres auditar. Incorporamos equipos en pequeños grupos y te responderemos por correo electrónico.

Solo usamos estos datos para responder a tu solicitud. Política de privacidad