> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inputapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses WebSocket API

> Handshake, create fields, event correlation, and gateway limits.

`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](/en/api-reference/responses-retrieve) 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](/en/api-reference/responses) for common fields, without assuming all HTTP extensions are equivalent.

These are separate illustrative messages; the cancellation ID must come from an active response:

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

```json theme={null}
{"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](https://developers.openai.com/api/reference/resources/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](/en/guides/responses-websocket) · [Shared connection module](/en/guides/websocket)

[阅读中文](/zh/api-reference/responses-websocket)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.