# Responses API

> Use the OpenAI Responses API on OpenCheese: POST /v1/responses with instructions, input items, streaming events, function tools and reasoning effort.
>
> Web page: https://opencheese.dev/en/docs/responses/ · Every docs page: https://opencheese.dev/llms.txt

`POST https://api.opencheese.dev/v1/responses` is the OpenAI Responses API. Codex uses it, and
so do the OpenAI SDKs' `responses` methods.

## A first request

```bash
curl https://api.opencheese.dev/v1/responses \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "instructions": "Answer in one sentence.", "input": "What is a gateway?"}'
```

`model` is required; `input` is a string or a list of input items, and `instructions` becomes
the system prompt. The answer's text is in `output[].content[]` items of type `output_text`:

```json
{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "MODEL_ID",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "A gateway passes your requests on to the models behind it." }]
    }
  ],
  "usage": { "input_tokens": 24, "output_tokens": 13, "total_tokens": 37 }
}
```

## Parameters

| Field | Notes |
| --- | --- |
| `model` | Required. An `id` from [`/v1/models`](https://opencheese.dev/en/docs/models.md). |
| `input` | A string, or `message`, `function_call` and `function_call_output` items. |
| `instructions` | The system prompt. |
| `stream` | `true` for server-sent events. |
| `tools`, `tool_choice` | Function tools, where the model supports tools. |
| `reasoning.effort` | A level from the model's `supported_reasoning_levels`. |
| `temperature`, `top_p`, `max_output_tokens` | Optional. If you don't set them, the model's defaults are used. |

## Conversations are sent in full

Every request carries the whole conversation in `input`: replay earlier turns as `message`
items (the assistant's with `role: "assistant"`). `previous_response_id`, `store` and
`text.format` are not supported here; for structured output, use
[Chat Completions](https://opencheese.dev/en/docs/chat-completions.md) with `response_format`.

```json
{
  "model": "MODEL_ID",
  "input": [
    { "type": "message", "role": "user", "content": "Name three cheeses." },
    { "type": "message", "role": "assistant", "content": "Brie, Gouda and Comté." },
    { "type": "message", "role": "user", "content": "Which one melts best?" }
  ]
}
```

## Streaming

```bash
curl -N https://api.opencheese.dev/v1/responses \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "stream": true, "input": "Count to three."}'
```

The stream sends the Responses event types: `response.created` and `response.in_progress`,
then `response.output_item.added`, `response.output_text.delta` with the text, the matching
`.done` events, and finally `response.completed` with the full response and its `usage`. A
request that fails after the stream has started ends with `response.failed`, whose
`response.error` holds a `code` and a `message`.

```text
event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"One, two"}

event: response.completed
data: {"type":"response.completed","response":{"status":"completed","usage":{"input_tokens":12,"output_tokens":6,"total_tokens":18}}}
```

## Tools

```json
{
  "model": "MODEL_ID",
  "input": "What is the weather in Paris?",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Current weather for a city",
      "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }
    }
  ]
}
```

A tool call arrives as a `function_call` output item with `call_id`, `name` and `arguments`.
Send the result back in the next request as a `function_call_output` item with the same
`call_id`, after the `function_call` item itself.

## Reasoning effort

```bash
curl https://api.opencheese.dev/v1/responses \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "reasoning": {"effort": "high"}, "input": "Plan a three-day trip to Lyon."}'
```

If you don't set an effort, the model's default is used. A level the model doesn't offer is
refused with `unsupported_reasoning_effort`, listing the levels it does offer. Reasoning
summaries, where the model returns them, arrive as `reasoning` output items.

## Usage

`usage` reports `input_tokens` (with `input_tokens_details.cached_tokens`), `output_tokens`
(with `output_tokens_details.reasoning_tokens`) and `total_tokens`.

## Python

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.opencheese.dev/v1", api_key="YOUR_OPENCHEESE_API_KEY")
response = client.responses.create(model="MODEL_ID", input="Write a haiku about cheese.")
print(response.output_text)
```

Errors on this endpoint are always an HTTP status with a JSON body, never an assistant reply as on
Chat Completions; once a stream has started, they arrive as `response.failed`. See
[Errors and rate limits](https://opencheese.dev/en/docs/errors.md). Add the
[`opencheese-session-uuid`](https://opencheese.dev/en/docs/sessions.md) header to keep a conversation together.