Create Response - Bud Stack Documentation

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

Get ResponseRetrieve a response by ID.

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

​Body

​Core request fields

​Sampling

​Reasoning & truncation

​Tools

​Persistence & background mode

​Streaming

​Identity

​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

Notes on deployment-level configuration

Supported Providers