ultrarouter docs

API reference

Provider keys

BYOK provider keys (write-only secrets).

BYOK provider keys (write-only secrets).

This page is GENERATED from the OpenAPI spec (openapi.yaml) — it can never drift from the served API. Set UR_BASE_URL (required: your gateway’s URL) and UR_API_KEY (an ur_sk_* key); secrets are always the $UR_API_KEY placeholder.

List provider keys

GET /v1/workspaces/{id}/provider-keys

Auth: Session cookie + workspace RBAC.

curl -sS -X GET "$UR_BASE_URL/v1/workspaces/req_0000000000000000/provider-keys" \
  -H "Cookie: better-auth.session_token=$UR_SESSION"

Register a BYOK provider key

POST /v1/workspaces/{id}/provider-keys

The secret is envelope-encrypted at rest; responses carry last-4 + health only.

Auth: Session cookie + workspace RBAC.

curl -sS -X POST "$UR_BASE_URL/v1/workspaces/req_0000000000000000/provider-keys" \
  -H "Cookie: better-auth.session_token=$UR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "string",
    "secret": "string"
  }'

Update a provider key

PATCH /v1/workspaces/{id}/provider-keys/{keyId}

Auth: Session cookie + workspace RBAC.

curl -sS -X PATCH "$UR_BASE_URL/v1/workspaces/req_0000000000000000/provider-keys/key_0000000000000000" \
  -H "Cookie: better-auth.session_token=$UR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "priority": 0
  }'

Delete a provider key

DELETE /v1/workspaces/{id}/provider-keys/{keyId}

Auth: Session cookie + workspace RBAC.

curl -sS -X DELETE "$UR_BASE_URL/v1/workspaces/req_0000000000000000/provider-keys/key_0000000000000000" \
  -H "Cookie: better-auth.session_token=$UR_SESSION"

Health-check a provider key

POST /v1/workspaces/{id}/provider-keys/{keyId}/health-check

Runs one cheap probe and returns the refreshed health status.

Auth: Session cookie + workspace RBAC.

curl -sS -X POST "$UR_BASE_URL/v1/workspaces/req_0000000000000000/provider-keys/key_0000000000000000/health-check" \
  -H "Cookie: better-auth.session_token=$UR_SESSION"

Preflight

Ask what the gateway would decide before a non-proxied call — model, fallbacks, learned knowledge, placement.

Workspaces

Workspace tenancy management.

On this page

List provider keys Register a BYOK provider key Update a provider key Delete a provider key Health-check a provider key