Assistants API

Purpose and Scope

The Assistants API is the older object model for building assistant-style workflows in the OpenAI TypeScript and JavaScript SDK. It is still represented under client.beta, but the generated SDK marks assistant methods and types as deprecated, and the current OpenAI documentation recommends new integrations use the Responses API instead. This page is therefore most useful for maintaining existing Assistants integrations, understanding how the SDK maps assistant concepts to generated resource classes, and planning a migration from assistants, threads, runs, and run steps toward Responses, Conversations, and output items.

Sources: src/resources/beta/assistants.ts, src/resources/beta/threads/index.ts

In this model, an assistant is a persistent API object that stores model configuration, instructions, tool declarations, tool resources, metadata, and naming information. A thread stores the conversation context. A run applies an assistant to a thread and produces messages, tool calls, and step-level execution detail. The SDK exposes those concepts as nested resources so application code can create or retrieve configuration objects, append conversation state, start execution, and inspect progress without constructing HTTP paths manually.

Sources: src/resources/beta/assistants.ts, src/resources/beta/threads/index.ts

Relevant Source Files

• api.md - Generated API reference surface for the package; use it as the broad reference companion for complete generated signatures and type names.
• src/resources/beta/assistants.ts - Generated Assistants resource implementation, including CRUD methods, beta headers, bearer authentication metadata, pagination type, and the deprecated Assistant type.
• src/resources/beta/threads/index.ts - Barrel export for beta thread-related resources and types, including messages, runs, thread objects, run streaming and polling parameter types, and assistant-specific tool choice and response format types.
• tests/api-resources/beta/assistants.test.ts - Generated resource tests showing the public client.beta.assistants call shape, request option handling, response helpers, and create/list/delete coverage.
• tests/api-resources/beta/threads/runs/runs.test.ts - Generated resource tests showing the public client.beta.threads.runs call shape, required identifiers, optional run parameters, streaming flags, tool choices, truncation strategy, and response helper behavior.

System-to-Code Mapping

The top-level entry point for assistant configuration is client.beta.assistants. In the generated resource class, create, retrieve, update, list, and delete call /assistants endpoints and add the OpenAI-Beta: assistants=v2 header on every request. Each operation also declares bearer authentication through the generated request metadata. list returns a cursor-paginated page type, while the other methods return APIPromise values that can be awaited directly or inspected through SDK response helpers.

Sources: src/resources/beta/assistants.ts, tests/api-resources/beta/assistants.test.ts

The thread family is organized below client.beta.threads. The beta threads index re-exports message types such as Message, MessageContent, annotations, deltas, and message parameter types; run types such as Run, RunStatus, RequiredActionFunctionToolCall, and submit-tool-output parameter variants; and thread types such as Thread, ThreadCreateParams, ThreadCreateAndRunParams, and streaming or polling variants. That export design lets TypeScript users import the generated contracts from the SDK while still calling the ergonomic nested client methods.

Sources: src/resources/beta/threads/index.ts

Conceptually, Assistants maps to the older API vocabulary while newer OpenAI platform documentation maps the same workflow ideas to newer primitives. Assistants become prompt-like configuration, threads become conversations, runs become responses, and run steps become generalized items. The SDK preserves the Assistants surface for compatibility, but migration work should identify where application state depends on persistent assistant objects, thread IDs, run status polling, tool-output submission, or run-step inspection so those responsibilities can be shifted deliberately.

Sources: api.md, src/resources/beta/assistants.ts, src/resources/beta/threads/index.ts

Execution Flow

A typical existing Assistants workflow starts by creating or retrieving an assistant. The minimal create shape only requires a model, as shown by the generated resource test calling client.beta.assistants.create({ model: 'gpt-4o' }). Optional assistant fields include description, instructions, metadata, name, reasoning_effort, response_format, temperature, top_p, tools, and tool_resources. Tool resources can attach file IDs for code_interpreter and vector store information for file_search, which matches the API concept that built-in tools need explicit access to uploaded files or vector stores.

Sources: tests/api-resources/beta/assistants.test.ts

