openai-responses

# OpenAI Responses API

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

---

## Quick Start (5 Minutes)

### Node.js

```typescript
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

```typescript
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