# Responses API The OpenAI Responses API over your org's models. Responses-shape requests, items and events, with no stored responses. `POST /v1/responses` serves the OpenAI Responses API. Clients that speak only that API, such as [Codex CLI](https://docs.privatemind.com/coding-agents.html#codex-cli) and the [OpenAI Agents SDK](https://docs.privatemind.com/openai-sdk.html#openai-agents-sdk), work with PrivateMind once you change their base URL and key. It runs on the same models, keys, budgets and rate limits as [chat completions](https://docs.privatemind.com/chat-completions.html). PrivateMind stores no responses, so every request carries the whole conversation: see [Conversations](https://docs.privatemind.com/responses-api.html#conversations). **cURL** ```bash curl -s "https://api.privatemind.com/v1/responses" \ -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "fast", "instructions": "You are a concise assistant.", "input": "Explain the CAP theorem.", "max_output_tokens": 400, "temperature": 0.2 }' ``` **Python** ```python from openai import OpenAI client = OpenAI( base_url="https://api.privatemind.com/v1", api_key="PMIND...:abcdef...", ) response = client.responses.create( model="fast", instructions="You are a concise assistant.", input="Explain the CAP theorem.", max_output_tokens=400, temperature=0.2, ) print(response.output_text) ``` **TypeScript** ```typescript import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.privatemind.com/v1', apiKey: process.env.PMIND_KEY, }); const response = await client.responses.create({ model: 'fast', instructions: 'You are a concise assistant.', input: 'Explain the CAP theorem.', max_output_tokens: 400, temperature: 0.2, }); console.log(response.output_text); ``` The base URL ends in `/v1`, as for chat completions. The key goes in `Authorization: Bearer` or `x-api-key` (see [Authentication](https://docs.privatemind.com/authentication.html)). > [!NOTE] > On a model server registered with [No translation](https://docs.privatemind.com/model-deployments.html#no-translation), the request goes to your vLLM's own `/v1/responses` as sent, apart from the model name, and its answer comes back unchanged. What works then follows your vLLM's own Responses API support. The rest of this page describes the translated path. ## Parameters | Field | What happens | | --- | --- | | `model` (required) | Id or alias of a chat model from [`GET /v1/models`](https://docs.privatemind.com/models.html) | | `input` (required) | One user message as a string, or an array of items. See [Input](https://docs.privatemind.com/responses-api.html#input) | | `instructions` | The system prompt, placed before any `system` or `developer` message in `input` | | `stream` | When `true`, the response arrives as Responses API events. See [Streaming](https://docs.privatemind.com/responses-api.html#streaming) | | `max_output_tokens` | Maximum tokens to generate, reasoning included | | `temperature`, `top_p` | Sampling controls | | `tools` | Function tools, top-level or inside a `namespace`. Hosted tools are dropped and custom tools return `400`. See [Tools](https://docs.privatemind.com/responses-api.html#tools) | | `tool_choice` | `auto`, `none`, `required`, a named function, or `allowed_tools`. See [Tool choice](https://docs.privatemind.com/responses-api.html#tool-choice) | | `parallel_tool_calls` | `false` asks for at most one call per turn | | `text.format` | `text`, `json_object` or `json_schema`. See [Structured output](https://docs.privatemind.com/responses-api.html#structured-output) | | `reasoning.effort` | How much the model thinks. See [Reasoning](https://docs.privatemind.com/responses-api.html#reasoning) | | `reasoning.summary` | Echoed in the response and otherwise unused. Reasoning text is returned whatever it says | | `metadata` | Stored as [usage tags](https://docs.privatemind.com/usage.html#tagging-requests) and not sent to the model, with the same limits as [on chat completions](https://docs.privatemind.com/chat-completions.html#parameters) | | `user`, `safety_identifier` | Passed to the model as the end-user id. When both are set, `user` is used | | `store` | Accepted and ignored. Every response reports `store: false` | | `previous_response_id`, `conversation`, `prompt`, `background: true` | `400`. See [Conversations](https://docs.privatemind.com/responses-api.html#conversations) | Other fields, such as `include`, `truncation`, `service_tier`, `prompt_cache_key`, `max_tool_calls` and `text.verbosity`, are accepted and ignored, so SDK upgrades do not break calls. The whole request body, base64 images included, can be up to 32 MB. A larger body gets `413` with `error.code` `request_too_large`. ## Input `input` is a string or an array of items. An item with no `type` is a `message`, and a message with no `role` is from the user. | Item | What happens | | --- | --- | | `message`, role `user` | `content` is a string or an array of parts: `input_text`, and `input_image` with `image_url` as a URL or a data URL plus an optional `detail`. `input_file`, `input_audio`, an `input_image` given only a `file_id`, and any other part return `400`. See [Vision](https://docs.privatemind.com/vision.html) for which models read images | | `message`, role `assistant` | Its `output_text` parts are the model's earlier answer | | `message`, role `system` or `developer` | At the start of `input`, joined to `instructions` in the system prompt. Later in the conversation, added to the user turn as text, because most chat templates refuse a second system turn | | `reasoning` | The text of its `content` parts is passed back to the model as that turn's reasoning. `summary` and `encrypted_content` are dropped. See [Reasoning items](https://docs.privatemind.com/responses-api.html#reasoning-items) | | `function_call` | A tool call the model made: `call_id`, `name`, `namespace` and `arguments` | | `function_call_output` | The result for a `call_id`. `output` is a string or an array of parts: text parts are joined, images follow the results as a user turn, and other parts are dropped | | `item_reference` | `400`: there is no stored item to point at | | Any other item, such as a hosted tool's call record | Dropped | Consecutive user messages are sent as one user turn, and consecutive reasoning, assistant message and function call items as one assistant turn. A `function_call` whose `arguments` is not valid JSON, such as a call cut short by `max_output_tokens`, reaches the model as `{}`. A reasoning item with nothing after it is dropped. ## Tools ### Function tools Each tool has `name`, `description` and `parameters` at its top level: ```bash curl -s "https://api.privatemind.com/v1/responses" \ -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "fast", "input": "What is the weather in Paris?", "tools": [{ "type": "function", "name": "get_weather", "description": "Get current weather for a city", "parameters": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"] } }] }' ``` A call comes back as a `function_call` item in `output`, after any reasoning: ```json { "arguments": "{\"city\": \"Paris\"}", "call_id": "chatcmpl-tool-83baf0e4cb6cf671", "id": "fc_9be7f795ed7f4bb79a2eb3d4c8441737", "name": "get_weather", "status": "completed", "type": "function_call" } ``` `arguments` is a string containing JSON. To answer, send the conversation again with every `output` item as it came back, followed by a `function_call_output` for each `call_id`: ```json { "model": "fast", "tools": [ ...the same tools... ], "input": [ { "role": "user", "content": "What is the weather in Paris?" }, { "type": "reasoning", "id": "rs_3b3bbd2a4a9945ad86c028dcd114d075", "summary": [], "content": [{ "type": "reasoning_text", "text": "User is asking for the weather in Paris. ..." }] }, { "type": "function_call", "id": "fc_9be7f795ed7f4bb79a2eb3d4c8441737", "call_id": "chatcmpl-tool-83baf0e4cb6cf671", "name": "get_weather", "arguments": "{\"city\": \"Paris\"}", "status": "completed" }, { "type": "function_call_output", "call_id": "chatcmpl-tool-83baf0e4cb6cf671", "output": "{\"temp_c\": 18, \"conditions\": \"overcast\"}" } ] } ``` A tool's `parameters` defaults to an empty object schema. Its `strict` flag is passed to the model server, but the model's engine decides whether calls follow the schema. Validate `arguments` before you act on them. See [Tool use](https://docs.privatemind.com/tool-use.html#responses-api) for the loop in Python. ### Namespaces A `namespace` groups function tools under a name. Calls to a tool inside one come back with its `namespace` as well as its `name`: ```json "tools": [ { "type": "namespace", "name": "tracker", "description": "The issue tracker", "tools": [{ "type": "function", "name": "get", "description": "Fetch an issue by key", "parameters": { "type": "object", "properties": { "key": { "type": "string" } }, "required": ["key"] } }] }, { "type": "namespace", "name": "wiki", "description": "The team wiki", "tools": [{ "type": "function", "name": "get", "description": "Fetch a wiki page by title", "parameters": { "type": "object", "properties": { "title": { "type": "string" } }, "required": ["title"] } }] } ] ``` ```json { "arguments": "{\"key\": \"PM-12\"}", "call_id": "chatcmpl-tool-a5ed80682540b678", "id": "fc_ca25afe5bd174d2e8b2f1cfefcad4e87", "name": "get", "namespace": "tracker", "status": "completed", "type": "function_call" } ``` The model sees each tool under its own name. When two declared functions share a name, as the two `get` tools do here, each one inside a namespace is offered to the model as `__`. The call still comes back under the name and namespace you declared. Send `function_call` items back with their `namespace` so the history matches. A namespace's own `description` is echoed in the response but not sent to the model, so put what the model needs to know in each tool's description. ### Limits - At most 1024 function tools per request, counting those inside namespaces. - Tool and namespace names are 1 to 128 characters. - Two functions that would reach the model under the same name, such as two top-level tools called `get`, return `400`. - Namespace descriptions are echoed up to 16 KB in total; past that, a namespace is echoed with an empty description. ### Hosted and custom tools Hosted tools are the ones OpenAI runs on its side, such as `web_search`, `file_search`, `code_interpreter` and `mcp`. PrivateMind drops them without an error, and the model answers without them. Custom tools (`"type": "custom"`), which take free-form text, return `400`, top-level or inside a namespace. Declare such a tool as a function with a string parameter. ### Tool choice | Value | Behaviour | | --- | --- | | `"auto"` (default) | The model decides whether to call a tool | | `"none"` | The model does not call a tool | | `"required"` | The model must call at least one tool | | `{"type": "function", "name": "...", "namespace": "..."}` | The model must call this tool. `namespace` may be left out when no other function has the same name | | `{"type": "allowed_tools", "mode": "auto", "tools": [...]}` | Only the listed functions are offered to the model, each given as `{"type": "function", "name": ..., "namespace": ...}`. `mode` is `auto` or `required` | If `tool_choice` names a function that is not in `tools`, the request returns `400`. Any other value, such as a hosted tool's choice, is treated as `auto`. With `allowed_tools`, the tools left out are not sent to the model. ## Structured output `text.format` asks for JSON: - `{"type": "json_schema", "name": "...", "schema": {...}, "strict": true}` holds the answer to the schema. A `name` longer than 64 characters is replaced by `output`. - `{"type": "json_object"}` asks for any JSON object. - `{"type": "text"}`, the default, is plain text. ```python from openai import OpenAI from pydantic import BaseModel client = OpenAI(base_url="https://api.privatemind.com/v1", api_key="PMIND...:abcdef...") class Place(BaseModel): city: str country: str response = client.responses.parse( model="fast", input="Extract the city and country: I flew into Lyon last week.", text_format=Place, ) print(response.output_parsed) ``` ### With tools on offer The model servers enforce a schema over a whole turn, which would leave the model no way to call a tool. So when tools are on offer, PrivateMind asks for the format in the system prompt and tool calls work as usual. It checks the final answer, the turn that ends without a tool call, against the format before returning it: - If it matches, it is returned, with any code fence the model added taken off. - If it does not match, PrivateMind runs the same turn again with the format enforced and tool calls off, and returns that answer. This second pass is billed as a request of its own (see [Usage](https://docs.privatemind.com/responses-api.html#usage)), and `output` keeps the first pass's reasoning ahead of the second's. If the second pass can't run, for example because the key's budget is spent, a non-streaming request gets that error, such as `402`. A streaming one ends in `response.failed`. - When the service is busy, an answer can also skip the check and take the second pass. - Some answers are never checked and always take the second pass: a very large answer, or one whose schema is very large or uses any of these: - keywords beyond the common subset, such as `unevaluatedProperties`, `uniqueItems`, `patternProperties` or `if`/`then`/`else` - a `format` other than `date-time`, `date`, `time`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, `uuid` or `uri` - a `$ref` that is recursive or points outside `$defs` or `definitions` - a `$schema` other than draft 2020-12 - Schemas that Python's `responses.parse` builds from pydantic models stay inside the common subset, with a few exceptions. These include a field that is a `set`, `bytes` or a `dict` keyed by an enum or `Literal`, and a pydantic model that refers to itself. - A first answer cut short by `max_output_tokens` is returned as `incomplete`, unchecked. If `max_output_tokens` leaves no room for a second pass, the first answer is returned as `incomplete` too. - When your organization, or the whole service, already has too many large requests of this kind in flight, the request returns `429` with `code` `too_many_requests` before anything runs. A key with too many requests in flight gets the same code, with or without tools. Retry after the 60 seconds in the `retry-after` header. When streaming, reasoning and tool calls arrive as they are written. Text the model writes before a tool call arrives as a single delta when the call starts. The final message arrives once it has been checked, also as a single delta. If it fails the check and the turn runs again, the second pass's reasoning and message stream as they are written, after a `response.in_progress` event. [Keepalives](https://docs.privatemind.com/responses-api.html#keepalives) cover both waits. `"strict": false` skips the check: the format is only asked for in the prompt. With `tool_choice` `"required"` or a named function, there is no final answer to check. When no tool is on offer, for example with `tool_choice: "none"` or only hosted tools declared, the schema is enforced from the start. ## Reasoning ### Effort `reasoning.effort` maps onto the same levels as [`reasoning_effort`](https://docs.privatemind.com/chat-completions.html#reasoning-effort) on chat completions: | You send | Effort | | --- | --- | | Nothing | The model's default | | `"none"` or `"off"` | `off` | | `"minimal"` | `low` | | `"low"`, `"medium"`, `"high"` | That level | | `"xhigh"` or `"max"` | `max` | Any other value returns `400`. A thinking-only model, such as Kimi K3.1 Pro or GLM 5.3, can't stop thinking, so it returns `400` for `"none"`. Each model lists the levels it tells apart in [`capabilities.reasoning_effort_levels`](https://docs.privatemind.com/models.html#capabilities). On a [model server you launched](https://docs.privatemind.com/model-deployments.html), the level reaches your vLLM as `reasoning_effort`, with `off` sent as `none`. ### Reasoning items A model that thinks returns a `reasoning` item before its answer, with its reasoning text in `content` as `reasoning_text`. `summary` is always empty. ```bash curl -s "https://api.privatemind.com/v1/responses" \ -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "reasoning", "input": "What is 17 * 23?", "reasoning": {"effort": "low"} }' ``` ```json "output": [ { "content": [{"text": "17*23 = 17*20+17*3 = 340+51 = 391.", "type": "reasoning_text"}], "id": "rs_a541038aa64b430ca6c0f187922cd232", "summary": [], "type": "reasoning" }, { "content": [{"annotations": [], "logprobs": [], "text": "17 × 23 = **391**", "type": "output_text"}], "id": "msg_48a8e034c0a54974aab724468489ac83", "role": "assistant", "status": "completed", "type": "message" } ] ``` Send reasoning items back unchanged in later turns, as Codex and the SDKs do, and their `content` text is passed back to the model. Whether the model uses it depends on its chat template: many keep only the reasoning of the current tool loop. Reasoning is unfiltered model output: see [Shared responsibility](https://docs.privatemind.com/shared-responsibility.html#reasoning-output). ## Response ```json { "id": "resp_64a1d3adf74d4b5d9de35eec5e7f7e2e", "object": "response", "created_at": 1794876535, "status": "completed", "background": false, "error": null, "incomplete_details": null, "instructions": "You are a concise assistant.", "max_output_tokens": 400, "metadata": {}, "model": "fast", "parallel_tool_calls": true, "reasoning": { "effort": null, "summary": null }, "temperature": 0.2, "text": { "format": { "type": "text" } }, "tool_choice": "auto", "tools": [], "top_p": null, "user": null, "output": [ { "content": [{ "text": "We need answer user: \"Explain the CAP theore ...", "type": "reasoning_text" }], "id": "rs_e3affa4de1cc44ad8cac07979960fadc", "summary": [], "type": "reasoning" }, { "content": [{ "annotations": [], "logprobs": [], "text": "The **CAP theorem** says that a distributed data system ...", "type": "output_text" }], "id": "msg_a8bb56ca60294ae1808b63bd4f17aab6", "role": "assistant", "status": "completed", "type": "message" } ], "previous_response_id": null, "store": false, "truncation": "disabled", "usage": { "input_tokens": 65, "input_tokens_details": { "cache_write_tokens": 0, "cached_tokens": 0 }, "output_tokens": 321, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 386 } } ``` `output` holds items in the order the model wrote them, usually reasoning, then the message, then any `function_call` items. There is no message item when the model wrote no text, or only whitespace. The response repeats the parameters as they were applied: - `model`, `instructions`, `max_output_tokens`, `temperature`, `top_p` and `metadata` as you sent them. - `tools` holds only the function tools offered to the model, in the shape you declared them. Hosted tools, and tools `allowed_tools` left out, are not there. - `tool_choice` is the resolved form: `"auto"`, `"none"`, `"required"`, a function with its `namespace`, or `allowed_tools` with its mode and functions. - `text.format` is the format applied. A `json_schema` larger than 64 KB is echoed with an empty `schema`. - `reasoning.effort` and `reasoning.summary` as sent, when 16 characters or fewer, and `user` when 256 characters or fewer; otherwise `null`. - `background` is always `false`, `previous_response_id` always `null`, `store` always `false` and `truncation` always `"disabled"`. ### Status | `status` | Meaning | | --- | --- | | `completed` | The turn ended normally, with an answer or with tool calls | | `incomplete` | `incomplete_details.reason` is `max_output_tokens` (hit `max_output_tokens` or the context window) or `content_filter`. A message or function call cut off this way is marked `incomplete`. A cut-off `function_call` has partial arguments: don't run it. Raise `max_output_tokens` and retry | | `failed` | Streaming only: the stream ended with `response.failed`, and `error` carries a `code` and `message`. See [Streaming](https://docs.privatemind.com/responses-api.html#streaming) | | `in_progress` | Only in the lifecycle events of a stream, before it ends | ### Usage `input_tokens` is the whole prompt, including the part read from the [prompt cache](https://docs.privatemind.com/chat-completions.html#prompt-caching), which `input_tokens_details.cached_tokens` reports. It matches `prompt_tokens` on chat completions. `output_tokens` includes reasoning, and `output_tokens_details.reasoning_tokens` is always `0`. `input_tokens_details.cache_write_tokens` is `0` on the models PrivateMind runs. When a final answer was generated again to match its `text.format` ([With tools on offer](https://docs.privatemind.com/responses-api.html#with-tools-on-offer)), `usage` adds up both passes. Each pass is billed, and listed in [usage](https://docs.privatemind.com/usage.html), as a call of its own. ## Streaming With `"stream": true` the answer arrives as Responses API events, which the OpenAI SDKs and Codex parse natively. ```bash curl -N "https://api.privatemind.com/v1/responses" \ -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "fast", "input": "Write a haiku about TCP.", "stream": true}' ``` Every event is a named `event:` line followed by its `data:`, and every `data` carries `type` and a `sequence_number` that starts at `0`: ```text event: response.created data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_c62db3cb3a67498f9f435315c9ca8faa","object":"response","status":"in_progress",...,"output":[],"usage":null}} event: response.in_progress data: {"type":"response.in_progress","sequence_number":1,"response":{...}} event: response.output_item.added data: {"item":{"content":[],"id":"rs_45905d0065954ca6b3391cf6ac466f40","summary":[],"type":"reasoning"},"output_index":0,"sequence_number":2,"type":"response.output_item.added"} event: response.content_part.added data: {"content_index":0,"item_id":"rs_45905d0065954ca6b3391cf6ac466f40","output_index":0,"part":{"text":"","type":"reasoning_text"},"sequence_number":3,"type":"response.content_part.added"} event: response.reasoning_text.delta data: {"content_index":0,"delta":"We","item_id":"rs_45905d0065954ca6b3391cf6ac466f40","output_index":0,"sequence_number":4,"type":"response.reasoning_text.delta"} ... event: response.output_item.added data: {"item":{"content":[],"id":"msg_ad65c35f4eaa47a9a2432786c11e528a","role":"assistant","status":"in_progress","type":"message"},"output_index":1,"sequence_number":163,"type":"response.output_item.added"} event: response.content_part.added data: {"content_index":0,"item_id":"msg_ad65c35f4eaa47a9a2432786c11e528a","output_index":1,"part":{"annotations":[],"logprobs":[],"text":"","type":"output_text"},"sequence_number":164,"type":"response.content_part.added"} event: response.output_text.delta data: {"content_index":0,"delta":"\n\nThree-way","item_id":"msg_ad65c35f4eaa47a9a2432786c11e528a","logprobs":[],"output_index":1,"sequence_number":165,"type":"response.output_text.delta"} ... event: response.output_text.done data: {"content_index":0,"item_id":"msg_ad65c35f4eaa47a9a2432786c11e528a","logprobs":[],"output_index":1,"sequence_number":170,"text":"\n\nThree-way handshake forms\npackets in order arrive\nACKs confirm each byte","type":"response.output_text.done"} event: response.content_part.done data: {"content_index":0,"item_id":"msg_ad65c35f4eaa47a9a2432786c11e528a","output_index":1,"part":{...},"sequence_number":171,"type":"response.content_part.done"} event: response.output_item.done data: {"item":{...,"status":"completed","type":"message"},"output_index":1,"sequence_number":172,"type":"response.output_item.done"} event: response.completed data: {"type":"response.completed","sequence_number":173,"response":{"id":"resp_c62db3cb3a67498f9f435315c9ca8faa","object":"response","status":"completed",...,"usage":{"input_tokens":59,"input_tokens_details":{"cache_write_tokens":0,"cached_tokens":0},"output_tokens":442,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":501}}} ``` The events come in this order: 1. `response.created`, then `response.in_progress`, both sent at once, before the model has produced anything. 2. For each output item, in the order the model writes them: - `response.output_item.added`. - For reasoning: `response.content_part.added`, `response.reasoning_text.delta` events, `response.reasoning_text.done`, `response.content_part.done`. - For a message: `response.content_part.added`, `response.output_text.delta` events, `response.output_text.done`, `response.content_part.done`. - For a tool call: `response.function_call_arguments.delta` events, then `response.function_call_arguments.done` with the `name` and full `arguments`. - `response.output_item.done` with the finished item. 3. One terminal event: `response.completed`, `response.incomplete` or `response.failed`. It carries the whole response, with `output` and `usage`. Items are written one at a time: one is done before the next is added. ### Keepalives While the model is silent, the stream carries `: ping` comments, as on [chat completions](https://docs.privatemind.com/streaming.html#keepalive-pings). Some clients time out when no event arrives, so after 60 seconds without one, the next keepalive is a `response.in_progress` event carrying the response so far. `: ping` comments carry no data, and a repeated `response.in_progress` needs no handling. They also run, at least every 15 seconds, while a final answer waits for its `text.format` check and before a second pass starts (see [With tools on offer](https://docs.privatemind.com/responses-api.html#with-tools-on-offer)). ### Failures A stream that fails ends with `response.failed`, never with `response.completed`, so a cut-off answer is never presented as complete. The response in it has `status: "failed"` and an `error` with a `code` and a `message`. - **A torn stream**: the model's stream breaks, or ends before the turn is finished. `error.code` is `server_error`. - **An interleaved tool call**: the model goes back to a tool call after starting another item, which cannot be written as items. `error.code` is `server_error`. - **A request that does not fit the context window**: `error.code` is `context_length_exceeded`, right after `response.in_progress`, with the HTTP status still `200`. - **A second pass that cannot run** ([With tools on offer](https://docs.privatemind.com/responses-api.html#with-tools-on-offer)): for example the key's budget runs out before it starts. `error.code` is that failure's code, such as `budget_exceeded`. ```text event: response.failed data: {"type":"response.failed","sequence_number":2,"response":{"id":"resp_05d3e0e0ca7f4621bc90251310cf3bad","object":"response","created_at":1794876636,"status":"failed","background":false,"error":{"code":"context_length_exceeded","message":"This model's maximum context length is 262144 tokens. However, you requested 262000 output tokens and your prompt contains at least 145 input tokens, ..."},...,"output":[],...,"usage":null}} ``` The item being written when the stream failed is abandoned: it gets no `response.output_item.done` and is not in the response's `output`. Items finished before the failure stay in `output`. Don't run tool calls from a failed response. An interleaved tool call was already sent as done, with only the arguments the model wrote before it moved on. Retry the request instead. Errors before the stream starts, such as a `400`, `401` or `429`, come back as a normal JSON error with that status. ## Errors Errors use the OpenAI shape: ```json { "error": { "code": "invalid_request_error", "message": "previous_response_id is not supported: responses are not stored here; send the whole conversation in input", "type": "invalid_request_error" } } ``` The status codes are those of [Errors](https://docs.privatemind.com/errors.html). A request this endpoint refuses returns `400` with `type` `invalid_request_error` and a message that says what to send instead. That covers stored state, custom tools, files, an unknown function in `tool_choice` and a bad `reasoning.effort`. If the prompt and `max_output_tokens` together don't fit the model's context window, the request returns `400` with `code` `context_length_exceeded`. Responses clients look for this code to know when to compact a conversation: ```json { "error": { "code": "context_length_exceeded", "message": "This model's maximum context length is 262144 tokens. However, you requested 262000 output tokens and your prompt contains at least 145 input tokens, for a total of at least 262145 tokens. Please reduce the length of the input prompt or the number of requested output tokens. (parameter=input_tokens, value=145)", "param": null, "type": "invalid_request_error" } } ``` On a stream, the same error arrives as a `response.failed` event (see [Failures](https://docs.privatemind.com/responses-api.html#failures)). Other errors from the model server are [relayed in the model server's shape](https://docs.privatemind.com/errors.html#errors-relayed-from-the-model), with `code` as a number. One example is a `max_output_tokens` that alone is above the model's context length. ## Conversations PrivateMind does not store responses, so there is nothing for an id to point at. These return `400`: - `previous_response_id` - `conversation` - `background: true` - `prompt` (stored prompt templates); send `instructions` and `input` - `item_reference` items in `input` To carry a conversation, send all of it in `input` on every request, in this order: 1. The earlier input items. 2. Every item of each response's `output`, as it came back. 3. The new items, such as `function_call_output` results or the next user message. Keep earlier items byte for byte the same and append new ones. The [prompt cache](https://docs.privatemind.com/chat-completions.html#prompt-caching) then reads the shared start of the conversation, so a long history is not processed in full each time. Codex, the OpenAI SDKs and the Agents SDK work this way when they are not given a `previous_response_id`. If your client sends `item_reference` items, set it to send the items themselves, which most clients do when `store` is off. ## What is not supported | Feature | Behaviour | | --- | --- | | Stored responses and conversations | `400`. See [Conversations](https://docs.privatemind.com/responses-api.html#conversations) | | Hosted tools (`web_search`, `file_search`, `code_interpreter`, `mcp` and the like) | Not run; the model answers without them | | Custom tools | `400`; declare the tool as a function | | File and audio input (`input_file`, `input_audio`, `input_image` by `file_id`) | `400`. Images work by URL or data URL | | Vendor provider models served through another API, such as Claude through a provider card | `400` naming the dialect; use [chat completions](https://docs.privatemind.com/chat-completions.html) for those | | Responses lines in a [batch](https://docs.privatemind.com/batch.html) | Not accepted: a batch runs `/v1/chat/completions` or `/v1/embeddings` | Only `POST /v1/responses` exists. These paths return `404`: - `GET /v1/responses/{id}` and `DELETE /v1/responses/{id}` - `POST /v1/responses/{id}/cancel` - `GET /v1/responses/{id}/input_items` - `POST /v1/responses/input_tokens` - `POST /v1/responses/compact` ## Where next - [OpenAI SDK](https://docs.privatemind.com/openai-sdk.html#responses-api) for the Responses API from Python, TypeScript and the Agents SDK. - [Coding agents](https://docs.privatemind.com/coding-agents.html#codex-cli) to point Codex CLI at PrivateMind. - [Tool use](https://docs.privatemind.com/tool-use.html#responses-api) for a tool loop. - [Streaming](https://docs.privatemind.com/streaming.html#responses-api) for the event stream next to the other APIs. - [Errors](https://docs.privatemind.com/errors.html#responses-api) for the error shape and status codes.