Create Response

POST

responses

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

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

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

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

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

Introduction

Gateway APIs

Python SDK & CLI

Headers

Body

Core request fields

Sampling

Reasoning & truncation

Tools

Persistence & background mode

Streaming

Identity

Conversations and continuation

previous_response_id

conversation

The response always carries the conversation

Ids are minted for you

The echoed parent is the one that was stored

What `store: false` guarantees

Notes on deployment-level configuration

Supported Providers

OpenAI / Azure OpenAI

Anthropic

Google / Mistral

Moonshot / DeepSeek

Self-hosted open weights

…and others

​Headers

​Body

​Core request fields

​Sampling

​Reasoning & truncation

​Tools

​Persistence & background mode

​Streaming

​Identity

​Conversations and continuation

previous_response_id

conversation

​The response always carries the conversation

​Ids are minted for you

​The echoed parent is the one that was stored

​What store: false guarantees

​Notes on deployment-level configuration

​Supported Providers

OpenAI / Azure OpenAI

Anthropic

Google / Mistral

Moonshot / DeepSeek

Self-hosted open weights

…and others

Headers

Body

Core request fields

Sampling

Reasoning & truncation

Tools

Persistence & background mode

Streaming

Identity

Conversations and continuation

The response always carries the conversation

Ids are minted for you

The echoed parent is the one that was stored

What `store: false` guarantees

Notes on deployment-level configuration

Supported Providers