> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses

> POST /v1/responses — OpenAI's newer unified response endpoint

`/v1/responses` is OpenAI's newer endpoint that manages multi-step conversations and tool calls with a unified response object, suited to agent scenarios.

<Info>OpenAI now positions the **Responses API as the recommended default interface** — prefer it for new projects; Chat Completions remains supported long-term with backward compatibility.</Info>

## Differences from chat/completions

| Dimension   | `/v1/chat/completions`                 | `/v1/responses`                                              |
| ----------- | -------------------------------------- | ------------------------------------------------------------ |
| Input       | `messages` array                       | `input` (a string, message array, or `previous_response_id`) |
| State       | Stateless, full history sent each time | Optionally stateful (`store: true`)                          |
| Tools       | `tools` + `tool_calls`                 | Built-in `web_search`, `file_search`, `code_interpreter`     |
| Model scope | All models                             | Mainly newer OpenAI models                                   |

## Request

```bash theme={null}
curl https://openp.ai/v1/responses \
  -H "Authorization: Bearer $OPENPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Introduce OpenPAI in 200 words"
  }'
```

### Main parameters

| Field                   | Type             | Description                                                 |
| ----------------------- | ---------------- | ----------------------------------------------------------- |
| `model`                 | string           | Model ID                                                    |
| `input`                 | string \| array  | Input content, plain text or a multimodal array             |
| `instructions`          | string           | Equivalent to a system prompt                               |
| `previous_response_id`  | string           | Continue from a previous response without resending history |
| `tools`                 | array            | Built-in tools or custom functions                          |
| `tool_choice`           | string \| object | Tool selection strategy                                     |
| `stream`                | boolean          | Streaming output                                            |
| `store`                 | boolean          | Whether to save conversation state server-side              |
| `temperature` / `top_p` | number           | Sampling parameters                                         |
| `max_output_tokens`     | integer          | Maximum output tokens                                       |
| `reasoning`             | object           | `{ effort: "high" }` reasoning effort                       |
| `metadata`              | object           | Business labels                                             |
| `user`                  | string           | End-user identifier                                         |

## Response

```json theme={null}
{
  "id": "resp_...",
  "object": "response",
  "created_at": 1715750400,
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "OpenPAI is a..."}]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 48,
    "total_tokens": 60,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens_details": { "reasoning_tokens": 0 }
  }
}
```

You can get the merged text directly via `response.output_text` (an SDK helper field).

## Multi-turn conversation

The second turn doesn't resend history — use `previous_response_id`:

```json theme={null}
{
  "model": "gpt-5.5",
  "previous_response_id": "resp_...",
  "input": "Expand on point 2"
}
```

You must pass `store: true` in the first request so OpenPAI retains the state.

## Reasoning

```json theme={null}
{
  "model": "o3-mini",
  "input": "Prove that √2 is irrational",
  "reasoning": { "effort": "high" },
  "max_output_tokens": 4096
}
```

## Built-in tools

```json theme={null}
{
  "model": "gpt-5.5",
  "input": "Latest OpenPAI news",
  "tools": [{ "type": "web_search" }]
}
```

Supported built-in tools (subject to upstream availability):

* `web_search` — search the web
* `file_search` — retrieve from uploaded files
* `code_interpreter` — execute code in a sandbox

Some built-in tools depend on the upstream environment; OpenPAI passes the results through.