Docs · API reference

API reference.

RelayOne exposes a stable REST surface plus a high-throughput RPC channel for fleet operators. All endpoints sit behind RelayOne identity. Authentication is via API key (Bearer) or workspace-scoped service account JWT.

Base URL

  • Gateway hot-path: https://gateway.relayone.ai/v1/<workspace>
  • Control plane: https://api.relayone.ai/v1

Authentication

Every request requires Authorization: Bearer <token>. Token types:

  • ro_live_* — long-lived API key bound to a workspace and scope
  • ro_session_* — short-lived dashboard session token
  • Workspace JWT — for service-account-style integration; signed by your Clerk frontend

Gateway endpoints

The gateway is API-compatible with OpenAI, Anthropic, and AWS Bedrock. Drop-in replacement for the upstream base URL.

  • POST /v1/{workspace}/chat/completions — OpenAI-shaped chat
  • POST /v1/{workspace}/messages — Anthropic-shaped messages
  • POST /v1/{workspace}/embeddings — embeddings
  • POST /v1/{workspace}/completions — legacy completions

Every response carries an X-RelayOne-Receipt-Id header pointing at the signed receipt for the call.

Policies

  • GET /policies — list active policies in the workspace
  • POST /policies — create a policy (YAML body)
  • PUT /policies/{id} — update a policy; new version published atomically
  • POST /policies/{id}/dryrun — evaluate against an example payload without enforcing
  • DELETE /policies/{id} — soft-delete; receipts referencing the policy remain

Audit and evidence

  • GET /audit/events — paginated audit feed; filter by user, model, policy, time range
  • GET /audit/events/{id} — full event with signed receipt
  • POST /evidence/bundles — assemble a bundle for a time range and component selection
  • GET /evidence/bundles/{id} — download the assembled bundle (tar.gz with manifest)
  • GET /evidence/bundles/{id}/verify — server-side verifier; offline verifier available as a binary

Fleet

  • GET /fleet/instances — list gateway instances and their posture
  • POST /fleet/deployments — rolling deployment of a policy version across selected tenants
  • POST /fleet/credentials/rotate — rotate a named credential; emits chain-of-custody event
  • GET /fleet/health — per-tenant health and evidence-emission rate

Errors

Standard HTTP semantics. Error bodies are JSON: { "error": { "code": "policy.blocked", "message": "...", "receipt_id": "..." } }. Block decisions return 451 Unavailable For Legal Reasons when caused by sovereignty policy; 403 Forbidden for scope; 429 Too Many Requests for rate or budget caps.

Rate limits

Hot-path gateway calls are governed by your workspace tier. Control-plane API calls are limited to 60/sec/workspace by default; raise via Enterprise contract. Rate-limit responses include Retry-After.

Versioning

The v1 surface is stable. Breaking changes are introduced under /v2. Deprecations announced 12 months in advance via the changelog.

SDKs and clients

No RelayOne SDK is required — the gateway is wire-compatible with the upstream provider's client. We publish helper libraries for Go, Python, and TypeScript that wrap the control-plane API. See the RelayOne GitHub org for releases.