Skip to main content

Chat Completions

POST https://gateway-api.mastra.ai/v1/chat/completions

Compatible with the OpenAI Chat Completions API. Works with every chat model in the catalog, including non-OpenAI providers.

Request
Direct link to Request

curl https://gateway-api.mastra.ai/v1/chat/completions \
-H "Authorization: Bearer $MASTRA_GATEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-haiku-5.5",
"messages": [
{ "role": "system", "content": "Answer in one sentence." },
{ "role": "user", "content": "What is a gateway?" }
],
"max_tokens": 100
}'

Common fields:

model:

string
A provider/model ID from `/v1/models`.

messages:

Message[]
System, developer, user, assistant, and tool messages.

stream?:

boolean
Stream server-sent events. Set stream_options.include_usage to receive a final usage chunk.

tools?:

Tool[]
Function tools, plus Gateway tools such as web search.

tool_choice?:

'auto' | 'none' | 'required' | object
Controls which tool the model calls.

response_format?:

object
Text, JSON object, or JSON schema output.

max_tokens?:

number
Maximum tokens to generate.

max_completion_tokens?:

number
Maximum completion tokens, including reasoning tokens.

temperature?:

number
Sampling temperature.

top_p?:

number
Nucleus sampling probability.

stop?:

string | string[]
Sequences that stop generation.

seed?:

number
Seed for best-effort deterministic sampling.

web_search_options?:

object
Search context size and approximate user location for web search.

Gateway validates the request before routing. Unknown top-level fields are ignored. A body that doesn't match the schema returns 422.

Streaming
Direct link to Streaming

import OpenAI from 'openai'

const client = new OpenAI({
apiKey: process.env.MASTRA_GATEWAY_API_KEY,
baseURL: 'https://gateway-api.mastra.ai/v1',
})

const stream = await client.chat.completions.create({
model: 'openai/gpt-6.1-sol',
messages: [{ role: 'user', content: 'Count to five.' }],
stream: true,
stream_options: { include_usage: true },
})

for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? '')
}

Gateway fails over only before the first chunk is sent. After streaming starts, an upstream error ends the stream. See Models and routing.

Response headers
Direct link to Response headers

HeaderDescription
x-request-idUnique request ID. Matches the entry in your usage logs.
x-gateway-providerThe provider that served the request.
x-gateway-projectThe project the key belongs to. Sent for project keys only.

See Usage, pricing, and limits for error codes.

On this page