API REST pública

El Vault expone una API REST pública en localhost:7437 para la CLI, el dashboard Beacon y herramientas externas. Esta página documenta solo los endpoints públicos — los endpoints de admin y team intencionalmente no se publicitan.

Actualizado: 2026-04-30

El Vault expone una API REST pública en localhost:7437 para la CLI, el dashboard Beacon y herramientas externas.

Esta página documenta solo los endpoints públicos. Los endpoints de admin (/admin/*) aceptan o bien X-Admin-Key (la clave del propietario del vault) o X-Session-Token perteneciente a un miembro del equipo con role=admin; los endpoints de team (/team/*) requieren X-Session-Token y están documentados en Administración de Teams.

Convenciones

URL base: http://localhost:7437
Content type: application/json para peticiones y respuestas
CORS: KORVA_CORS_ORIGIN (por defecto http://localhost:5173 para el servidor de desarrollo de Beacon)
Rate limit: 120 peticiones / minuto / IP (ventana fija)
Formato de tiempo: RFC 3339 en todo (2026-04-30T12:00:00Z)
IDs: ULID (26 caracteres en Crockford base32)

Salud y estado

Método	Ruta	Propósito
GET	`/healthz`	Sonda de liveness — `{"status":"ok"}`
GET	`/api/v1/status`	Estado del servidor — versión, uptime, tier de licencia, totales
GET	`/api/v1/metrics`	Métricas en formato Prometheus

curl -s http://localhost:7437/healthz
# {"status":"ok"}

Observaciones

Método	Ruta	Propósito
GET	`/api/v1/observations/{id}`	Obtener una observación por ULID
POST	`/api/v1/observations`	Guardar una observación (filtro de privacidad + dedup aplicados)
GET	`/api/v1/search?q=&cloud=&project=&type=&limit=`	Búsqueda full-text (usa `cloud=1` para híbrido local + Hive)
GET	`/api/v1/context/{project}`	Observaciones recientes de un proyecto
GET	`/api/v1/timeline/{project}?from=&to=`	Consulta por rango de fechas
GET	`/api/v1/summary/{project}`	Resumen de alto nivel del proyecto
GET	`/api/v1/stats`	Estadísticas globales

curl -s "http://localhost:7437/api/v1/search?q=race%20condition&type=incident&limit=5"

curl -s -X POST http://localhost:7437/api/v1/observations \
  -H 'Content-Type: application/json' \
  -d '{"title":"Race en pagos","content":"Lock distribuido en Redis sobre payment_id.","type":"incident","project":"payments"}'

Sesiones

Método	Ruta	Propósito
POST	`/api/v1/sessions`	Iniciar una sesión, devuelve `id`
PUT	`/api/v1/sessions/{id}`	Cerrar una sesión con un resumen
GET	`/api/v1/sessions/all`	Listar todas las sesiones

Prompts

Método	Ruta	Propósito
POST	`/api/v1/prompts`	Guardar una plantilla de prompt reutilizable

OpenSpec y SDD (solo lectura)

Método	Ruta	Propósito
GET	`/api/v1/openspec/{project}`	Convenciones a nivel de proyecto
GET	`/api/v1/sdd/{project}`	Fase SDD actual

Worker de Hive (solo lectura)

Método	Ruta	Propósito
GET	`/api/v1/hive/status`	Estado del worker — `idle / pushing / backoff / healthy / disabled`

Endpoints en la frontera de autenticación

Estos son públicos pero esperan headers específicos en peticiones posteriores:

Método	Ruta	Propósito
POST	`/auth/redeem`	Canjear un token de invitación, devuelve un `session_token`
GET	`/auth/me`	Identidad de la sesión actual (requiere `X-Session-Token`)
DELETE	`/auth/session`	Logout (requiere `X-Session-Token`)

Stripping del prefijo de URL

Cuando la SPA de Beacon hace proxy de peticiones durante el desarrollo, las envía bajo /vault-api/*. El Vault elimina ese prefijo internamente para que la misma cadena de handlers sirva tanto /api/v1/* como /vault-api/api/v1/*.

Especificación OpenAPI

La especificación completa legible por máquinas se publica en /openapi.json (OpenAPI 3.1). Pásala por cualquier visor de OpenAPI (Stoplight, Redoc, Swagger UI) para explorar esquemas, ejemplos y tipos.

Herramientas MCP — el protocolo orientado a IA que envuelve estas mismas operaciones
Self-hosting — ejecutar el Vault tras nginx / Traefik