# Responses

POST /v1/responses - the OpenAI Responses API, forwarded natively to Codex and OpenAI lanes.

*ProxyLLM docs · https://proxyllm.ai/docs/api/responses*

```
POST /v1/responses
```

Auth: **[routing key](/docs/api/authentication)** (`pllm_…`). Codex and OpenAI lanes get the Responses body natively; other lanes are translated through chat completions and translated back.

## Request body

| Field                                       | Type                      | Notes                                                                                                       |
| ------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `model`                                     | string, required          | Same values as [chat completions](/docs/api/chat-completions).                                              |
| `input`                                     | string or array, required | A string, or Responses items: `message`, `function_call`, `function_call_output`.                           |
| `instructions`                              | string                    | System prompt.                                                                                              |
| `stream`                                    | boolean                   | Server-sent events with Responses API event lines.                                                          |
| `tools`                                     | array                     | Function tools. Only `type: "function"` translates to non-native lanes; other tool types are dropped there. |
| `tool_choice`                               | string or object          | Forwarded.                                                                                                  |
| `text.format`                               | object                    | `json_object` and `json_schema` supported.                                                                  |
| `temperature`, `top_p`, `max_output_tokens` | number                    | Forwarded.                                                                                                  |
| `metadata`                                  | object                    | Echoed back.                                                                                                |
| `previous_response_id`                      | -                         | **Not supported.** Returns `400 unsupported_feature`; resend the full conversation in `input`.              |

```bash
curl https://api.proxyllm.ai/v1/responses \
  -H "Authorization: Bearer pllm_your_routing_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flagship",
    "input": "Say hello."
  }'
```

## Response

The standard Responses object. Trimmed to the fields most callers read:

```json
{
  "id": "resp_4f8d2c9a...",
  "object": "response",
  "created_at": 1751500000,
  "status": "completed",
  "error": null,
  "model": "flagship",
  "output": [
    {
      "id": "msg_a1b2c3...",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        { "type": "output_text", "text": "Hello!", "annotations": [] }
      ]
    }
  ],
  "usage": {
    "input_tokens": 9,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 3,
    "output_tokens_details": { "reasoning_tokens": 0 },
    "total_tokens": 12
  },
  "metadata": {}
}
```

Tool calls appear in `output` as `function_call` items with `call_id`, `name`, and `arguments`. With `"stream": true` the body is `text/event-stream` carrying Responses API events (`response.output_text.delta`, `response.completed`, and so on).

## Errors

| Status | Code                  | When                                             |
| ------ | --------------------- | ------------------------------------------------ |
| 400    | (none)                | `model` or `input` missing, or `input` is empty. |
| 400    | `unsupported_feature` | `previous_response_id` was sent.                 |
| 400    | `no_providers`        | The key has no lanes.                            |
| 401    | `signup_required`     | Missing key, or a raw provider key was sent.     |
| 401    | `invalid_api_key`     | Unknown or revoked routing key.                  |
| 402    | `budget_exceeded`     | Monthly budget exhausted.                        |
| 405    | (none)                | Method other than POST.                          |
| 502    | `upstream_error`      | All lanes failed.                                |

Full list: [error codes](/docs/api#error-codes).