> ## 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   |

<Tip>
  `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`.
</Tip>

***

## Full Request Example

<Tabs>
  <Tab title="Python">
    ```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)
    ```
  </Tab>

  <Tab title="Node.js">
    ```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);
    ```
  </Tab>

  <Tab title="cURL">
    ```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
      }'
    ```
  </Tab>
</Tabs>

***

## 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)       |

<Warning>
  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.
</Warning>

***

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