Gateway REST API

The Cavalry gateway exposes a small, stable HTTP API consumed by the CLI and by AI agents via MCP. All endpoints live under /v1/ and authenticate with a Bearer token.

Authentication

Authorization: Bearer cav_...

Tokens are created in the web UI under /[org]/settings/tokens. Each token is scoped (skills:read, skills:write, skills:install) and shown once at creation.

Errors

Errors use RFC 7807 problem+json:

{
  "type": "https://cavalry.sh/errors/policy-violation",
  "title": "policy_violation",
  "status": 403,
  "detail": "blocked by \"no-tessl\"",
  "policyId": "pol_...",
  "policyName": "no-tessl",
  "decision": "deny"
}

Endpoints

Private registry

• GET /v1/skills/:namespace/:name — metadata + version list
• GET /v1/skills/:namespace/:name/:version — manifest
• GET /v1/skills/:namespace/:name/:version/artifact — streams the gzipped tarball. Policy-enforced.
• POST /v1/skills/:namespace/:name/versions — multipart publish (manifest + artifact)

Proxy (upstream registries)

• GET /v1/proxy/:registry/:namespace/:name
• GET /v1/proxy/:registry/:namespace/:name/:version
• GET /v1/proxy/:registry/:namespace/:name/:version/artifact — Policy-enforced.

The gateway caches artifacts in content-addressed storage; subsequent requests return x-cavalry-cache: HIT.

Governance

• GET /v1/policies — read-only projection used by cavalry policy list
• POST /mcp — JSON-RPC 2.0 MCP endpoint (see MCP reference)

Health

• GET /healthz — liveness
• GET /readyz — DB connectivity + config
• GET /metrics — Prometheus format (request count, duration, cache hit ratio, policy decisions)

Install response headers