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

# Supported APIs

> API compatibility layers, agent harness support, and example requests for the LLM Gateway.

## Overview

The LLM Gateway exposes one gateway URL, `https://llm-gateway.aptible.com`, and speaks several API dialects from it. Pick whichever matches how you're already integrating:

* **OpenAI-compatible** — Chat Completions, Responses, and Embeddings, in both a strict `/openai` namespace and as un-namespaced defaults
* **Anthropic-compatible** — Messages, in a strict `/anthropic` namespace
* **Agent harnesses** — a dedicated, never-changing base URL per supported coding assistant or agent harness, under `/harness/<name>`

Every request authenticates with an [LLM Key](https://www.aptible.com/docs/llm-gateway/llm-keys.md) and selects a model by name in the request body — see [Supported Models](https://www.aptible.com/docs/llm-gateway/supported-models.md) for the current model catalog.

## Authentication

Send your LLM Key as a bearer token:

```text theme={null}
Authorization: Bearer <YOUR_LLM_KEY>
```

Anthropic's SDKs (and Claude Code) instead send an `x-api-key` header — the gateway accepts either:

```text theme={null}
x-api-key: <YOUR_LLM_KEY>
```

## OpenAI-compatible API

Use the `/openai` namespace for strict OpenAI compatibility:

| Endpoint | Path |
| - | - |
| Chat Completions | `POST /openai/v1/chat/completions` |
| Responses | `POST /openai/v1/responses` |
| Embeddings | `POST /openai/v1/embeddings` |

The same three endpoints are also available un-namespaced (`/v1/chat/completions`, `/v1/responses`, `/v1/embeddings`) as the gateway's default dialect — use whichever your SDK or tooling expects.

For full request and response documentation, see [OpenAI's API reference](https://developers.openai.com/api/reference/overview).

## Anthropic-compatible API

Use the `/anthropic` namespace for Anthropic Messages:

| Endpoint | Path |
| - | - |
| Messages | `POST /anthropic/v1/messages` |
| Count Tokens | `POST /anthropic/v1/messages/count_tokens` |

For full request and response documentation, see [Anthropic's API reference](https://platform.claude.com/docs/en/api/overview).

## Agent harness support

Some coding assistants and agent harnesses need a single base URL they can be pointed at once and never have to edit again — even as the underlying API dialect they speak evolves. The LLM Gateway provides one under `/harness/<name>`, which resolves internally to the right compatibility endpoint:

| Harness | Base URL |
| - | - |
| Claude Code | `https://llm-gateway.aptible.com/harness/claude-code` |
| Claude Desktop | `https://llm-gateway.aptible.com/harness/claude-desktop` |
| Grok Build | `https://llm-gateway.aptible.com/harness/grok-build` |
| Pi | `https://llm-gateway.aptible.com/harness/pi` |

See the [Claude Code guide](https://www.aptible.com/docs/getting-started/secure-llm-usage/claude-code.md) for a full walkthrough of harness setup.

> [!NOTE]
>
> Don't see your harness or coding assistant listed? Any tool that speaks OpenAI- or Anthropic-compatible APIs already works against the `/openai` or `/anthropic` endpoints above — a dedicated `/harness` route just saves you from ever having to change the base URL again. [Contact us](https://app.aptible.com/support) if you'd like a harness added.

## Example requests

Every example below uses the model field to select a model — see [Supported Models](https://www.aptible.com/docs/llm-gateway/supported-models.md) for valid IDs.

```bash Chat Completions theme={null}
curl https://llm-gateway.aptible.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $LLM_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [
      {"role": "user", "content": "Tell me a joke about cloud security"}
    ]
  }'
```

```bash Responses theme={null}
curl https://llm-gateway.aptible.com/openai/v1/responses \
  -H "Authorization: Bearer $LLM_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "input": "Tell me a joke about cloud security"
  }'
```

```bash Anthropic Messages theme={null}
curl https://llm-gateway.aptible.com/anthropic/v1/messages \
  -H "x-api-key: $LLM_GATEWAY_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Tell me a joke about cloud security"}
    ]
  }'
```

## Prompt caching

Prompt caching works through the LLM Gateway the same way it does with the provider directly: mark cacheable content with `cache_control` (Anthropic), or rely on the provider's automatic caching (OpenAI).

The gateway serves each model from a pool of upstream providers. A provider's cache only helps requests that reach that same provider, so to keep a conversation's cache warm, send a `session-id` (or `x-session-id`) header that stays the same for the whole conversation:

```text theme={null}
session-id: <CONVERSATION_ID>
```

Requests that share a session ID are routed to the same upstream for up to an hour after the last request. Use a new, unique value, such as a UUID, for each conversation or agent run. Without a session ID, requests are spread across upstreams and see more cache misses.

```python Anthropic SDK (Python) theme={null}
message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[{"type": "text", "text": LONG_SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}}],
    messages=messages,
    extra_headers={"session-id": conversation_id},
)
```

```python OpenAI SDK (Python) theme={null}
response = client.responses.create(
    model="gpt-5",
    input=messages,
    extra_headers={"session-id": conversation_id},
)
```

> [!NOTE]
>
> Claude Code, Codex CLI, OpenCode, and Pi already send their own session headers, which the gateway recognizes, so no configuration is needed for them.

A request that fails over to another provider during an outage starts with a cold cache on that provider.

## Automatic provider failover and client-side fallbacks

If a model is available from more than one provider, the gateway automatically fails over to another available provider during an outage — no client changes required. You can also specify your own fallback models in a request; see [Supported Models](https://www.aptible.com/docs/llm-gateway/supported-models.md#provider-failover) for details on both.