> ## Documentation Index
> Fetch the complete documentation index at: https://oximy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP endpoint reference

> Call Relay directly over HTTP for gateway execution, route-only decisions, and OTLP ingestion.

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

## Authentication

```http theme={null}
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

```http theme={null}
POST https://relay.oximy.com/v1/chat/completions
Content-Type: application/json
Authorization: Bearer ox_...
```

```json theme={null}
{
  "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.

```bash theme={null}
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:

```text theme={null}
https://relay.oximy.com/v1/traces
```

Use the same bearer-authentication pattern. See
[Observe with OpenTelemetry](/docs/relay/observe-otel) 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.

<CardGroup cols={2}>
  <Card title="Gateway behavior" icon="server" href="/docs/relay/gateway">
    Understand automatic and explicit model execution through Relay.
  </Card>

  <Card title="Route-only behavior" icon="signpost" href="/docs/relay/route-only">
    Keep provider execution, retries, credentials, and fallback in your
    infrastructure.
  </Card>
</CardGroup>