> ## 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 Responses API request and response object.

The Responses API uses a streamlined request format and returns a richer response object compared to Chat Completions. This page covers every key field.

## Request Object

A minimal request needs only a `model` and `input`:

```json theme={null}
{
  "model": "gpt-4o",
  "input": "Explain photosynthesis in one sentence."
}
```

### Input Formats

The `input` field accepts multiple formats:

| Format        | Example                                | Use case                                     |
| ------------- | -------------------------------------- | -------------------------------------------- |
| Plain string  | `"What is 2+2?"`                       | Simple single-turn questions                 |
| Message array | `[{"role": "user", "content": "..."}]` | Multi-role conversations with system prompts |

**String input:**

```json theme={null}
{
  "model": "gpt-4o",
  "input": "What is the speed of light?"
}
```

**Message array input (with system prompt):**

```json theme={null}
{
  "model": "gpt-4o",
  "input": [
    { "role": "system", "content": "You are a physics tutor." },
    { "role": "user", "content": "What is the speed of light?" }
  ]
}
```

***

### Common Parameters

| Parameter              | Type             | Default       | Description                                                                 |
| ---------------------- | ---------------- | ------------- | --------------------------------------------------------------------------- |
| `model`                | string           | required      | Model ID to use (e.g. `"gpt-4o"`, `"gpt-4o-mini"`)                          |
| `input`                | string \| array  | required      | The user input — a plain string or a messages array                         |
| `instructions`         | string           | —             | System-level instructions (alternative to a system message in `input`)      |
| `max_output_tokens`    | integer          | model default | Maximum 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 output as Server-Sent Events                                         |
| `tools`                | array            | —             | Built-in tools or custom function schemas                                   |
| `tool_choice`          | string \| object | `"auto"`      | How the model selects tools                                                 |
| `text`                 | object           | —             | Text output configuration (e.g. `{"format": {"type": "json_schema", ...}}`) |
| `previous_response_id` | string           | —             | Chain this response to a previous one for multi-turn                        |
| `reasoning`            | object           | —             | Reasoning configuration for o-series models (e.g. `{"effort": "high"}`)     |
| `store`                | boolean          | `true`        | Whether to store the response for multi-turn use                            |

<Tip>
  Use `instructions` as a cleaner alternative to embedding a system message inside `input`. It keeps your input focused on the user's question.
</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.responses.create(
        model="gpt-4o",
        instructions="You are a concise assistant. Reply in one paragraph.",
        input="Explain how DNS works.",
        max_output_tokens=200,
        temperature=0.3,
    )

    print(response.output_text)
    ```
  </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.responses.create({
      model: "gpt-4o",
      instructions: "You are a concise assistant. Reply in one paragraph.",
      input: "Explain how DNS works.",
      max_output_tokens: 200,
      temperature: 0.3,
    });

    console.log(response.output_text);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.routeway.ai/v1/responses \
      -H "Authorization: Bearer $ROUTEWAY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-4o",
        "instructions": "You are a concise assistant. Reply in one paragraph.",
        "input": "Explain how DNS works.",
        "max_output_tokens": 200,
        "temperature": 0.3
      }'
    ```
  </Tab>
</Tabs>

***

## Response Object

A successful response looks like this:

```json theme={null}
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1749052800,
  "model": "gpt-4o-2024-11-20",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "DNS (Domain Name System) translates human-readable domain names into IP addresses..."
        }
      ]
    }
  ],
  "output_text": "DNS (Domain Name System) translates human-readable domain names into IP addresses...",
  "usage": {
    "input_tokens": 35,
    "output_tokens": 62,
    "total_tokens": 97
  }
}
```

### Key Fields

| Field         | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| `id`          | Unique response identifier (used for multi-turn via `previous_response_id`) |
| `object`      | Always `"response"`                                                         |
| `status`      | `"completed"`, `"failed"`, `"in_progress"`, or `"cancelled"`                |
| `output`      | Array of output items (messages, tool calls, etc.)                          |
| `output_text` | Convenience field — the concatenated text content from all output messages  |
| `model`       | The exact model snapshot used                                               |
| `usage`       | Token counts for billing                                                    |

<Info>
  The `output_text` field is a shortcut. For simple text responses, use it directly instead of digging into `output[0].content[0].text`.
</Info>

### Output Item Types

The `output` array can contain different item types:

| Type                    | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `message`               | A text response from the model                        |
| `function_call`         | The model wants to call a custom function you defined |
| `web_search_call`       | The model performed a web search (built-in tool)      |
| `file_search_call`      | The model searched uploaded files (built-in tool)     |
| `code_interpreter_call` | The model executed code (built-in tool)               |

***

## Status Values

| Status          | Meaning                                                     |
| --------------- | ----------------------------------------------------------- |
| `"completed"`   | Response generated successfully                             |
| `"failed"`      | An error occurred during generation                         |
| `"in_progress"` | Response is still being generated (streaming or background) |
| `"cancelled"`   | Response was cancelled before completion                    |

<Warning>
  Always check the `status` field. A `"failed"` status means the response was not generated — check the `error` field on the response object for details.
</Warning>

***

## Accessing the Response Text

The simplest way to get the model's reply:

```python theme={null}
text = response.output_text
```

For more control, iterate over the `output` array:

```python theme={null}
for item in response.output:
    if item.type == "message":
        for content in item.content:
            if content.type == "output_text":
                print(content.text)
```

When the model calls a function, the output includes a `function_call` item:

```python theme={null}
for item in response.output:
    if item.type == "function_call":
        print(f"Function: {item.name}")
        print(f"Arguments: {item.arguments}")
```

***

## Error Responses

Errors follow the same format as Chat Completions:

```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, invalid model, context too long |
| `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.