Responses and Vector Stores

The newest agentic clients no longer speak plain chat completions: they speak the OpenAI Responses API, a stateful protocol where the server stores each turn and the client chains on it. This server serves that protocol at POST /v1/responses, alongside the file surface and vector stores that ground it, so a tool built for it (Codex-class clients configure wire_api = "responses" and a base URL) runs here unmodified, with every turn generated and stored locally.

1The response lifecycle#

A response is stored by default (store defaults to true) and becomes an address:

Chaining follows the upstream contract exactly, including its sharp edge: instructions are NOT inherited across previous_response_id, so a client that relies on per-turn instructions must send them each turn. Stored responses are per-key, like files and everything else here (Keys and Authentication).

2What a request can carry#

Input is a string or an item array, and the item vocabulary is served broadly:

• Messages with input_text, input_image (a data URL, an http or https URL, or an uploaded file_id), and input_file (a file_id or inline file_data); document text is folded into the model's context.
• Function tools, flat, with tool_choice; function_call and function_call_output items round-trip the loop.
• Structured output through text.format: json_object and json_schema are enforced with grammar-constrained decoding, so the model cannot produce anything but the shape you declared.
• Reasoning: thinking models return real reasoning output items, reasoning items pass through on input, and usage carries a reasoning-token breakdown.

3Grounding: files into vector stores, retrieval through file_search#

The grounding loop is three calls and one tool:

1. POST /v1/files uploads the document (GET /v1/files/{id} reads its metadata back).
2. POST /v1/vector_stores creates a store; GET lists or retrieves; DELETE removes a store and everything indexed in it.
3. POST /v1/vector_stores/{id}/files attaches an uploaded file. The document is full-text searchable immediately and becomes semantically searchable when its embedding pass completes, so grounding works the moment the call returns and gets better seconds later.
4. Declare the file_search tool on the request, on POST /v1/responses or on POST /v1/chat/completions: both run it. The search executes server-side over your stores; there is deliberately no standalone store-query route, so retrieval always happens inside a generation, where the results land in context.

For retrieval you control call-by-call (hybrid tuning, filters, reranking, facets), the Search engine is the richer surface; vector stores are the compatibility path that makes existing OpenAI-style agents work as-is.

4Streaming#

Streaming responses follow the documented event scaffold with a monotonic sequence_number: response.created, response.in_progress, response.output_item.added, response.content_part.added, response.output_text.delta (repeated), response.output_text.done, response.content_part.done, response.output_item.done, response.completed. Clients that reconstruct state from events see the shape they were written against.

5Refused by name, never approximated#

Serving a stateful protocol approximately corrupts the caller's conversation, so what this version does not serve answers as a precise 400 naming the field: conversation objects (resend the transcript as input items), background execution, hosted tool types other than file_search, and item_reference. A client learns exactly what to change instead of debugging a silent misinterpretation.

6Stated plainly#

• wire_api = "responses" plus a base URL pointing here runs Responses-native tooling on local models: stateful turns, tools, structured output, reasoning, streaming.
• Files plus vector stores plus file_search give OpenAI-style grounding without a byte leaving this server; the Search engine remains the deeper retrieval surface when you want the knobs.
• Storage is per-key and deletable; chaining does not inherit instructions, by contract.
• Unsupported protocol corners are refused by name, so failures are actionable.