Responses reference

Purpose and Scope

The Responses API is the primary model interaction surface exposed by this SDK, and this page is a focused reference for the client.responses namespace. Use it when you need to create or retrieve model responses, delete or cancel stored response objects, compact response context, count input tokens before sending work, or understand how the generated TypeScript entrypoints are organized. In OpenAI platform terminology, Responses is the newer unified primitive for text, multimodal input, tool use, and agent-like loops; in this SDK, that concept appears as a generated resource namespace with typed request and response shapes.

Sources: api.md, src/resources/responses/index.ts, tests/api-resources/responses/responses.test.ts, tests/api-resources/responses/input-tokens.test.ts

This page intentionally treats the Responses namespace as an SDK reference rather than a conceptual guide. It focuses on public entrypoints that appear in the repository evidence: Responses, InputItems, InputTokens, WebSocket option types, the tested methods on client.responses, and the token-counting subresource. If you are deciding whether to use Responses or Chat Completions, start with the conceptual Responses page first; if you already know you are calling client.responses, this page helps map the public methods, options, return helpers, and test-backed behavior to code.

Relevant Source Files

• api.md — generated API reference for the SDK, used as the top-level reference surface for method and type discovery.
• src/resources/responses/index.ts — package barrel for the Responses resource family; it re-exports response resources, input item resources, input token resources, and WebSocket option types.
• tests/api-resources/responses/responses.test.ts — generated tests that exercise client.responses.create, retrieve, delete, cancel, and compact, including response-wrapper helpers and selected request parameters.
• tests/api-resources/responses/input-tokens.test.ts — generated tests for client.responses.inputTokens.count, including token-count request parameters, tool options, reasoning options, text options, and request-option propagation.

The source layout shows that Responses is not a single flat method. The barrel in src/resources/responses/index.ts re-exports the main Responses class, the InputItems subresource, the InputTokens subresource, and WebSocket-related option types. That means developers should expect both direct methods such as client.responses.create(...) and nested resource methods such as client.responses.inputTokens.count(...). The generated API documentation in api.md is the broad reference surface, while the tests provide executable signals that the public client methods return SDK response promises with raw-response accessors.

Sources: api.md, src/resources/responses/index.ts

Resource Model and Exported Components

At the module boundary, the Responses family is exported from src/resources/responses/index.ts. The file exports InputItems with ResponseItemList and InputItemListParams, InputTokens with InputTokenCountResponse and InputTokenCountParams, Responses, ResponsesWSClientOptions, and ResponsesWSReconnectOptions. Those names are useful when writing TypeScript code that needs to annotate helper functions, wrap the SDK, or expose a narrower application-specific API. The export names also clarify the shape of the namespace: response creation and lifecycle live on Responses, replayable input items have their own resource, token accounting has a dedicated resource, and WebSocket mode has separate client and reconnect options.

Sources: src/resources/responses/index.ts

The tests instantiate OpenAI and then access client.responses, which is the public object most users call directly. Each tested request produces an SDK promise that can be awaited for parsed data, converted to a raw Response with .asResponse(), or resolved with both parsed data and the raw HTTP response using .withResponse(). That wrapper behavior is important for production integrations because it lets ordinary application code consume typed response objects while diagnostics, middleware, or migration tooling can still inspect transport-level status, headers, and response metadata when needed.

Sources: tests/api-resources/responses/responses.test.ts, tests/api-resources/responses/input-tokens.test.ts

Method Reference

The direct lifecycle methods are the core reference surface. create starts a new response and, in the generated test, returns an object that includes output_text as a string convenience field. retrieve accepts a response identifier and supports additional parameters that affect what is returned, including include for expandable data such as file search call results, include_obfuscation, starting_after, and stream. delete and cancel both operate by response ID and participate in the same SDK response-promise contract. The tests do not treat these as browser Response objects after parsing; the parsed data is distinct from the raw transport response.

Sources: tests/api-resources/responses/responses.test.ts

The compact method is useful when an application needs to compress or reduce response context while preserving enough state for continued work. The generated test shows model as the required field in the minimal call. The optional test case includes input, instructions, previous_response_id, prompt_cache_key, prompt_cache_retention, and service_tier, which places compaction in the same family of stateful continuation and caching concerns as normal response creation. Treat the method as a model-scoped operation: choose the model first, then provide the input and continuation hints that define the context being compacted.

Sources: tests/api-resources/responses/responses.test.ts

Input Items and Token Counting

The Responses barrel exports an InputItems subresource and its associated ResponseItemList and InputItemListParams types. Even though the supplied tests focus on the top-level response lifecycle and token counting, the export itself is an important reference signal: response output can become future input, and the SDK exposes a typed resource for listing or working with those input items. In multi-turn systems, this distinction matters because replayable input is not always equivalent to visible assistant text; reasoning items, tool calls, and other response items may need to be preserved in the order the API returns them.

Sources: src/resources/responses/index.ts

