openai-responses

OpenAI Responses API

Status: Production Ready | API Launch: March 2025 | SDK: openai@5.19.1+

Quick Start (5 Minutes)

Node.js

import OpenAI from 'openai';

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

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'What are the 5 Ds of dodgeball?',
});

console.log(response.output_text);

Cloudflare Workers

const response = await fetch('https://api.openai.com/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5',
    input: 'Hello, world!',
  }),
});

const data = await response.json();
console.log(data.output_text);

Load references/setup-guide.md for complete setup with stateful conversations and built-in tools.

What Is the Responses API?

The Responses API (/v1/responses) is OpenAI's unified interface for agentic applications launched March 2025. Key Innovation: Preserved reasoning state across turns (unlike Chat Completions which discards it), improving multi-turn performance by ~5% on TAUBench.

Why Use Responses Over Chat Completions? Automatic state management, preserved reasoning, server-side tools, 40-80% better cache utilization, and built-in MCP support.

Load references/responses-vs-chat-completions.md for complete comparison and decision guide.

Top 3 Critical Rules

Always Do ✅

1. Store conversation_id - Preserve state between turns (most critical)
2. Use environment variables for API keys (NEVER hardcode)
3. Handle polymorphic outputs - Check output.type (message, reasoning, function_call)

Never Do ❌

1. Never ignore conversation_id - State will be lost
2. Never assume single output type - Always check output.type
3. Never mix Chat Completions and Responses in same conversation

Load references/setup-guide.md for complete rules and best practices.

Top 5 Use Cases

Use Case 1: Stateful Conversation

// First turn
const response1 = await openai.responses.create({
  model: 'gpt-5',
  input: 'My favorite color is blue.',
});

const conversationId = response1.conversation_id;

// Second turn - model remembers
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation_id: conversationId,
  input: 'What is my favorite color?',
});
// Output: "Your favorite color is blue."

Load: references/stateful-conversations.md + templates/stateful-conversation.ts

Use Case 2: Web Search Agent

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Search the web for latest AI news.',
  tools: {
    web_search: { enabled: true },
  },
});

Load: references/built-in-tools-guide.md + templates/web-search.ts

Use Case 3: Code Interpreter

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Calculate the sum of squares from 1 to 100.',
  tools: {
    code_interpreter: { enabled: true },
  },
});

Load: references/built-in-tools-guide.md + templates/code-interpreter.ts

Use Case 4: File Search (RAG)

// Upload file
const file = await openai.files.create({
  file: fs.createReadStream('document.pdf'),
  purpose: 'user_data',
});

// Search file
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Summarize key points from the uploaded document.',
  tools: {
    file_search: {
      enabled: true,
      file_ids: [file.id],
    },
  },
});

Load: references/built-in-tools-guide.md + templates/file-search.ts

Use Case 5: MCP Server Integration

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Get weather for San Francisco.',
  tools: {
    mcp_servers: [
      {
        url: 'https://weather-mcp.example.com',
        tool_choice: 'auto',
      },
    ],
  },
});

Load: references/mcp-integration-guide.md + templates/mcp-integration.ts

Built-in Tools

All tools run server-side: Code Interpreter (Python execution), File Search (RAG), Web Search (real-time), Image Generation (DALL-E).

Enable explicitly:

tools: {
  code_interpreter: { enabled: true },
  file_search: { enabled: true, file_ids: ['file-123'] },
  web_search: { enabled: true },
  image_generation: { enabled: true },
}

Load references/built-in-tools-guide.md for complete guide with examples and configuration options.

Stateful Conversations

Automatic state management with conversation IDs eliminates manual message tracking, preserves reasoning, and improves cache utilization by 40-80%.

// Create conversation
const response1 = await openai.responses.create({
  model: 'gpt-5',
  input: 'Remember: my name is Alice.',
});

// Continue conversation
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation_id: response1.conversation_id,
  input: 'What is my name?',
});

Load references/stateful-conversations.md for persistence patterns (Node.js/Redis/KV) and lifecycle management.

Migration from Chat Completions

Quick changes: messages → input, system role → developer, choices[0].message.content → output_text, /v1/chat/completions → /v1/responses.

Before (Chat Completions):

const messages = [{ role: 'user', content: 'Hello' }];
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: messages,
});
messages.push(response.choices[0].message); // Manual history

After (Responses API):

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Hello',
});

const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation_id: response.conversation_id, // Automatic state
  input: 'Follow-up question',
});

Load references/migration-guide.md for complete migration checklist with tool migration patterns.

Polymorphic Outputs

Responses can return multiple output types (message, reasoning, function_call, image). Handle each type or use output_text convenience property.

for (const output of response.output) {
  if (output.type === 'message') {
    console.log('Message:', output.content);
  } else if (output.type === 'reasoning') {
    console.log('Reasoning:', output.summary);
  } else if (output.type === 'function_call') {
    console.log('Function:', output.name, output.arguments);
  }
}

// Or use convenience property
console.log(response.output_text);

Load references/reasoning-preservation.md for reasoning output details and debugging patterns.

Background Mode

For long-running tasks (>60 seconds), use background: true to run asynchronously and poll for completion.

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Analyze this 50-page document.',
  background: true,
});

// Poll for completion
const completed = await openai.responses.retrieve(response.id);

Load templates/background-mode.ts for complete polling pattern with exponential backoff.

Top 3 Errors & Solutions

Error 1: Session State Not Persisting

Symptom: Model doesn't remember previous turns.

Cause: Not using conversation IDs or creating new conversation each time.

Solution:

// ✅ GOOD: Reuse conversation ID
const conv = await openai.conversations.create();
const response1 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // Same ID
  input: 'Question 1',
});
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // Same ID - remembers previous
  input: 'Question 2',
});

Error 2: MCP Server Connection Failed

Cause: In