Create Response

Create a new response using OpenAI’s Responses API.

POST /v1/responses

cURL

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
  }'

200

{
  "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
}

cURL

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
  }'

200

{
  "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).
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.
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.
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.
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:

"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 — 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:

# 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…" } }'

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.

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 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.

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.