The token-counting subresource is exposed as client.responses.inputTokens.count(...). The generated test shows that the method can be called without arguments, and it can also accept a rich parameter object matching many create-like concerns: conversation, input, instructions, model, parallel_tool_calls, personality, previous_response_id, reasoning, text, tool_choice, tools, and truncation. This makes the method useful before an expensive or latency-sensitive request, because it can estimate the token load of the same ingredients that would influence a real response.

Sources: tests/api-resources/responses/input-tokens.test.ts

The tested token-count payload also demonstrates how tool and reasoning configuration are represented in generated request types. A function tool includes name, parameters, strict, type, defer_loading, and description. Reasoning configuration includes context, effort, generate_summary, and summary. Text configuration includes a format object, such as { type: 'text' }, and verbosity. These fields should be treated as typed SDK request properties rather than ad hoc JSON: when writing reusable wrappers, annotate against the exported InputTokenCountParams type so that changes in the generated OpenAPI surface are caught by TypeScript.

Sources: src/resources/responses/index.ts, tests/api-resources/responses/input-tokens.test.ts

Streaming and WebSocket Types

Streaming Responses are conceptually event streams: a request can produce lifecycle events such as creation, output text deltas, tool-call updates, and completion. In this SDK reference surface, streaming appears in two ways. First, retrieve is tested with a stream parameter, showing that streaming-related options can participate in response retrieval calls. Second, the Responses barrel exports ResponsesWSClientOptions and ResponsesWSReconnectOptions, which identify a WebSocket-mode surface for clients that need persistent bidirectional response sessions rather than one-shot HTTP requests.

Sources: src/resources/responses/index.ts, tests/api-resources/responses/responses.test.ts

For normal HTTP streaming, applications generally set a streaming option on the relevant create-style request and then iterate typed events. For WebSocket mode, applications should look for the generated WebSocket client options exported from the Responses resource family and configure reconnection behavior deliberately. The distinction matters operationally: HTTP streaming is a response delivery mode for a single request, while WebSocket mode is a longer-lived transport where reconnect behavior and client lifecycle become part of application design. The exported option types provide TypeScript names to anchor that configuration in wrappers or framework adapters.

Sources: src/resources/responses/index.ts

Request Options, Raw Responses, and Error Signals

The generated tests repeatedly exercise three ways of observing a request. Awaiting the SDK promise yields parsed data. Calling .asResponse() yields the raw platform Response. Calling .withResponse() yields an object whose data is the parsed result and whose response is the raw response. The tests assert that parsed data is not itself a raw Response, and that .withResponse().data is the same parsed value returned by awaiting the promise. This is the standard pattern to use when your application needs both typed SDK output and transport information.

Sources: tests/api-resources/responses/responses.test.ts, tests/api-resources/responses/input-tokens.test.ts

Request options are passed separately from method parameters. The tests prove this by sending a request option with path: '/_stainless_unknown_path', which causes OpenAI.NotFoundError. That pattern appears for both client.responses.retrieve(...) and client.responses.inputTokens.count(...), so it is not limited to one method. In real code, request options are where you should put per-call overrides supported by the SDK transport layer, while API parameters such as include, instructions, tools, or reasoning belong in the method parameter object.

Sources: tests/api-resources/responses/responses.test.ts, tests/api-resources/responses/input-tokens.test.ts

Example Patterns

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});
 
const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions: 'Be concise and cite assumptions.',
  input: 'Summarize the tradeoffs of server-side rendering.',
});
 
console.log(response.output_text);

For a simple create call, the most important result field in the generated test is output_text, which the SDK exposes as a string on the parsed response. That convenience field is useful for ordinary text-generation flows where the application does not need to inspect every output item. More advanced applications should still keep the full parsed response object, because response items can include tool calls, reasoning-related data, and other structured output that may be needed for a later turn, for audit logging, or for UI rendering beyond plain text.

Sources: tests/api-resources/responses/responses.test.ts

const tokenEstimate = await client.responses.inputTokens.count({
  model: 'gpt-5.5',
  input: 'Draft a release note for the new SDK wrapper.',
  instructions: 'Use a professional tone.',
  tool_choice: 'none',
  truncation: 'auto',
});

Use token counting before sending high-volume requests, before choosing whether to truncate context, or before deciding which tool configuration to include. The tested parameter object shows that counting can incorporate the same categories that influence an actual response: model, instructions, prior response linkage, reasoning behavior, text formatting, tools, and truncation. A practical wrapper can therefore compute the count from the same request builder used for create, reducing drift between estimation and execution.

Sources: tests/api-resources/responses/input-tokens.test.ts

Next Steps

When implementing a new Responses integration, start with client.responses.create and inspect output_text for the simplest text path. Add previous_response_id or input item handling when the application becomes multi-turn. Use client.responses.inputTokens.count before large requests, tool-heavy requests, or requests that must fit within a strict budget. Reach for .withResponse() when you need parsed data and HTTP metadata together, and use .asResponse() only when raw transport details are the primary concern. For streaming or persistent interactive sessions, follow the WebSocket option types exported from the Responses resource family.

Related pages: responses-api, streaming-events, conversation-state, structured-outputs, tools-approvals