Public REST API

The Vault exposes a public REST API on localhost:7437 for the CLI, the Beacon dashboard and external tooling. This page documents only the public endpoints — admin and team endpoints are intentionally not advertised.

Updated: 2026-04-30

The Vault exposes a public REST API on localhost:7437 for the CLI, the Beacon dashboard and external tooling.

This page documents only the public endpoints. Admin endpoints (/admin/*) accept either X-Admin-Key (the vault owner’s key) or X-Session-Token belonging to a team member with role=admin; team endpoints (/team/*) require X-Session-Token and are documented in Teams admin.

Conventions

Base URL: http://localhost:7437
Content type: application/json for both requests and responses
CORS: KORVA_CORS_ORIGIN (defaults to http://localhost:5173 for the Beacon dev server)
Rate limit: 120 requests / minute / IP (fixed window)
Time format: RFC 3339 throughout (2026-04-30T12:00:00Z)
IDs: ULID (26-char Crockford base32)

Health & status

Method	Path	Purpose
GET	`/healthz`	Liveness probe — `{"status":"ok"}`
GET	`/api/v1/status`	Server status — version, uptime, license tier, totals
GET	`/api/v1/metrics`	Prometheus-format metrics

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

Observations

Method	Path	Purpose
GET	`/api/v1/observations/{id}`	Fetch one observation by ULID
POST	`/api/v1/observations`	Save an observation (privacy filter + dedup applied)
GET	`/api/v1/search?q=&cloud=&project=&type=&limit=`	Full-text search (set `cloud=1` for hybrid local + Hive)
GET	`/api/v1/context/{project}`	Recent observations for a project
GET	`/api/v1/timeline/{project}?from=&to=`	Date-range query
GET	`/api/v1/summary/{project}`	High-level project summary
GET	`/api/v1/stats`	Global statistics

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 in payments","content":"Distributed Redis lock on payment_id.","type":"incident","project":"payments"}'

Sessions

Method	Path	Purpose
POST	`/api/v1/sessions`	Start a session, returns `id`
PUT	`/api/v1/sessions/{id}`	End a session with a summary
GET	`/api/v1/sessions/all`	List all sessions

Prompts

Method	Path	Purpose
POST	`/api/v1/prompts`	Save a reusable prompt template

OpenSpec & SDD (read-only)

Method	Path	Purpose
GET	`/api/v1/openspec/{project}`	Project-level conventions
GET	`/api/v1/sdd/{project}`	Current SDD phase

Hive worker (read-only)

Method	Path	Purpose
GET	`/api/v1/hive/status`	Worker state — `idle / pushing / backoff / healthy / disabled`

Authentication boundary endpoints

These are public but expect specific headers in subsequent requests:

Method	Path	Purpose
POST	`/auth/redeem`	Redeem an invite token, returns a `session_token`
GET	`/auth/me`	Identity of the current session (requires `X-Session-Token`)
DELETE	`/auth/session`	Logout (requires `X-Session-Token`)

URL prefix stripping

When the Beacon SPA proxies requests during development, it sends them under /vault-api/*. The Vault strips that prefix internally so the same handler chain serves both /api/v1/* and /vault-api/api/v1/*.

OpenAPI specification

The full machine-readable specification is published at /openapi.json (OpenAPI 3.1). Run it through any OpenAPI viewer (Stoplight, Redoc, Swagger UI) to explore schemas, examples, and types.

MCP tools — the AI-facing protocol that wraps these same operations
Self-hosting — running the Vault behind nginx / Traefik