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

# Create Response

> Create a new response using OpenAI's Responses API.

```bash cURL theme={null}
curl https://gateway.bud.studio/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "What is the capital of France?",
    "instructions": "You are a helpful geography tutor.",
    "max_output_tokens": 256,
    "reasoning": { "effort": "medium" },
    "truncation": "disabled",
    "store": true,
    "background": false,
    "stream": false
  }'
```

```json 200 theme={null}
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1699000000,
  "model": "gpt-4o",
  "status": "completed",
  "output": [
    {
      "id": "msg_xyz",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        { "type": "output_text", "text": "The capital of France is Paris.", "annotations": [] }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 8,
    "total_tokens": 23,
    "input_tokens_details":  { "cached_tokens": 0 },
    "output_tokens_details": { "reasoning_tokens": 0 }
  },
  "metadata": null
}
```

## Headers

| Parameter | Type | Required | Description |
| - | - | - | - |
| `Authorization` | string | Yes | Bearer authentication header |
| `Content-Type` | string | Yes | Must be `application/json` |

## Body

### Core request fields

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | Model identifier to invoke. Must match a deployment with `/v1/responses` enabled (see [Deployment Settings](https://docs.budecosystem.com/projects/guides/deployment-settings-and-autoscaling.md)). |
| `input` | string or array | Yes\* | Text or multimodal content. *Optional when `prompt` is provided.* |
| `prompt` | object | No | Versioned prompt template reference (`{ id, version, variables }`). Renders before user input. |
| `instructions` | string | No | System instructions for this call. Overrides the deployment-level default if one is configured. |
| `previous_response_id` | string | No | Stored response ID to continue from. Server walks the chain and prepends prior turns. Capped by the deployment's `chain_depth_limit` (default 200) — above the cap returns `400 chain_too_deep`. An id that does not resolve (unknown, or belonging to another key) returns `400 previous_response_not_found`. |
| `conversation` | string or object | No | Conversation this response belongs to — an id string, or `{ "id": "conv_..." }`. Prior turns in the conversation are prepended to this request's input and this turn is appended to it. Cannot be combined with `previous_response_id` (`400`). Max 256 characters. See [Conversations](#conversations-and-continuation). |
| `metadata` | object | No | Custom key-value pairs (max 16, keys ≤64 chars, values ≤512 chars). Echoed back on the response and persisted when `store=true`. |

### Sampling

| Parameter | Type | Required | Description |
| - | - | - | - |
| `temperature` | float | No | Sampling temperature (0.0 – 2.0). Default `1.0`. |
| `top_p` | float | No | Nucleus sampling. Default `1.0`. |
| `max_output_tokens` | integer | No | Maximum tokens the model may emit. Clamped to the deployment's `max_output_tokens` cap (default 16384) — above the cap returns `200` with `incomplete_details.reason = "max_output_tokens"`. |
| `modalities` | array | No | Output modalities, e.g. `["text"]`. Default `["text"]`. |
| `response_format` | object | No | OpenAI-style structured-output schema, e.g. `{ "type": "json_schema", "json_schema": {...} }`. |

### Reasoning & truncation

| Parameter | Type | Required | Description |
| - | - | - | - |
| `reasoning` | object | No | `{ "effort": "minimal" \| "low" \| "medium" \| "high" \| "xhigh" }`. Only meaningful on reasoning-capable models. If omitted, falls back to the deployment's default `reasoning_effort`. |
| `truncation` | string | No | `"disabled"` (default) or `"auto"` — `auto` truncates older content when the context window overflows. Can also be set as a deployment default. |

### Tools

| Parameter | Type | Required | Description |
| - | - | - | - |
| `tools` | array | No | Function/MCP tool definitions for this call. Hosted tools (`web_search`, `web_fetch`) declared at the deployment level are auto-attached on every call and do **not** need to be re-declared here. |
| `tool_choice` | string or object | No | `"auto"` (default), `"none"`, `"required"`, or `{ "type": "function", "name": "…" }`. |
| `parallel_tool_calls` | boolean | No | Allow the model to call multiple tools in the same turn. Default `true`. |
| `max_tool_calls` | integer | No | Hard cap on tool invocations per response. Clamped to the deployment's `max_tool_calls` cap (default 50). |
| `include` | array | No | Extra fields to include in stored response items (e.g. `["encrypted_content"]` for state passthrough with `store=false`). |

### Persistence & background mode

| Parameter | Type | Required | Description |
| - | - | - | - |
| `store` | boolean | No | Persist the response so it can be retrieved via `GET /v1/responses/{id}` and chained from. Defaults to the deployment's configured default (typically `true`). Zero-data-retention deployments force this to `false`. See [What `store: false` guarantees](#what-store-false-guarantees). |
| `background` | boolean | No | Return immediately with `status: "queued"` and process the request asynchronously server-side. Final result is fetched via `GET /v1/responses/{id}`. Requires the deployment to allow background mode — otherwise returns `400 background_not_allowed`. Subject to a configurable wall-clock timeout (default 3600s). |
| `service_tier` | string | No | `"auto"` (default), `"default"`, `"flex"`, or `"scale"`. Routes through the configured tier when supported. |

### Streaming

| Parameter | Type | Required | Description |
| - | - | - | - |
| `stream` | boolean | No | Stream the response as Server-Sent Events. Default `false`. See [Response Format → Streaming](https://docs.budecosystem.com/api-sdk/responses/response-format.md#streaming-response-format). |
| `stream_options` | object | No | Streaming behaviour, e.g. `{ "include_usage": true }` to receive a final `usage` chunk. |

### Identity

| Parameter | Type | Required | Description |
| - | - | - | - |
| `user` | string | No | End-user identifier for abuse monitoring. Surfaced in observability. |

## Conversations and continuation

There are two ways to continue a thread, and they are mutually exclusive — sending both
returns `400` (`` `previous_response_id` cannot be used in conjunction with `conversation`. ``).

> **previous\_response\_id**
>
> Continue from **one specific turn**. The server walks that turn's chain and prepends the
> prior turns. Use it to branch deliberately from an older turn.

> **conversation**
>
> Continue **the thread**. The server resolves the conversation's latest turn for you, so a
> client that only keeps one handle never has to track response ids at all.

### The response always carries the conversation

Every response echoes the **effective** conversation as an object:

```json theme={null}
"conversation": { "id": "conv_9f2c1d7b4a6e08f35c1d2b7e4a9f6038" }
```

This is present on every envelope shape — the completed response, the `200` returned by
`background: true`, and the paused/withheld envelopes described in
[Response Format](https://docs.budecosystem.com/api-sdk/responses/response-format.md#governance-outcomes) — and a later
`GET /v1/responses/{id}` reports the same value.

### Ids are minted for you

A call that supplies **neither** `conversation` nor `previous_response_id` is given a
server-minted `conv_*` id, stamped on the stored response and echoed back, so the client has a
reusable handle without inventing one:

```bash theme={null}
# Turn 1 — no handle supplied
curl https://gateway.bud.studio/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "gpt-4o", "input": "Plan a trip to Lisbon." }'
# → { "id": "resp_a1", "conversation": { "id": "conv_9f2c…" }, ... }

# Turn 2 — continue the thread with that handle
curl https://gateway.bud.studio/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "gpt-4o", "input": "Three days, no museums.",
        "conversation": { "id": "conv_9f2c…" } }'
```

> [!NOTE]
>
> This is a deliberate divergence from OpenAI, which never mints conversation ids (it has a
> separate `POST /v1/conversations` resource that Bud does not implement). Operators can turn
> minting off with `RESPONSES_AUTO_CONVERSATION=false`, after which no id is returned unless the
> client sends one.

### The echoed parent is the one that was stored

`previous_response_id` on the response body is the parent the turn was **actually** stored
with, which is not always the one you sent: when two turns of the same conversation arrive
together, the server serializes them and chains the second onto the first rather than letting
the thread fork. A turn continued by `conversation` therefore reports the parent the server
resolved, and `GET /v1/responses/{id}` reports the same one.

## What `store: false` guarantees

`store: false` means the turn's **content** is not retained after the response is returned:

* an ordinary run's row is removed once the answer is delivered, so `GET /v1/responses/{id}`
  returns `404` afterwards;
* a run that a **governance policy** touched keeps a content-free skeleton instead of being
  deleted — its `input`, `output`, `instructions` and `prompt_variables` are emptied, but the
  row survives so the record of an approval a human actually gave is not destroyed with it;
* a crash between the answer and the cleanup is swept afterwards, so content cannot be
  retained indefinitely by a badly-timed restart.

Deleting a turn with `store: false` never truncates a thread it was chained into — see
[Delete Response](https://docs.budecosystem.com/api-sdk/responses/delete-response.md).

## Notes on deployment-level configuration

Several fields above (`max_output_tokens`, `max_tool_calls`, `reasoning.effort`, `truncation`, `store`, `background`, `instructions`) have **per-deployment defaults and caps** configured in the deployment's **Settings → Responses API** tab. Behaviour summary:

* **Limits clamp** — `max_output_tokens` / `max_tool_calls` above the deployment cap return `200 OK` with `incomplete_details.reason` set. The chain-depth limit is enforced as a hard `400 chain_too_deep`.
* **Capability gates** — `background: true` against a deployment with background mode disabled returns `400 background_not_allowed`. Zero-data-retention deployments force `store = false` regardless of request.
* **Defaults pre-fill** — `reasoning.effort`, `truncation`, `instructions` from the deployment apply when the request omits them. Per-request values always override.
* **Server tools auto-attach** — `web_search` and `web_fetch` enabled at the deployment level attach to every call without the client declaring them in `tools[]`. The model decides whether to invoke them.

See the [Deployment Settings guide](https://docs.budecosystem.com/projects/guides/deployment-settings-and-autoscaling.md) for how to configure these.

## Supported Providers

`/v1/responses` is **provider-agnostic** — it works with **any chat-capable
model deployed through Bud**, including models from providers that don't offer a
Responses API of their own.

> **OpenAI / Azure OpenAI**
>
> GPT-4o, o-series and Azure deployments.

> **Anthropic**
>
> Claude models, including extended-thinking (reasoning) variants.

> **Google / Mistral**
>
> Gemini and Mistral chat models.

> **Moonshot / DeepSeek**
>
> Kimi K2.5 / K2-thinking and DeepSeek-Reasoner, with reasoning-token
> accounting preserved.

> **Self-hosted open weights**
>
> Any vLLM / SGLang deployment (Llama, Qwen, etc.).

> **…and others**
>
> Any current or future model available on your Bud deployment.

> [!NOTE]
>
> To serve `/v1/responses`, a deployment needs the **Responses API** turned on in
> its **Settings** tab (this also requires `/v1/chat/completions` to be enabled
> on the same deployment).
>
> Model-specific behaviour still applies: e.g. `reasoning.effort` only affects
> reasoning-capable models.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.