OpenAI Responses API

Status: Production Ready Last Updated: 2026-01-21 API Launch: March 2025 Dependencies: [email protected] (Node.js) or fetch API (Cloudflare Workers)

---

What Is the Responses API?

OpenAI's unified interface for agentic applications, launched March 2025. Provides stateful conversations with preserved reasoning state across turns.

Key Innovation: Unlike Chat Completions (reasoning discarded between turns), Responses preserves the model's reasoning notebook, improving performance by 5% on TAUBench and enabling better multi-turn interactions.

vs Chat Completions:

Feature	Chat Completions	Responses API
State	Manual history tracking	Automatic (conversation IDs)
Reasoning	Dropped between turns	Preserved across turns (+5% TAUBench)
Tools	Client-side round trips	Server-side hosted
Output	Single message	Polymorphic (8 types)
Cache	Baseline	40-80% better utilization
MCP	Manual	Built-in

---

Quick Start

npm install [email protected]

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);

Key differences from Chat Completions:

• Endpoint: /v1/responses (not /v1/chat/completions)
• Parameter: input (not messages)
• Role: developer (not system)
• Output: response.output_text (not choices[0].message.content)

---

When to Use Responses vs Chat Completions

Use Responses:

• Agentic applications (reasoning + actions)
• Multi-turn conversations (preserved reasoning = +5% TAUBench)
• Built-in tools (Code Interpreter, File Search, Web Search, MCP)
• Background processing (60s standard, 10min extended timeout)

Use Chat Completions:

• Simple one-off generation
• Fully stateless interactions
• Legacy integrations

---

Stateful Conversations

Automatic State Management using conversation IDs:

// Create conversation
const conv = await openai.conversations.create({
  metadata: { user_id: 'user_123' },
});

// First turn
const response1 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id,
  input: 'What are the 5 Ds of dodgeball?',
});

// Second turn - model remembers context + reasoning
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id,
  input: 'Tell me more about the first one',
});

Benefits: No manual history tracking, reasoning preserved, 40-80% better cache utilization

Conversation Limits: 90-day expiration

---

Built-in Tools (Server-Side)

Server-side hosted tools eliminate backend round trips:

Tool	Purpose	Notes
code_interpreter	Execute Python code	Sandboxed, 30s timeout (use background: true for longer)
file_search	RAG without vector stores	Max 512MB per file, supports PDF/Word/Markdown/HTML/code
web_search	Real-time web information	Automatic source citations
image_generation	DALL-E integration	DALL-E 3 default
mcp	Connect external tools	OAuth supported, tokens NOT stored

Usage:

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Calculate mean of: 10, 20, 30, 40, 50',
  tools: [{ type: 'code_interpreter' }],
});

Web Search TypeScript Note

TypeScript Limitation: The web_search tool's external_web_access option is missing from SDK types (as of v6.16.0).

Workaround:

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Search for recent news',
  tools: [{
    type: 'web_search',
    external_web_access: true,
  } as any],  // ✅ Type assertion to suppress error
});

Source: GitHub Issue #1716

---

MCP Server Integration

Built-in support for Model Context Protocol (MCP) servers to connect external tools (Stripe, databases, custom APIs).

User Approval Requirement

By default, explicit user approval is required before any data is shared with a remote MCP server (security feature).

Handling Approval:

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Get my Stripe balance',
  tools: [{
    type: 'mcp',
    server_label: 'stripe',
    server_url: 'https://mcp.stripe.com',
    authorization: process.env.STRIPE_TOKEN,
  }],
});

if (response.status === 'requires_approval') {
  // Show user: "This action requires sharing data with Stripe. Approve?"
  // After user approves, retry with approval token
}

Alternative: Pre-approve MCP servers in OpenAI dashboard (users configure trusted servers via settings)

Source: Official MCP Guide

Basic MCP Usage

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Roll 2d6 dice',
  tools: [{
    type: 'mcp',
    server_label: 'dice',
    server_url: 'https://example.com/mcp',
    authorization: process.env.TOKEN, // ⚠️ NOT stored, required each request
  }],
});

MCP Output Types:

• mcp_list_tools - Tools discovered on server
• mcp_call - Tool invocation + result
• message - Final response

---

Reasoning Preservation

Key Innovation: Model's internal reasoning state survives across turns (unlike Chat Completions which discards it).

Visual Analogy:

• Chat Completions: Model tears out scratchpad page before responding
• Responses API: Scratchpad stays open for next turn

Performance: +5% on TAUBench (GPT-5) purely from preserved reasoning

Reasoning Summaries (free):

response.output.forEach(item => {
  if (item.type === 'reasoning') console.log(item.summary[0].text);
  if (item.type === 'message') console.log(item.content[0].text);
});

Important: Reasoning Traces Privacy

What You Get: Reasoning summaries (not full internal traces) What OpenAI Keeps: Full chain-of-thought reasoning (proprietary, for security/privacy)

For GPT-5-Thinking models:

• OpenAI preserves reasoning internally in their backend
• This preserved reasoning improves multi-turn performance (+5% TAUBench)
• But developers only receive summaries, not the actual chain-of-thought
• Full reasoning traces are not exposed (OpenAI's IP protection)

Source: Sean Goedecke Analysis

---

Background Mode

For long-running tasks, use background: true:

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Analyze 500-page document',
  background: true,
  tools: [{ type: 'file_search', file_ids: [fileId] }],
});

// Poll for completion (check every 5s)
const result = await openai