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.
RequestDirect 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.
StreamingDirect 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 headersDirect link to Response headers
| Header | Description |
|---|---|
x-request-id | Unique request ID. Matches the entry in your usage logs. |
x-gateway-provider | The provider that served the request. |
x-gateway-project | The project the key belongs to. Sent for project keys only. |
See Usage, pricing, and limits for error codes.