# OpenAI Responses API — complete reference

Status: DOCUMENTED + LIVE_VERIFIED (all HTTP endpoints exercised 2026-09-18 with gpt-5.4-nano / gpt-4.1-nano; WebSocket mode DOCUMENTED/UNVERIFIED). Machine-readable twins: generated/fragments/endpoints/openai-core.json, generated/fragments/parameters/openai-responses.json, generated/fragments/objects/openai-responses-objects.json, generated/fragments/streaming-events/openai-responses*.json.

Sources

• https://developers.openai.com/api/reference/resources/responses/methods/create (+ retrieve, delete, cancel, compact, input_items/list, input_tokens/count, streaming-events, websocket-events)
• https://developers.openai.com/api/docs/guides/text · conversation-state · background · compaction · token-counting · websocket-mode · streaming-responses · migrate-to-responses
• OpenAPI spec sources/openai/openapi/openapi-master.yaml (schemas CreateResponse, Response, ResponseStreamEvent, ResponsesClientEvent, ResponsesServerEvent, CompactResponseMethodPublicBody, TokenCountsBody)
• Live probes: tmp-live/openai-core/*.json (sanitized), log reports/live-requests.jsonl

Last verified: 2026-09-18

# 1. Endpoints

Auth: Authorization: Bearer $OPENAI_API_KEY (+ optional OpenAI-Organization, OpenAI-Project). Observed response headers: x-request-id, openai-processing-ms, openai-version: 2020-10-01, x-ratelimit-{limit,remaining,reset}-{requests,tokens} (account-specific values, not documented limits).

SDK surface (verified installed): Python openai==3.16.2 → client.responses.{create,retrieve,delete,cancel,compact,stream,parse}, client.responses.input_items.list, client.responses.input_tokens.count, client.responses.connect() (WS). Node openai@7.18.0 → client.responses.{create,retrieve,delete,cancel,compact,stream,parse}, client.responses.inputItems.list, client.responses.inputTokens.count, ResponsesWS.

# 2. Request body — POST /v1/responses

Notation: a.b nested object, x[] array element, x[](t) union member discriminated by type (or role). Full list (511 rows incl. every input item type) in generated/fragments/parameters/openai-responses.json.

# 2.1 Top-level parameters

# 2.2 input items (union Item)

Message content parts: input_text{text}, input_image{image_url \| file_id, detail: low\|high\|auto\|original}, input_file{file_id \| file_url \| file_data+filename, detail: auto\|low\|high}, input_audio{input_audio:{data,format:mp3\|wav}}; assistant messages use output_text{text, annotations[], logprobs[]} / refusal{refusal}. Every part accepts prompt_cache_breakpoint: {mode:"explicit"} (GPT-5.6+). Details: docs/openai/multimodal-input.md.

Live check (p8): mixed forms in one request — {type:message, role:developer, content:"…"}, {type:message, role:user, content:[input_text]}, {type:message, role:assistant, phase:"commentary", content:"…"} and bare {role:user, content:"…"} → 200.

# 3. The Response object

Top-level fields (spec Response + live). * = returned live but absent from the OpenAPI Response schema (LIVE_DISCOVERED).

Live example (a, trimmed, ids shortened):

{"id":"resp_0d1a…","object":"response","created_at":1789782269,"status":"completed","background":false,
 "billing":{"payer":"developer"},"completed_at":1789782270,"error":null,"incomplete_details":null,
 "instructions":null,"max_output_tokens":32,"model":"gpt-5.4-nano-2026-03-17","moderation":null,
 "output":[{"id":"msg_0d1a…","type":"message","status":"completed","role":"assistant","phase":"final_answer",
           "content":[{"type":"output_text","annotations":[],"logprobs":[],"text":"OK."}]}],
 "parallel_tool_calls":true,"previous_response_id":null,"prompt_cache_key":null,"prompt_cache_retention":"24h",
 "reasoning":{"context":"current_turn","effort":"none","mode":"standard","summary":null},"safety_identifier":null,
 "service_tier":"default","store":true,"temperature":1.0,"text":{"format":{"type":"text"},"verbosity":"medium"},
 "tool_choice":"auto","tool_usage":{"image_gen":{"input_tokens":0,"output_tokens":0,"total_tokens":0,"…":"…"},"web_search":{"num_requests":0}},
 "tools":[],"top_logprobs":0,"top_p":0.98,"truncation":"disabled",
 "usage":{"input_tokens":10,"input_tokens_details":{"cache_write_tokens":0,"cached_tokens":0},"output_tokens":6,
          "output_tokens_details":{"reasoning_tokens":0},"total_tokens":16},"user":null,"metadata":{}}

# 4. Conversation-state strategies

Rules that bite:

• previous_response_id xor conversation (400 mutually_exclusive_parameters).
• Reasoning models: keep every item between the last user message and your function_call_output untouched; reasoning.context: all_turns (GPT-5.6) re-renders earlier reasoning only when the request has access to it.
• instructions are per-request; to change the system prompt mid-chain just send a new instructions.

# 5. Background mode

• background:true → HTTP 200 immediately with status:"queued", output:[], usage:null. Poll GET /v1/responses/{id} while queued|in_progress.
• Cancel: POST …/cancel → Response with status:"cancelled" (usage zeros); repeated cancel on a cancelled response returns the same object (idempotent, documented + observed). Cancelling an already completed response fails: HTTP 400 invalid_request_error "Cannot cancel a completed response." (observed in examples/openai/responses/background.ts, first run) — so "idempotent" only holds for in-flight/cancelled states. Cancelling a foreground response = drop the connection.
• Streaming a background response: create with background:true, stream:true; keep the last sequence_number; resume with GET /v1/responses/{id}?stream=true&starting_after=N (live: after seq 1 the server replayed response.in_progress(2)…response.completed(9)). Only possible if created with stream:true.
• Background streams emit an extra response.queued event (seq 1) after response.created.
• Retention: ZDR projects run background with store=false, data kept ~10 min for polling; Modified-Abuse-Monitoring projects keep background responses only with explicit store=true.
• Documented latency caveat: time-to-first-token is higher than synchronous.

# 6. Compaction

Server-side: context_management: [{"type":"compaction","compact_threshold": N}] (N ≥ 1000 tokens). When rendered context crosses N the server compacts mid-response, emits a compaction output item (and response.compaction.compacting SSE event) and continues. Continue by appending outputs (stateless) or via previous_response_id (never prune manually in that mode). Latency tip: in stateless mode you may drop items before the latest compaction item.

Standalone: POST /v1/responses/compact {model, input | previous_response_id, instructions?, tools?, prompt_cache_*?, service_tier?} →

{"id":"resp_0ed5…","object":"response.compaction","created_at":1789782277,
 "output":[{"id":"msg_…","type":"message","status":"completed","role":"user","content":[{"type":"input_text","text":"Reply with OK."}]},
           {"id":"msg_…","type":"message","role":"user","content":[{"type":"input_text","text":"Reply with OK again."}]},
           {"id":"cmp_…","type":"compaction","encrypted_content":"gAAAAABq…"}],
 "usage":{"input_tokens":119,"input_tokens_details":{"cache_write_tokens":0,"cached_tokens":0},"output_tokens":…,"output_tokens_details":{"reasoning_tokens":…},"total_tokens":…}}

Observations: the assistant message was folded into the compaction item while user messages were retained; previous_response_id alone (no input) also works (i2). Pass the returned output as-is as the next input (do not prune). Compaction can lower prompt-cache reuse (prompt_cache_diagnostics.reason = context_compacted on GPT-5.6+).

# 7. Token counting — POST /v1/responses/input_tokens

Body = the create body minus generation settings (model, input, instructions, tools, tool_choice, text, reasoning, previous_response_id, conversation, truncation, parallel_tool_calls, personality). Response {object:"response.input_tokens", input_tokens}. Live: "Reply with OK." → 10 (equals the real call's usage.input_tokens); with instructions + 1×1 image + one function tool → 49. Free; ?beta=true variant works. Counts include role/boundary formatting tokens; output-side max_output_tokens also covers non-visible formatting tokens.

# 8. WebSocket mode (wss://api.openai.com/v1/responses) — DOCUMENTED

• Client events: response.create (same body as HTTP create + stream_id; stream implicit, background unsupported, generate:false = warm-up), response.steer (previous_response_id, input of messages/function outputs — queues mid-turn steering), beta response.inject (response_id, input).
• Server events: the 59 SSE events + stream_id echo, plus response.steer.accepted|pending|failed, beta response.inject.created|failed, and error (previous_response_not_found, invalid_stream_id, websocket_stream_limit_reached, websocket_connection_limit_reached).
• stream_id = ordered lane (FIFO within a lane, concurrent across lanes); previous_response_id = lineage → fork a lane from another lane's response. Limits: 16 in-flight responses, 32 named lanes, 60-minute connections. Reconnect = new cache; continue with previous_response_id only if store=true.
• SDKs: Python client.responses.connect() (pip install "openai[realtime]"), Node ResponsesWS.

# 9. Retrieve / list / delete semantics

• GET /v1/responses/{id} returns the same object as create (status may have progressed). include[] works on retrieve (live: message.output_text.logprobs).
• GET …/input_items on a previous_response_id child returned (desc): new user message, prior assistant message (phase:"final_answer"), prior user message — i.e. the rendered context, not only the literal input.
• DELETE is allowed on any stored response including chain parents (child kept its copy of the context). After delete → 404 Response with id '…' not found.
• Responses attached to a conversation persist through the conversation (no 30-day TTL).

# 10. Errors observed (all type: invalid_request_error)

# 11. Live verification log (2026-09-18, total ≈ $0.0015)