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.

bash
go build -o rakuvo-api ./cmd/rakuvo-api
export RAKUVO_ADMIN_TOKEN=...
./rakuvo-api -listen 127.0.0.1:8090 -db rakuvo.db -allow-origin https://your-dashboard.example

#Routes

RoutePurpose
GET /healthzLiveness.
POST /v1/admin/orgsCreate 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/configRead or set the organisation's gateway settings.
POST /v1/ingest/eventsTrace ingestion from gateways, in batches.
GET /v1/summaryAggregated cost, tokens, latency and layer actions.
GET /v1/runs, GET /v1/runs/{id}Individual runs with their layer notes.
GET /v1/seriesCalls, failures, tokens and cost per time bucket, for charts. Takes since and bucket.
POST /v1/ingest/memory, GET /v1/memory/graphSend and read a user's memory facts. See Memory graph.
GET, POST /v1/alerts/rules, PUT, DELETE /v1/alerts/rules/{id}, GET /v1/alertsAlert rules and the times they fired. See Alerts.
GET /v1/usageMonthly usage and the bill estimate. See Usage and billing.
PUT /v1/admin/orgs/{id}/planSet an organisation's plan (admin token).

#Gateway configuration

PUT /v1/config takes the same settings as the CLI flags, validated on write:

bash
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.