After an assistant exists, application code creates or reuses a thread and starts a run for that thread. The generated runs tests show the required call shape as client.beta.threads.runs.create('thread_id', { assistant_id: 'assistant_id' }). Optional run creation parameters can override or extend assistant behavior for that execution, including additional_instructions, additional_messages, instructions, model, token limits, parallel_tool_calls, response_format, tools, tool_choice, temperature, top_p, and truncation_strategy. This makes a run the execution boundary where persistent assistant defaults meet request-time conversation and orchestration choices.

Sources: tests/api-resources/beta/threads/runs/runs.test.ts

The same runs test coverage shows that generated SDK promises expose multiple response access patterns. A caller can await the promise for parsed data, call asResponse() to inspect the raw Response, or call withResponse() to receive both parsed data and the raw response. That behavior is useful when maintaining Assistants applications that need SDK-level type safety but also need headers, status codes, or low-level response information for logging, debugging, or compatibility checks during migration.

Sources: tests/api-resources/beta/assistants.test.ts, tests/api-resources/beta/threads/runs/runs.test.ts

API Components

Component	Public SDK surface	Role	Notes
Assistant configuration	client.beta.assistants.create, retrieve, update, list, delete	Stores model, instructions, tools, resources, and metadata	Methods are generated with OpenAI-Beta: assistants=v2 and are marked deprecated.
Thread resources	client.beta.threads plus exported Thread* types	Stores conversation context for assistant runs	The index exports create, update, create-and-run, streaming, and polling parameter types.
Messages	client.beta.threads.messages plus exported message and delta types	Represents user and assistant conversation content	Exports include text, image, annotations, file citation, refusal, and delta content types.
Runs	client.beta.threads.runs plus exported Run* types	Executes an assistant against a thread	Tests show create, retrieve, update, list, request options, and rich creation options.
Tool interaction	RunSubmitToolOutputs* and RequiredActionFunctionToolCall types	Supports function/tool output loops	Use when a run requires application-provided tool results before continuing.

Implementation Details

The generated assistant implementation is intentionally thin. It does not contain hand-written orchestration logic; instead, it translates typed method calls into REST requests using the shared client, generated pagination, path interpolation, and request option plumbing. That matters for maintainers because behavior such as retries, timeouts, logging, and custom fetch integration comes from the core client, while the Assistants resource is responsible for endpoint paths, beta headers, request body types, response types, and authentication metadata.

Sources: src/resources/beta/assistants.ts

The generated tests are a practical compatibility signal for public method shapes. The assistants tests validate minimal and optional create calls, retrieval, update, listing, delete, pagination/query options such as after, before, limit, and order, and request-option forwarding through an intentionally invalid path. The runs tests similarly validate required thread and run identifiers, metadata updates, run listing, and a broad run creation body. When upgrading the SDK, these tests indicate which call shapes are expected to remain type-safe and operational for legacy Assistants users.

Sources: tests/api-resources/beta/assistants.test.ts, tests/api-resources/beta/threads/runs/runs.test.ts

Migration Guidance

For new work, prefer the Responses API. For existing Assistants applications, migrate by separating configuration, conversation state, execution, and tool loops. Assistant fields such as model, instructions, tools, and tool_resources identify the configuration to reproduce. Thread messages identify conversation history. Runs identify execution-time overrides and status handling. Run steps and tool-output submission identify orchestration points that may need explicit handling in Responses. Treat this as a model change rather than a mechanical rename, because the newer APIs use input and output items more directly.

Sources: api.md, src/resources/beta/threads/index.ts, tests/api-resources/beta/threads/runs/runs.test.ts

Next, inventory your code for client.beta.assistants, client.beta.threads, and client.beta.threads.runs calls. Keep the Assistants API reference nearby for exact generated names, then compare each persistent object and run-time option with its Responses or Conversations equivalent. If your integration uses built-in tools such as file search or code interpreter, also review file, vector store, and tool-output flows before migration so that file IDs, vector store IDs, and function-call results continue to be supplied at the correct stage of execution.

Sources: api.md, tests/api-resources/beta/assistants.test.ts, tests/api-resources/beta/threads/runs/runs.test.ts