Responses API concepts
Purpose and Scope
The Responses API is the primary model interaction surface for new integrations built with the TypeScript and JavaScript SDK. It gives applications one place to send model input, receive output, stream incremental events, configure tools, and continue work across turns. The official platform guidance describes Responses as the newer primitive and recommends it for new projects, while this repository grounds that guidance in the client.responses resource, generated type exports, and tests that exercise how SDK promises, parsed response objects, and response items behave in user code.
Sources: src/resources/responses/index.ts, tests/api-resources/responses/responses.test.ts
A useful way to think about a response is as more than a text string. A response can include visible assistant text, structured output items, reasoning context, function calls, tool calls, and other records that may matter to the next request. The SDK still supports a convenient output_text property for the common case where an application just wants printable text, but the tests also demonstrate that lower-level output items can be carried forward as future input. That dual shape is central to Responses: simple enough for a first request, structured enough for agent-like workflows.
Sources: tests/api-resources/responses/responses.test.ts, tests/responsesItems.test.ts
Relevant Source Files
- api.md — Generated SDK API reference catalog for the Responses resource, request shapes, response shapes, and associated exported types.
- src/resources/responses/index.ts — Generated barrel module that exposes the Responses resource plus adjacent input item, input token, and WebSocket option exports.
- tests/api-resources/responses/responses.test.ts — Generated resource tests showing the public
client.responsesmethods, SDK response-wrapper behavior, request options, and selected request parameters. - tests/responsesItems.test.ts — Type-compatibility test showing how
ResponseOutputItemvalues,ResponseInputItemvalues, andtoResponseInputItems()participate in manual conversation history replay.
Core Primitives
The central primitive is client.responses.create(...), which starts model work and returns an SDK promise for a parsed response object. In the generated resource tests, awaiting that promise yields an SDK domain object rather than a Fetch API Response, and the parsed object has output_text as a string. The same promise also supports asResponse() for the raw transport response and withResponse() for paired parsed data and raw response metadata. That wrapper pattern lets application code stay ergonomic while preserving access to status, headers, and transport-level diagnostics when needed.
Sources: tests/api-resources/responses/responses.test.ts
Input can be a direct string or a structured collection of items. The response-item test creates a response with model: 'gpt-5.1' and input: 'You are a helpful assistant.', then builds a mixed history array containing a function_call_output item and the response’s own output items. This demonstrates the SDK’s model of conversation state: prior model output is not merely display text, and tool protocol records may need to remain in order. When manually managing state, applications should preserve compatible items instead of reducing history to assistant messages only.
Sources: tests/responsesItems.test.ts
The resource index shows that Responses includes adjacent subresources, not only a single create method. It exports InputItems, InputTokens, Responses, ResponsesWSClientOptions, and ResponsesWSReconnectOptions. Those names map to three common needs: inspecting or listing response input items, counting input tokens for budgeting, and configuring WebSocket-style response clients where the SDK supports persistent response transport. In other words, the generated module groups generation, item access, token accounting, and transport configuration under the broader Responses concept.
Sources: src/resources/responses/index.ts
Compact API Reference
| Surface | Source-level contract visible in this repository | Reader use |
|---|---|---|
client.responses.create(params) | Called with {} in generated tests and with { model: 'gpt-5.1', input: '...' } in item tests; awaited value is parsed data with output_text: string. | Start a response and read final text or structured output. |
client.responses.retrieve(responseID, params?, options?) | Called with response id resp_677efb5139a88190b512bc3fef8e535d; optional params include include, include_obfuscation, starting_after, and stream. | Fetch an existing response and request additional included data. |
client.responses.delete(responseID) | Tested with the same response id and standard SDK response-wrapper helpers. | Delete a stored response when the API permits it. |
client.responses.cancel(responseID) | Tested as a generated resource method returning parsed data plus optional raw response access. | Stop an in-progress response. |
client.responses.compact(params) | Required param shown as { model: 'gpt-5.4' }; optional params shown include input, instructions, previous_response_id, prompt_cache_key, prompt_cache_retention, and service_tier. | Compact or prepare context while controlling model, instructions, cache, and service tier. |
toResponseInputItems(history) | Imported from openai/lib/responses/ResponseInputItems in the item compatibility test and used on mixed `ResponseInputItem | ResponseOutputItem` history. |
InputItems / InputTokens | Exported from src/resources/responses/index.ts with response item list and token count types. | Navigate item access and token counting surfaces. |
ResponsesWSClientOptions / ResponsesWSReconnectOptions | Exported WebSocket option types from the Responses index. | Configure persistent or reconnecting response transports where used. |
Sources: src/resources/responses/index.ts, tests/api-resources/responses/responses.test.ts, tests/responsesItems.test.ts
Execution Flow
A basic non-streaming flow starts by constructing an OpenAI client and calling client.responses.create with a model and input. The SDK returns a promise-like object with multiple consumption modes. If the caller awaits it directly, it receives the parsed response object. If the caller needs HTTP details, it can call asResponse() to inspect the raw response, or withResponse() to receive both parsed data and transport response together. The generated tests assert that these forms refer to the same parsed data object and raw response object, which is useful when instrumenting production requests.
Sources: tests/api-resources/responses/responses.test.ts
A streaming flow keeps the same conceptual endpoint but changes how output is consumed. Official platform docs describe HTTP streaming with stream=true as server-sent semantic events such as response.created, output text deltas, and response.completed. The repository evidence for this page does not enumerate every event type, but it does show stream as a retrieve parameter and exports WebSocket response option types from the Responses module. The practical distinction is that non-streaming code waits for the whole parsed object, while streaming code processes typed lifecycle and delta events before final completion.
Sources: src/resources/responses/index.ts, tests/api-resources/responses/responses.test.ts
A multi-turn flow can be stateful or manual. For simple continuation, platform guidance and repository examples use a previous response identifier so the server can continue from earlier context. For manual state, the SDK test shows a stricter pattern: combine prior output items with tool outputs, filter out item variants that cannot be replayed, and normalize mixed history with toResponseInputItems(). The test-defined type guard excludes computer_call_output and additional_tools, which signals that developers should not blindly resend every output item as input without considering compatibility.
Sources: tests/responsesItems.test.ts
Tools, Items, and Conversation State
Responses is designed for workflows where the model may call tools during a single request. Official docs describe built-in tools such as web search, file search, computer use, code interpreter, and remote MCP servers, plus custom functions. The repository test’s function_call_output item is a small but important example of that protocol: tool execution results are represented as structured items with a call_id and output, not as ordinary user text. Preserving those records helps the next request maintain the causal relationship between a model’s tool call and the application’s result.
Sources: tests/responsesItems.test.ts
The output_text convenience property should therefore be treated as a view over the response, not as the entire response state. It is excellent for printing, logging user-visible answers, or returning a plain result from a simple helper. It is not sufficient as the only stored state for agentic flows, because reasoning traces, tool call records, and other compatible output items may be required to continue correctly. The SDK’s exported response item types and normalization helper make that distinction visible to TypeScript users before they encounter runtime protocol errors.
Sources: tests/api-resources/responses/responses.test.ts, tests/responsesItems.test.ts
Testing Signals and Implementation Details
The generated resource tests establish a consistent SDK method pattern for Responses lifecycle operations. create, retrieve, delete, cancel, and compact all return SDK promises that can be consumed as parsed data, raw transport response, or both. The retrieve test also deliberately passes request options with an unknown path and expects OpenAI.NotFoundError, showing that endpoint parameters and SDK request options are forwarded through the resource layer. This is a useful troubleshooting signal: if a call fails, inspect both the semantic request fields and the transport options supplied at the method boundary.
Sources: tests/api-resources/responses/responses.test.ts
The item compatibility test is a type-level safety signal rather than a live API assertion. It imports ResponseInputItem and ResponseOutputItem from the generated Responses types and checks that realistic history construction type-checks. That matters because the generated OpenAPI surface can evolve as new output item variants are added. By keeping this test close to the SDK, maintainers verify that the public type model still supports replaying valid response output as later response input while forcing incompatible variants to be handled deliberately.
Sources: tests/responsesItems.test.ts
Next Steps
Use this page as the conceptual map before moving to narrower implementation topics. Read the Responses reference for method-by-method details from the generated API catalog, the conversation state page for previous_response_id and manual item replay patterns, and the streaming events page for event iteration and delta handling. If your workflow uses tools, continue to tools and approvals, MCP integrations, Code Interpreter, file search, and computer use. Those pages build on the same contract described here: Responses accepts model input plus tool configuration, returns structured output items, and exposes both convenient text and typed protocol records.
Sources: api.md, src/resources/responses/index.ts, tests/responsesItems.test.ts