Control API

The control plane listens on RELAY_CONTROL_PORT (default 8081), separate from the inference port. It serves the control API under /api and the admin UI on the same origin.

API routes are mounted under /api (for example GET /api/providers) so they do not shadow the admin UI’s own routes (/models, /policies, …): a hard reload of /models returns the UI, not JSON. Any path not claimed by the API falls through to the UI, except under /api, where an unknown path answers a JSON 404. Set RELAY_UI_DISABLE=1 to serve the API without the UI.

A few paths sit at the listener root instead:

Path	Purpose
`/config.json`	Runtime configuration the admin UI reads before it knows the `/api` prefix.
`/metrics`	Prometheus metrics, unauthenticated. See Metrics.
`/auth/callback`	OIDC redirect URI. See SSO.
`/scim/v2`	SCIM 2.0 endpoint for identity providers. See SCIM.

The generated OpenAPI document at GET /api/openapi.json is the complete, typed list of operations, with request and response schemas; GET /api/docs renders it. This page groups the routes and links the page that explains each area.

Authentication

Caller	Mechanism
Browser (admin UI)	`relay_session` cookie, set by `POST /api/auth/login` or the OIDC sign-in
Operator, CI, scripts	`Authorization: Bearer $RELAY_ADMIN_TOKEN`

curl -H "Authorization: Bearer $RELAY_ADMIN_TOKEN" http://localhost:8081/api/providers

