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

# POST /v1/chat/completions

> OpenAI-compatible chat completion endpoint — the core gateway API for sending messages to any supported model.

## Endpoint

```
POST /v1/chat/completions
```

This is the primary gateway endpoint. It accepts an OpenAI-compatible request body, authenticates the caller, enforces your policy, routes to the configured provider, and returns either a complete response or a Server-Sent Events stream.

***

## Authentication

Include an `Authorization` header with every request. Three schemes are supported:

| Header value            | When to use                                                           |
| ----------------------- | --------------------------------------------------------------------- |
| `GatelitSigned <token>` | Backend-issued HMAC signed token (recommended for client-facing apps) |
| `Bearer <token>`        | OIDC token from Clerk, Supabase, or Auth0                             |
| `GatelitKey <key>`      | Long-lived service key (backend-to-backend)                           |

***

## Request

**Content-Type:** `application/json`

### Body fields

<ParamField body="model" type="string" required>
  The model to use, in `"provider/model-name"` format.

  ```
  "openai/gpt-4o"
  "anthropic/claude-3-5-sonnet-20241022"
  "google/gemini-1.5-pro"
  "mistral/mistral-large-latest"
  ```
</ParamField>

<ParamField body="messages" type="array" required>
  Conversation history as an array of message objects. Each object must have:

  <Expandable title="Message object">
    <ParamField body="role" type="&#x22;system&#x22; | &#x22;user&#x22; | &#x22;assistant&#x22;" required>
      The author of the message.
    </ParamField>

    <ParamField body="content" type="string" required>
      The message text.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  When `true`, the response is delivered as a Server-Sent Events stream. Each event carries an incremental delta. See [Streaming response](#streaming-response) below.
</ParamField>

<ParamField body="max_tokens" type="number">
  Maximum number of tokens to generate in the response.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature between `0` and `2`. Lower values produce more deterministic output.
</ParamField>

<ParamField body="x-gatelit-output-schema" type="object">
  Structured output configuration. When set, the gateway instructs the model to return valid JSON matching the specified shape.

  <Expandable title="JSON object mode">
    ```json theme={null}
    { "mode": "json_object" }
    ```

    The model must return valid JSON of any shape.
  </Expandable>

  <Expandable title="JSON schema mode">
    ```json theme={null}
    {
      "mode": "json_schema",
      "type": "object",
      "properties": {
        "score": { "type": "number" },
        "reason": { "type": "string" }
      },
      "required": ["score", "reason"]
    }
    ```

    The model's output is constrained to the provided JSON Schema.
  </Expandable>
</ParamField>

<ParamField body="x-gatelit-prompt-id" type="string">
  UUID of a saved prompt in your Gatelit dashboard. Links this ad-hoc request to the prompt for log correlation. The prompt's configuration is **not** applied — use [`POST /v1/prompts/:id/run`](/api/run-prompt) to execute a saved prompt.
</ParamField>

<ParamField body="x-gatelit-fallback-chain" type="array">
  An ordered list of fallback models to try if the primary model fails. Each entry:

  <Expandable title="FallbackModelEntry">
    <ParamField body="model" type="string" required>
      Fallback model in `"provider/model-name"` format.
    </ParamField>

    <ParamField body="triggers" type="string[]">
      Error conditions that activate this fallback. If omitted, the fallback is tried on any failure.

      Supported values: `"rate_limit"`, `"provider_error"`, `"timeout"`, `"context_limit"`.
    </ParamField>
  </Expandable>

  ```json theme={null}
  "x-gatelit-fallback-chain": [
    { "model": "anthropic/claude-3-5-sonnet-20241022", "triggers": ["rate_limit", "provider_error"] },
    { "model": "google/gemini-1.5-pro" }
  ]
  ```
</ParamField>

***

## Response headers

These headers are present on every successful response (streaming and non-streaming):

<ResponseField name="x-gatelit-request-id" type="string">
  A unique ID for this gateway request. Use it to look up the request in the Gatelit dashboard logs.
</ResponseField>

<ResponseField name="x-gatelit-model" type="string">
  The model that actually handled the request in `"provider/model-name"` format. May differ from the requested model if a fallback was triggered.
</ResponseField>

<ResponseField name="x-gatelit-auth-mode" type="string">
  The authentication mode used: `"signed-token"`, `"oidc"`, or `"service-key"`.
</ResponseField>

***

## Non-streaming response

When `stream` is `false` (the default), the gateway returns a standard OpenAI-compatible chat completion object.

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o-2024-08-06",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 9,
    "total_tokens": 23
  }
}
```

***

## Streaming response

When `stream` is `true`, the gateway returns an SSE stream (`Content-Type: text/event-stream`). Each line is prefixed with `data: ` and contains a JSON delta chunk:

```
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","model":"gpt-4o-2024-08-06","choices":[{"index":0,"delta":{"content":"The"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","model":"gpt-4o-2024-08-06","choices":[{"index":0,"delta":{"content":" capital"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","model":"gpt-4o-2024-08-06","choices":[{"index":0,"delta":{"content":""},"finish_reason":"stop"}],"usage":{"prompt_tokens":14,"completion_tokens":9,"total_tokens":23}}

data: [DONE]
```

* Each chunk carries incremental text in `choices[0].delta.content`.
* Token usage appears in the **last chunk before `[DONE]`**.
* The stream ends with a bare `data: [DONE]` line.

***

## Examples

<CodeGroup>
  ```bash Non-streaming theme={null}
  curl https://gateway.yourapp.com/v1/chat/completions \
    -H "Authorization: GatelitSigned <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o",
      "messages": [
        { "role": "system", "content": "You are a helpful assistant." },
        { "role": "user", "content": "What is the capital of France?" }
      ]
    }'
  ```

  ```bash Streaming theme={null}
  curl https://gateway.yourapp.com/v1/chat/completions \
    -H "Authorization: GatelitSigned <token>" \
    -H "Content-Type: application/json" \
    --no-buffer \
    -d '{
      "model": "openai/gpt-4o",
      "messages": [
        { "role": "user", "content": "Count to 5." }
      ],
      "stream": true
    }'
  ```

  ```bash With fallback chain theme={null}
  curl https://gateway.yourapp.com/v1/chat/completions \
    -H "Authorization: GatelitSigned <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o",
      "messages": [
        { "role": "user", "content": "Summarise this document." }
      ],
      "x-gatelit-fallback-chain": [
        {
          "model": "anthropic/claude-3-5-sonnet-20241022",
          "triggers": ["rate_limit", "provider_error"]
        }
      ]
    }'
  ```

  ```bash Structured output theme={null}
  curl https://gateway.yourapp.com/v1/chat/completions \
    -H "Authorization: GatelitSigned <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o",
      "messages": [
        { "role": "user", "content": "Rate the following review on a scale of 1–10 and give a reason." }
      ],
      "x-gatelit-output-schema": {
        "mode": "json_schema",
        "type": "object",
        "properties": {
          "score": { "type": "number" },
          "reason": { "type": "string" }
        },
        "required": ["score", "reason"]
      }
    }'
  ```
</CodeGroup>

***

## Error responses

All errors return JSON with `code`, `message`, and `requestId`. See the [Errors reference](/api/errors) for the full list of codes and HTTP statuses.