> ## 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](/projects/guides/deployment-settings-and-autoscaling#responses-api)). |
| `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`. |
| `metadata` | object | No | Custom key-value pairs (max 16). 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`. |
| `background` | boolean | No | Return immediately with `status: "in_progress"` 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](/api-sdk/responses/response-format#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. |
## 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](/projects/guides/deployment-settings-and-autoscaling) 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.
GPT-4o, o-series and Azure deployments.
Claude models, including extended-thinking (reasoning) variants.
Gemini and Mistral chat models.
Kimi K2.5 / K2-thinking and DeepSeek-Reasoner, with reasoning-token
accounting preserved.
Any vLLM / SGLang deployment (Llama, Qwen, etc.).
Any current or future model available on your Bud deployment.
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.