OpenAI Assistants API v2

Status: Production Ready (⚠️ Deprecated - Sunset August 26, 2026) Package: [email protected] Last Updated: 2026-01-21 v1 Deprecated: December 18, 2024 v2 Sunset: August 26, 2026 (migrate to Responses API)

⚠️ Deprecation Notice

OpenAI is deprecating Assistants API in favor of Responses API.

Timeline: v1 deprecated Dec 18, 2024 | v2 sunset August 26, 2026

Use this skill if: Maintaining legacy apps or migrating existing code (12-18 month window) Don't use if: Starting new projects (use openai-responses skill instead)

Migration: See references/migration-to-responses.md

Quick Start

npm install [email protected]

import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// 1. Create assistant
const assistant = await openai.beta.assistants.create({
  name: "Math Tutor",
  instructions: "You are a math tutor. Use code interpreter for calculations.",
  tools: [{ type: "code_interpreter" }],
  model: "gpt-5",
});

// 2. Create thread
const thread = await openai.beta.threads.create();

// 3. Add message
await openai.beta.threads.messages.create(thread.id, {
  role: "user",
  content: "Solve: 3x + 11 = 14",
});

// 4. Run assistant
const run = await openai.beta.threads.runs.create(thread.id, {
  assistant_id: assistant.id,
});

// 5. Poll for completion
let status = await openai.beta.threads.runs.retrieve(thread.id, run.id);
while (status.status !== 'completed') {
  await new Promise(r => setTimeout(r, 1000));
  status = await openai.beta.threads.runs.retrieve(thread.id, run.id);
}

// 6. Get response
const messages = await openai.beta.threads.messages.list(thread.id);
console.log(messages.data[0].content[0].text.value);

Core Concepts

Four Main Objects:

1. Assistants: Configured AI with instructions (max 256k chars in v2, was 32k in v1), model, tools, metadata
2. Threads: Conversation containers with persistent message history (max 100k messages)
3. Messages: User/assistant messages with optional file attachments
4. Runs: Async execution with states (queued, in_progress, requires_action, completed, failed, expired)

Key API Patterns

Assistants

const assistant = await openai.beta.assistants.create({
  model: "gpt-5",
  instructions: "System prompt (max 256k chars in v2)",
  tools: [{ type: "code_interpreter" }, { type: "file_search" }],
  tool_resources: { file_search: { vector_store_ids: ["vs_123"] } },
});

Key Limits: 256k instruction chars (v2), 128 tools max, 16 metadata pairs

Threads & Messages

// Create thread with messages
const thread = await openai.beta.threads.create({
  messages: [{ role: "user", content: "Hello" }],
});

// Add message with attachments
await openai.beta.threads.messages.create(thread.id, {
  role: "user",
  content: "Analyze this",
  attachments: [{ file_id: "file_123", tools: [{ type: "code_interpreter" }] }],
});

// List messages
const msgs = await openai.beta.threads.messages.list(thread.id);

Key Limits: 100k messages per thread

Runs

// Create run with optional overrides
const run = await openai.beta.threads.runs.create(thread.id, {
  assistant_id: "asst_123",
  additional_messages: [{ role: "user", content: "Question" }],
  max_prompt_tokens: 1000,
  max_completion_tokens: 500,
});

// Poll until complete
let status = await openai.beta.threads.runs.retrieve(thread.id, run.id);
while (['queued', 'in_progress'].includes(status.status)) {
  await new Promise(r => setTimeout(r, 1000));
  status = await openai.beta.threads.runs.retrieve(thread.id, run.id);
}

Run States: queued → in_progress → requires_action (function calling) / completed / failed / cancelled / expired (10 min max)

Streaming

const stream = await openai.beta.threads.runs.stream(thread.id, { assistant_id });

for await (const event of stream) {
  if (event.event === 'thread.message.delta') {
    process.stdout.write(event.data.delta.content?.[0]?.text?.value || '');
  }
}

Key Events: thread.run.created, thread.message.delta (streaming co