API reference
The package root exports the supported public surface. Import protocol types from openresponses; transport-specific classes are also available from their modules when a lower-level import is useful.
Clients
| Symbol | Purpose |
|---|---|
OpenResponses |
Synchronous HTTP client with responses.create, responses.compact, and websocket(). |
AsyncOpenResponses |
Asynchronous counterpart; await response operations and use async for for streams. |
ClientConfig |
Validated base URL, authentication, timeout, headers, compatibility, and response-size settings. |
WebSocketConfig |
WebSocket open/close timeouts, ping settings, and maximum frame size. |
Clients own transports they create and close them. An injected httpx.Client or httpx.AsyncClient remains caller-owned.
HTTP resources
responses.create(request, *, extra_headers=None, timeout=None) accepts a CreateResponseRequest or a mapping and returns:
ResponseResourcefor strict JSON responses;OpenAICompatibleResponsewhenresponse_compatibility="openai-compatible"accepts a partial provider response;ResponseStreamorAsyncResponseStreamwhenstream=True.
responses.compact(request, *, extra_headers=None, timeout=None) returns CompactResource. The base URL is normalized and the SDK appends /responses and /responses/compact.
Types
Request and response models are generated from the pinned OpenAPI artifact and re-exported from the package root:
CreateResponseRequest,CompactResponseRequest,WebSocketResponseCreateRequest;ResponseResource,CompactResource,ResponseItem,InputItem;FunctionToolParam,ToolChoice,ResponseContentPart;Response*StreamingEvent,UnknownStreamingEvent, andWebSocketErrorEvent.
Use model_dump(mode="json", by_alias=True) to serialize Python models to the wire format. Unknown provider fields are preserved.
Streams and WebSockets
ResponseStream and AsyncResponseStream are closeable iterators. They expose final_response, response_id, and last_sequence_number.
WebSocketConnection and AsyncWebSocketConnection expose connect(), close(), and create(). A connection permits one in-flight turn; inspect turn.error, turn.final_response, and turn.response_id before starting the next turn.
SSEParser is exported for reusable incremental SSE framing. The high-level streams add content-type, event-model, sequence, and lifecycle validation.
OpenAI and MLflow integrations
Use response_compatibility="openai" with OpenAIRequest, OpenAICompactRequest, and OpenAIWebSocketRequest for the current OpenAI Responses API. This explicit mode preserves current OpenAI fields without changing strict OpenResponses validation.
MLflow support is optional through openresponses.integrations.MLflowOpenResponses and MLflowAsyncOpenResponses. Install openresponses-py[mlflow] to enable it. The wrapper traces JSON, compact, and streaming response calls; WebSocket turns remain available through the wrapped client's websocket() method.
Errors
All errors inherit from OpenResponsesError:
| Error | Typical condition |
|---|---|
BadRequestError |
HTTP 400 or invalid request semantics. |
AuthenticationError |
HTTP 401. |
PermissionDeniedError |
HTTP 403. |
NotFoundError |
HTTP 404. |
RateLimitError |
HTTP 429. |
ModelError |
Provider model_error response. |
InternalServerError |
Other 5xx responses. |
APIConnectionError / APITimeoutError |
Transport failure or timeout. |
APIResponseValidationError |
Successful response fails the pinned model. |
SSEProtocolError / WebSocketError |
Invalid stream or WebSocket protocol behavior. |
HTTP status errors retain the status, raw body, headers, request URL, and parsed provider error. No automatic retries are performed.
Version boundary
OPENRESPONSES_SPEC_VERSION reports the pinned protocol version, currently 2026-04-24. The client does not silently follow an unreleased upstream contract.