HTTP endpoint reference

Relay does not require an Oximy SDK. Use the endpoint shown for the project and authenticate with a project-scoped Relay key.

Authentication

Authorization: Bearer ox_...

The full Relay key is shown once when it is created. Store it in a secret manager and revoke it if it is exposed.

Execute a chat completion

POST https://relay.oximy.com/v1/chat/completions
Content-Type: application/json
Authorization: Bearer ox_...

{
  "model": "oximy/auto",
  "messages": [
    {
      "role": "user",
      "content": "Summarize the release risk."
    }
  ],
  "max_tokens": 800
}

Use oximy/auto for the project’s active routing policy or a provider-prefixed model ID for an explicit model. The response uses an OpenAI-compatible chat-completion envelope. Relay can also return:

Header	Meaning
`x-oximy-resolved-model`	Model that executed the request
`x-oximy-cost-usd`	Cost attributed to the completed request when available

For streaming, send "stream": true. Relay returns server-sent events when the selected provider and request path support streaming. Include "stream_options": {"include_usage": true} when usage in the stream is needed.

Request a routing decision

Use POST /v1/route when Relay should choose the model but your infrastructure should execute the provider request.

curl https://relay.oximy.com/v1/route \
  -H "Authorization: Bearer ox_..." \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Classify this support request."}
    ]
  }'

The response includes model and decision_id. Preserve the decision identifier in execution telemetry so Relay can correlate the recommendation with the outcome.

Send OpenTelemetry traces

Send OTLP/HTTP protobuf traces to:

https://relay.oximy.com/v1/traces

Use the same bearer-authentication pattern. See Observe with OpenTelemetry for exporter configuration.

Handle failures

Status	Check
`401`	Relay key is missing, invalid, expired, disabled, or revoked
`402`	Project or provider billing cannot cover the request
`429`	A project, key, provider, or plan rate limit has been reached
`5xx`	Relay or the selected provider could not complete the request

Preserve the HTTP status, sanitized error body, request or decision identifier, and UTC timestamp when investigating a failure.

Gateway behavior

Understand automatic and explicit model execution through Relay.

Route-only behavior

Keep provider execution, retries, credentials, and fallback in your infrastructure.

​Authentication

​Execute a chat completion

​Request a routing decision

​Send OpenTelemetry traces

​Handle failures