Skip to main content

REST API Reference

Cruvero exposes a Huma/OpenAPI 3.1 REST surface for runtime control, governance, and operations. The embedded reference below is generated from route registrations in internal/api/routes/*.

Authentication​

The API supports two auth strategies:

  • Bearer JWT (OIDC modes): send Authorization: Bearer <token>
  • API key (apikey mode): send X-API-Key: <key>

For tenant-scoped requests, set:

  • X-Cruvero-Tenant-Id: <tenant-id>

Common Behavior​

  • Content type: application/json (except stream endpoints)
  • Errors follow RFC 7807 problem details (application/problem+json)
  • Quota and rate limits are enforced per tenant via policy configuration

Example error payload:

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "unauthorized"
}

Quick Endpoint Map​

  • Runtime: /v1/runs*, /v1/supervisor*, /v1/graph*, /v1/memory, /v1/tools*
  • Governance: /v1/audit*, /v1/quota*, /v1/security/alerts, /v1/immune/*, /v1/provenance*, /v1/traces
  • Operations: /v1/admin/*, /v1/health*
  • Catalog/Config: /v1/models*, /v1/tenants*, /v1/agents*, /v1/agent-versions, /v1/capabilities

Spec Freshness​

OpenAPI artifacts are versioned in-repo:

Regenerate/update:

make site-openapi
site/scripts/openapi-sha.sh update

Download the raw spec: /api/openapi.json

Loading API reference...