Chat Completions

curl https://gateway.yourapp.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: GatelitKey sk_live_your_service_key" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "What is the capital of France?"}]
  }'

{
  "id": "<string>",
  "object": "chat.completion",
  "created": 123,
  "model": "<string>",
  "choices": [
    {
      "index": 123,
      "message": {
        "role": "user",
        "content": "Explain quantum entanglement in one sentence."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123
  }
}

{
  "error": true,
  "code": "gateway_error",
  "message": "Missing or invalid 'model' field. Expected format: 'provider/model-name'"
}

{
  "error": true,
  "code": "unauthorized",
  "message": "Invalid or expired token"
}

{
  "error": true,
  "code": "provider_error",
  "message": "Upstream error 503 — Service Unavailable"
}

POST

chat

completions

curl https://gateway.yourapp.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: GatelitKey sk_live_your_service_key" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "What is the capital of France?"}]
  }'

{
  "id": "<string>",
  "object": "chat.completion",
  "created": 123,
  "model": "<string>",
  "choices": [
    {
      "index": 123,
      "message": {
        "role": "user",
        "content": "Explain quantum entanglement in one sentence."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123
  }
}

{
  "error": true,
  "code": "gateway_error",
  "message": "Missing or invalid 'model' field. Expected format: 'provider/model-name'"
}

{
  "error": true,
  "code": "unauthorized",
  "message": "Invalid or expired token"
}

{
  "error": true,
  "code": "provider_error",
  "message": "Upstream error 503 — Service Unavailable"
}

POST /v1/chat/completions Send a chat request to any supported provider through the gateway. The response format is identical to OpenAI’s chat completions API regardless of which provider handles the request.

Auth

All three schemes are accepted:

Authorization: GatelitKey sk_live_...
Authorization: GatelitSigned <signed-token>

Bearer (OIDC) is supported but in Alpha. Contact us if you need OIDC auth.

Request

Field	Type	Required	Description
`model`	`string`	Yes	Provider/model in `provider/model-id` format
`messages`	`array`	Yes	Array of `{role, content}` objects
`max_tokens`	`integer`	No	Max output tokens
`temperature`	`number`	No	0–2, stripped for reasoning models
`stream`	`boolean`	No	Enable SSE streaming

Gateway-specific fields

Field	Description
`x-gatelit-output-schema`	Structured output config (`json_object` or `json_schema` mode)
`x-gatelit-prompt-id`	Tag request with a saved prompt’s slug for log correlation
`x-gatelit-fallback-chain`	Ordered fallback models with trigger conditions

Response

Non-streaming

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "openai/gpt-4o",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 8,
    "total_tokens": 23
  }
}

Response headers

Header	Description
`x-gatelit-request-id`	Unique request ID for log lookup
`x-gatelit-model`	Resolved model in `provider/model` format
`x-gatelit-auth-mode`	`Bearer`, `GatelitSigned`, or `GatelitKey`
`x-gatelit-fallback`	`"true"` when a fallback model was used
`x-gatelit-fallback-reason`	`rate_limit`, `provider_error`, or `timeout`
`x-gatelit-fallback-model`	The fallback model that responded

Streaming

When stream: true, the response is an OpenAI-compatible SSE stream. Each data: line is a JSON chunk. Final line is data: [DONE].

Examples

curl https://gateway.gatelit.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: GatelitKey sk_live_..." \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

import { GatelitClient } from "@gatelit/sdk"

const client = new GatelitClient({
  gatewayUrl: "https://gateway.gatelit.dev",
  getToken: async () => ({ token: "sk_live_...", scheme: "GatelitKey" }),
})

const response = await client.chat({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
})

Structured output

curl https://gateway.gatelit.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: GatelitKey sk_live_..." \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Alice is 30."}],
    "x-gatelit-output-schema": {
      "mode": "json_schema",
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
      },
      "required": ["name", "age"]
    }
  }'

With fallback chain

curl https://gateway.gatelit.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: GatelitKey sk_live_..." \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Explain TCP"}],
    "x-gatelit-fallback-chain": [
      {"model": "anthropic/claude-3-5-haiku-20241022", "triggers": ["rate_limit"]},
      {"model": "google/gemini-2.5-flash"}
    ]
  }'

Errors

Status	Code	Meaning
400	`gateway_error`	Invalid model format or missing fields
401	`unauthorized`	Missing, invalid, or expired token
502	`provider_error`	Upstream provider returned an error

Authorizations

Authorization

string

header

required

OIDC JWT issued by your auth provider (Alpha). Full self-serve configuration is coming soon — contact us for early access. Use this for browser/frontend clients where a user is signed in.

Body

application/json

model

string

required

Model in provider/model-id format. Supported providers: openai, anthropic, google, mistral.

Examples:

"openai/gpt-4o"

"anthropic/claude-3-5-sonnet-20241022"

"google/gemini-2.5-flash"

"mistral/mistral-large-latest"

messages

object[]

required

Minimum array length: 1

Show child attributes

max_tokens

integer

Maximum tokens to generate. The gateway maps this to the correct upstream parameter — max_completion_tokens for OpenAI reasoning models, max_tokens for everything else.

Example:

1024

temperature

number

Sampling temperature. Omit for reasoning models (o3, o3-mini, o4-mini) — the gateway strips it automatically based on the model catalog.

Required range: 0 <= x <= 2

Example:

0.7

top_p

number

Nucleus sampling. Supported by all providers.

Required range: 0 <= x <= 1

stream

boolean

default:false

When true, the response is an OpenAI-compatible SSE stream. Each data: line is a JSON object regardless of the upstream provider.

x-gatelit-output-schema

object

Structured output configuration. The gateway translates to the correct provider-specific format automatically.

Show child attributes

x-gatelit-prompt-id

string

Associates this request with a saved prompt in the dashboard. The prompt's content is not used — only the ID is logged for correlation.

x-gatelit-fallback-chain

object[]

Ordered list of fallback models to try if the primary model fails. Each entry specifies a model and the error types that trigger it.

Show child attributes

Response

Successful response.

Non-streaming: Content-Type: application/json
Streaming: Content-Type: text/event-stream

Response headers always include:

x-gatelit-request-id — use for log lookup in the dashboard
x-gatelit-model — the provider/model that responded
x-gatelit-auth-mode — Bearer, GatelitSigned, or GatelitKey

OpenAI-compatible chat completion response. Returned when stream is false (default).

string

object

string

Example:

"chat.completion"

created

integer

model

string

The upstream model that handled the request.

choices

object[]

Show child attributes

usage

object

Show child attributes

Errors Run Prompt

How it works

API Reference

Chat Completions

Auth

Request

Gateway-specific fields

Response

Non-streaming

Response headers

Streaming

Examples

Structured output

With fallback chain

Errors

Authorizations

Body

Response

​Auth

​Request

​Gateway-specific fields

​Response

​Non-streaming

​Response headers

​Streaming

​Examples

​Structured output

​With fallback chain

​Errors

Authorizations

Body

Response

Auth

Request

Gateway-specific fields

Response

Non-streaming

Response headers

Streaming

Examples

Structured output

With fallback chain

Errors