Public, with no credentials: GET /api/version, GET /api/healthz, GET /api/livez, POST /api/auth/login, the OIDC sign-in routes, GET /api/schemas/* and /config.json. Every other route requires a session or the admin token and is authorized per action; under RELAY_AUTHZ=rbac the caller’s role bindings decide. See Authentication. Control-plane actions are recorded in the audit log, which describes what is recorded.

Resource CRUD

Every kind shares one shape:

GET    /api/{plural}                 list
GET    /api/{plural}/{ref}           read by slug or id (a UUID is tried as an id first)
POST   /api/{plural}                 create; the server assigns id and slug
PUT    /api/{plural}/by-id/{id}      replace
DELETE /api/{plural}/by-id/{id}      delete

Plural	Kind	Concept
`providers`, `hosts`, `models`, `host-bindings`, `pricings`	Catalog	Catalog
`host-keys`	Upstream credentials	Authentication, Key pooling
`policies`	Grants, key pool, limits	Policies
`rate-limits`	Rule sets	Rate limits
`keys`	Relay keys (create through `POST /api/keys`)	Authentication
`teams`, `projects`, `service-accounts`, `groups`	Tenancy	Authentication
`roles`, `role-bindings`, `policy-bindings`	Access control	Authentication

List endpoints accept q (free text), sort, limit, offset, label=key=value (repeatable), and per-kind field filters; an unknown filter answers 400. The OpenAPI document lists each kind’s filters. Every read returns metadata.resourceVersion, an opaque string that changes on every write to the row. Send it back unchanged in the PUT body to make the update conditional: if the row changed since you read it, the PUT fails with 409 and the code stale_resource_version, and nothing is written. A PUT without resourceVersion replaces the row unconditionally. Every write is applied to each pod’s in-memory catalog within about a second; no reload is needed. Edits and deletes of catalog-owned rows are governed by the governance:* settings; see Settings.

References and detach

GET  /api/{plural}/by-id/{id}/references   rows that reference this one, before a delete
POST /api/{plural}/by-id/{id}/detach       clear every reference to this row the caller may edit; returns what still references it

Available for providers, hosts, models, pricings, policies, host-keys, rate-limits, teams, projects, service-accounts, groups and roles. Detach deletes nothing.

Host keys

POST /api/host-keys/by-id/{id}/rotate   {"value": "<new value>"}: replace a stored or oauth value
GET  /api/host-keys/by-id/{id}/health   the key's circuit-breaker state

A PUT cannot change a host key’s value; rotation is explicit. An env-referenced key is rotated by changing the variable, and the rotate call answers 400. See Key pooling for breaker states and Stored secrets for how stored values are sealed.

Relay keys

POST /api/keys                         create; the plaintext is returned once
POST /api/keys/by-id/{id}/rotate       new plaintext; optional {"graceSeconds": N} keeps the old one valid that long

curl -X POST http://localhost:8081/api/keys \
  -H "Authorization: Bearer $RELAY_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "displayName": "prod key" },
    "spec": {
      "principal": { "kind": "serviceaccount", "id": "<service-account-id>" },
      "policyId": "<policy-id>",
      "expiresAt": "2027-01-01T00:00:00Z"
    }
  }'

{
  "plaintext": "sk-wr-…",
  "key": { "metadata": { "id": "…" }, "spec": { "prefix": "sk-wr-…", "...": "..." } }
}

spec.principal is required. Optional fields: policyId, expiresAt, enabled, passthroughAllowed (proxy mode) and payloadLoggingEnabled. Relay stores only a hash of the plaintext; save it on receipt, it cannot be read again. A PUT never changes the key’s value, hash or principal.

Policies

POST   /api/policies/by-id/{id}/keys/{keyId}   attach a relay key to the policy
DELETE /api/policies/by-id/{id}/keys/{keyId}   detach it (409 if the key points at another policy)

Model overlays

GET    /api/models/by-id/{id}/overlay   the overlay, the catalog template and the effective spec
PUT    /api/models/by-id/{id}/overlay   set the overlay
DELETE /api/models/by-id/{id}/overlay   remove it, back to the catalog template

See Overlays.

Catalog views

Read-only projections for building UIs and checking a configuration:

GET /api/models/{ref}/hosts          hosts serving the model, with binding and pricing
GET /api/models/{ref}/pricing        the model's pricing per host
GET /api/models/{ref}/policies       policies granting the model, with the limits each applies
GET /api/hosts/{ref}/models          models the host serves, with binding and pricing
GET /api/hosts/{ref}/keys            the host's keys, without values
GET /api/hosts/{ref}/policies        the host's tier policies, with limits
GET /api/policies/{ref}/models       models the policy grants, with the limits it applies
GET /api/policies/{ref}/hosts        hosts the policy can reach, with the keys that reach each
GET /api/policies/{ref}/rate-limits  rate limits the policy references
GET /api/catalog/resolve             expand model references into matching catalog rows
GET /api/catalog/graph               providers, hosts, models and bindings, minimal
GET /api/debug/snapshot              counts and joins of the in-memory catalog the inference plane reads

Compare /api/debug/snapshot with the list endpoints when a row does not seem to reach inference.

Settings

GET /api/settings                 every section with its current value
GET /api/settings/sections        section names, descriptions and schema names
GET /api/settings/{section}       one section
PUT /api/settings/{section}       replace one section

Sections with their own route: inference, parsing, proxy-mode, usage-logging, payload-logging, otlp-receiver, audit, catalog-source, auth:oidc, auth:scim, auth:tokens, governance:provider, governance:host, governance:model, governance:policy. license is listed by GET /api/settings but has no route of its own: it is written with PUT /api/license. A PUT replaces the whole section, except the auth:tokens signing-key references, which only rotation changes; changes apply without a restart. Writing usage-logging, payload-logging, audit, auth:oidc, auth:scim or auth:tokens takes an admin. See Settings for each section’s fields.

GitOps

POST /api/apply                       plan and, unless dryRun, write a manifest bundle
GET  /api/export                      render tenant-owned rows as a manifest bundle
GET  /api/schemas/{version}           JSON Schemas for manifests (public)
GET  /api/schemas/{version}/{kind}    one kind's schema (public)

See GitOps.

POST   /api/auth/login                     username and password → session cookie
POST   /api/auth/logout                    end the session
GET    /api/auth/whoami                    the authenticated caller
GET    /api/auth/oidc/start                start OIDC sign-in
GET    /api/auth/oidc/callback             OIDC callback (also served at /auth/callback)
POST   /api/auth/token                     mint an inference token for a project (session only)
DELETE /api/auth/token/{jti}               revoke one token
POST   /api/auth/token/revoke              revoke the presented token
POST   /api/auth/token/revoke-all          revoke every token the caller holds
POST   /api/auth/token/keys/rotate         rotate the token signing key
POST   /api/master-key/generate            return a candidate RELAY_MASTER_KEY; installs nothing

curl -X POST http://localhost:8081/api/auth/token \
  -H "Cookie: relay_session=<session from POST /api/auth/login>" \
  -H "Content-Type: application/json" \
  -d '{"project": "my-project", "ttl": "1h"}'

Who may revoke which token, and how revocation reaches inference, is on Authentication. Sign-in with an identity provider is on SSO.

Users, access review and audit

GET  /api/users                              list users (never a password hash)
PUT  /api/users/by-id/{id}                   edit disabled and roles
POST /api/users/by-id/{id}/revoke-tokens     revoke every inference token the user holds
POST /api/access-review                      explain whether a user or service account may perform an action
GET  /api/audit                              audit events, newest first; filter by actor_id, actor_name, action,
                                             resource_kind, resource_id, scope, status, from, to

User endpoints authorize at the global scope. Disabling a user signs them out on their next request, refuses their login with 401 account_disabled, and revokes their inference tokens; re-enabling does not bring the tokens back. The access review answers 501 under RELAY_AUTHZ=single. See Checking access and Audit log.

SCIM clients

GET  /api/scim-clients                  list clients (name, token prefix, created, last used, revoked)
POST /api/scim-clients                  {"name": "entra"} → the client and its token, returned once
POST /api/scim-clients/{name}/rotate    replace the client's token, returned once
POST /api/scim-clients/{name}/revoke    stop the token; users and groups it provisioned stay

See SCIM.

Secret keys

GET  /api/secret-keys                      data keys, target master key, master keys this pod holds, legacy rows left
POST /api/secret-keys/rotate               {"scope": "project:<id>"} or {"all": true} → the new data keys
POST /api/secret-keys/rewrap               {"to": "<kek id>"} → target, rewrapped count, skipped keys
POST /api/secret-keys/by-id/{id}/destroy   optional {"force": true} → the destroyed key

Admin only. No response carries key bytes. See Stored secrets and key rotation for the refusals each call can answer.

License

GET /api/license    the live license
PUT /api/license    install a license without a redeploy

See License.

Usage and request logs

GET  /api/usage/events          raw usage events, filterable
GET  /api/usage/summary         aggregates per group over a window
GET  /api/usage/timeseries      aggregates per time bucket
GET  /api/usage/facets          values per dimension, for filters
GET  /api/logs                  request log, newest first
GET  /api/logs/{request_id}     one request, with captured bodies
POST /api/logs/erase            delete captured bodies by project and/or principal (admin)

Filters, grouping and comparison are on Usage tracking; captured bodies and erasure on Payload logging.

Operations

GET  /api/version        build version (public; license details only for authenticated callers)
GET  /api/healthz        readiness: process and backends (public)
GET  /api/livez          liveness: process only (public)
POST /api/reload         rebuild the in-memory catalog from Postgres
GET  /api/openapi.json   OpenAPI document
GET  /api/docs           API reference UI

/api/reload is a fallback; normal writes reach every pod on their own.

Get Started

Build with Relay

How It Works

Deploy and Operate

Observability

Security and Access

Reference

Authentication

Resource CRUD

References and detach

Host keys

Relay keys

Policies

Model overlays

Catalog views

Settings

GitOps

Users, access review and audit

SCIM clients

Secret keys

License

Usage and request logs

Operations

​Authentication

​Resource CRUD

​References and detach

​Host keys

​Relay keys

​Policies

​Model overlays

​Catalog views

​Settings

​GitOps

​Sign-in, tokens and the master key

​Users, access review and audit

​SCIM clients

​Secret keys

​License

​Usage and request logs

​Operations

Authentication

Resource CRUD

References and detach

Host keys

Relay keys

Policies

Model overlays

Catalog views

Settings

GitOps

Sign-in, tokens and the master key

Users, access review and audit

SCIM clients

Secret keys

License

Usage and request logs

Operations