Reference
API reference
The control plane: organisations, keys, gateway configuration and traces over HTTP.
The control plane is a separate binary, rakuvo-api, backed by SQLite. Every route except /healthz needs a bearer token. Keys have a role, and each route says which roles may call it: see Keys and roles.
go build -o rakuvo-api ./cmd/rakuvo-apiexport RAKUVO_ADMIN_TOKEN=..../rakuvo-api -listen 127.0.0.1:8090 -db rakuvo.db -allow-origin https://your-dashboard.example#Routes
| Route | Purpose |
|---|---|
GET /healthz | Liveness. |
POST /v1/admin/orgs | Create an organisation (admin token). |
GET /v1/keys, POST /v1/keys, DELETE /v1/keys/{id} | List, create and revoke API keys. A key's secret is shown once. |
GET /v1/config, PUT /v1/config | Read or set the organisation's gateway settings. |
POST /v1/ingest/events | Trace ingestion from gateways, in batches. |
GET /v1/summary | Aggregated cost, tokens, latency and layer actions. |
GET /v1/runs, GET /v1/runs/{id} | Individual runs with their layer notes. |
GET /v1/series | Calls, failures, tokens and cost per time bucket, for charts. Takes since and bucket. |
POST /v1/ingest/memory, GET /v1/memory/graph | Send and read a user's memory facts. See Memory graph. |
GET, POST /v1/alerts/rules, PUT, DELETE /v1/alerts/rules/{id}, GET /v1/alerts | Alert rules and the times they fired. See Alerts. |
GET /v1/usage | Monthly usage and the bill estimate. See Usage and billing. |
PUT /v1/admin/orgs/{id}/plan | Set an organisation's plan (admin token). |
#Gateway configuration
PUT /v1/config takes the same settings as the CLI flags, validated on write:
curl -X PUT "$RAKUVO_API_URL/v1/config" \ -H "Authorization: Bearer $RAKUVO_KEY" \ -H "Content-Type: application/json" \ -d '{ "tool_policy_auto": true, "verify": { "model": "gpt-4o-mini", "mode": "veto", "scope": "single" }, "context": { "keep_observations": 6, "mask_step": 3 }, "loop": { "enabled": true }, "memory": { "enabled": true } }'tool_policy and tool_policy_auto are alternatives: set one. An invalid setting is rejected with a message that names the field.
#Config-pull
Start a gateway with -config-from-api. It polls GET /v1/config using the ETag, builds a new pipeline when the settings change, and swaps it in atomically. A failed poll keeps the last good configuration. Turning a layer on in the dashboard therefore takes effect within one poll interval.
#Traces
Gateways send traces to POST /v1/ingest/events in batches without blocking requests. GET /v1/summary aggregates them; GET /v1/runs/{id} returns every attempt of a run with the notes each layer wrote.