> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routeway.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Request & Response
> Anatomy of a chat completion request and response object.
Every interaction with Routeway follows the same request/response cycle. Understanding the shape of these objects makes it easier to integrate the API, handle edge cases, and debug issues.
## Request Object
A minimal chat completion request looks like this:
```json theme={null}
{
"model": "gpt-4o-mini",
"messages": [
{ "role": "user", "content": "What is 2 + 2?" }
]
}
```
### Common Parameters
| Parameter | Type | Default | Description |
| - | - | - | - |
| `model` | string | required | Model ID to use (e.g. `"gpt-4o"`, `"claude-opus-4-5"`) |
| `messages` | array | required | Ordered list of conversation turns |
| `max_tokens` | integer | model default | Maximum output tokens to generate |
| `temperature` | number | `1.0` | Sampling temperature (`0` = deterministic, `2` = very random) |
| `top_p` | number | `1.0` | Nucleus sampling threshold |
| `stream` | boolean | `false` | Stream tokens as SSE chunks |
| `tools` | array | — | Function schemas the model may call |
| `tool_choice` | string / object | `"auto"` | How the model selects tools |
| `response_format` | object | — | Force `json_object` or `json_schema` output |
| `reasoning_effort` | string | — | `"low"` / `"medium"` / `"high"` for OpenAI reasoning models |
`temperature` and `top_p` both control randomness. Use one or the other — not both. For deterministic tasks like data extraction, set `temperature: 0`. For creative tasks, try values between `0.7` and `1.2`.
***
## Full Request Example
```python theme={null}
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.routeway.ai/v1",
api_key=os.getenv("ROUTEWAY_API_KEY")
)
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Name the planets in our solar system."}
],
max_tokens=150,
temperature=0.3,
)
print(response.choices[0].message.content)
```
```javascript theme={null}
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.routeway.ai/v1",
apiKey: process.env.ROUTEWAY_API_KEY,
});
const response = await client.chat.completions.create({
model: "gpt-4o",
messages: [
{ role: "system", content: "You are a concise assistant." },
{ role: "user", content: "Name the planets in our solar system." },
],
max_tokens: 150,
temperature: 0.3,
});
console.log(response.choices[0].message.content);
```
```bash theme={null}
curl https://api.routeway.ai/v1/chat/completions \
-H "Authorization: Bearer $ROUTEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Name the planets in our solar system."}
],
"max_tokens": 150,
"temperature": 0.3
}'
```
***
## Response Object
A successful response looks like this:
```json theme={null}
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1749052800,
"model": "gpt-4o-2024-11-20",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The eight planets are Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 22,
"total_tokens": 50
}
}
```
### Key Fields
| Field | Description |
| - | - |
| `id` | Unique identifier for this completion |
| `model` | The exact model snapshot that was used |
| `choices` | Array of generated responses (usually one) |
| `choices[0].message.content` | The model's text reply |
| `choices[0].finish_reason` | Why the model stopped generating |
| `usage` | Token counts for billing |
### `finish_reason` Values
| Value | Meaning |
| - | - |
| `"stop"` | Model finished naturally |
| `"length"` | Hit `max_tokens` limit — response may be truncated |
| `"tool_calls"` | Model wants to call a function |
| `"content_filter"` | Response blocked by a content policy |
| `"null"` | Stream is still in progress (streaming only) |
Always check `finish_reason`. A value of `"length"` means the response was cut off. Handle it by either increasing `max_tokens` or detecting and requesting a continuation.
***
## Accessing the Response Text
The model's reply lives at `choices[0].message.content`:
```python theme={null}
text = response.choices[0].message.content
```
When `n > 1`, multiple completions are returned and you index into `choices[0]`, `choices[1]`, etc.
When the model calls a tool instead of replying with text, `content` may be `null` and `tool_calls` will be populated:
```python theme={null}
message = response.choices[0].message
if message.tool_calls:
# model wants to call a function
for tc in message.tool_calls:
print(tc.function.name, tc.function.arguments)
else:
# normal text response
print(message.content)
```
***
## Error Responses
When something goes wrong, Routeway returns a standard error object:
```json theme={null}
{
"error": {
"message": "Invalid model: 'gpt-999'.",
"type": "invalid_request_error",
"code": "model_not_found"
}
}
```
| HTTP status | Type | Common causes |
| - | - | - |
| `400` | `invalid_request_error` | Bad parameters, context too long, invalid model ID |
| `401` | `authentication_error` | Missing or invalid API key |
| `429` | `rate_limit_error` | Too many requests or insufficient balance |
| `500` | `server_error` | Upstream provider error |
See the [Errors](/getting-started/errors) page for the full list and handling guidance.
***
## HTTP Headers
Every request must include:
```
Authorization: Bearer YOUR_ROUTEWAY_API_KEY
Content-Type: application/json
```
The response includes a `x-request-id` header you can use when contacting support about a specific call.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.