POST /v1/chat/completions

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

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"

array

required

Conversation history as an array of message objects. Each object must have:

Show Message object

"system" | "user" | "assistant"

required

The author of the message.

string

required

The message text.

boolean

default:"false"

When true, the response is delivered as a Server-Sent Events stream. Each event carries an incremental delta. See Streaming response below.

number

Maximum number of tokens to generate in the response.

number

Sampling temperature between 0 and 2. Lower values produce more deterministic output.

object

Structured output configuration. When set, the gateway instructs the model to return valid JSON matching the specified shape.

Show JSON object mode

{ "mode": "json_object" }

The model must return valid JSON of any shape.

Show JSON schema mode

{
  "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.

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 to execute a saved prompt.

array

An ordered list of fallback models to try if the primary model fails. Each entry:

Show FallbackModelEntry

string

required

Fallback model in "provider/model-name" format.

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".

"x-gatelit-fallback-chain": [
  { "model": "anthropic/claude-3-5-sonnet-20241022", "triggers": ["rate_limit", "provider_error"] },
  { "model": "google/gemini-1.5-pro" }
]

Response headers

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

string

A unique ID for this gateway request. Use it to look up the request in the Gatelit dashboard logs.

string

The model that actually handled the request in "provider/model-name" format. May differ from the requested model if a fallback was triggered.

string

The authentication mode used: "signed-token", "oidc", or "service-key".

Non-streaming response

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

{
  "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

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?" }
    ]
  }'

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
  }'

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"]
      }
    ]
  }'

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"]
    }
  }'

Error responses

All errors return JSON with code, message, and requestId. See the Errors reference for the full list of codes and HTTP statuses.

JavaScript SDK

Vue SDK

Gateway API

POST /v1/chat/completions

Endpoint

Authentication

Request

Body fields

Response headers

Non-streaming response

Streaming response

Examples

Error responses

​Endpoint

​Authentication

​Request

​Body fields

​Response headers

​Non-streaming response

​Streaming response

​Examples

​Error responses

Endpoint

Authentication

Request

Body fields

Response headers

Non-streaming response

Streaming response

Examples

Error responses