Responses WebSocket API

GET /v1/responses

Handshake

Upgrade with a WebSocket client at placeholder URL wss://gateway.example.com/v1/responses, sending Authorization: Bearer YOUR_API_KEY. There is no HTTP JSON body. The library supplies Upgrade, Connection, Sec-WebSocket-Key, and version headers. Success is HTTP 101; failures may be 400 / 401 / 403 / 429 / 5xx or a proxy response. The first create event supplies the model, and channel selection follows the handshake. Each create runs request authentication and rate-limit checks again. A compatible channel with ResponsesWebSocketEnabled is required. This GET is not resource retrieval; use GET with an ID for plugin tasks.

Client messages

Field / event	Meaning
type = response.create	Create a turn; common fields go at the top level
model	Request model; cannot change after the upstream connection is established
input	New input; the example sends complete explicit history
instructions / tools / include	Common Responses fields, subject to model and channel preservation
previous_response_id	Upstream continuation state; no promise of reconnect or cross-channel recovery
store	Upstream option, not a retention policy
event_id	Client event identifier; gateway errors may echo it, ordinary upstream events need not
stream_id	Correlation field; the gateway still permits only one active generation, not multiplexing
generate	Forwardable warmup extension; outside the example and requiring upstream verification
response.cancel	Control an active generation and wait for upstream outcome; not REST cancel

The parser also accepts a nested response object for create. The example consistently uses the top-level form. stream, background, and stream_options are not forwarded as transport settings; the connection already uses events. See create response for common fields, without assuming all HTTP extensions are equivalent. These are separate illustrative messages; the cancellation ID must come from an active response:

{"type":"response.create","model":"YOUR_MODEL_ID","input":[{"role":"user","content":"Hello"}],"store":false}

{"type":"response.cancel","event_id":"cancel_1","response_id":"resp_CURRENT"}

Server messages

Event	Client handling
response.created	Read response.id and associate the turn
response.output_item.added / done	Output-item lifecycle; preserve complete result structures
response.output_text.delta	Merge delta by item_id, output_index, content_index; response_id may be absent
response.output_text.done	One text part ended, not necessarily the entire turn
response.completed	Check response.id, status=completed, output, and content status
response.done	Terminal alias also recognized by the gateway; inspect status rather than trusting the name
response.failed / incomplete / cancelled / canceled	Unsuccessful terminal state, not a complete result
error	Gateway errors may include status, event_id, stream_id, response_id, error; upstream shapes vary

Deltas and final objects use Responses structures, not Chat choices or Realtime sessions. The example buffers results and rejects tools and refusals. A complete function loop still belongs in the application. See Responses streaming events for protocol context.

Limits and recovery

Overlapping create events may receive an error with status 409. A successful handshake does not guarantee future authorization, rate-limit admission, or continued channel availability. Active requests have bounded pending controls; cancellation can fail separately. Configuration or upstream connection changes can require reconnecting. Socket closure, missing terminal events, errors, and local deadlines do not indicate success. Official multiplexing, cached reconnect state, or a 60-minute lifetime are not gateway guarantees; deployments may impose shorter timeouts. Source: router/relay-router.go, controller/responses_websocket.go, relay/responses_websocket.go, checked at 30a6d88a4. Runnable example · Shared connection module 阅读中文

Getting started

Integration guides

Application guides

Multimodal guides

Retrieval and reranking

Production and troubleshooting

Additional protocols and tasks

API reference

Responses WebSocket API

Handshake

Client messages

Server messages

Limits and recovery

​Handshake

​Client messages

​Server messages

​Limits and recovery

Handshake

Client messages

Server messages

Limits and recovery