The Responses API: Your First Direct Call

There Are Two Levels

When you work with Codex, you are usually operating at the agent level. You describe a task, the agent reads files, writes code, runs commands, and delivers a result. This is the right level for most coding work — it handles the complexity of multi-step reasoning and tool orchestration for you.

But there is a level below the agent: the raw API. Under the hood, the agent works the same way you are about to — a loop of API calls plus tool execution — so learning the direct API demystifies how the agent operates. And when your task is a single inference — extract this, classify that, generate this text — dropping below the agent and calling the API directly is faster, cheaper, and simpler to debug. Everything Codex does is built from the same primitives you are about to use.

When to Use What

The distinction is not about complexity of the prompt — it is about whether the task requires acting on the environment across multiple steps. If the answer is a single text or structured response, call the API directly. If the answer requires reading real files, running real code, or making real changes to a codebase, use the agent.

The Responses API

The Responses API is OpenAI's primary API for new work. If you have used client.chat.completions.create before, this is the modern replacement — same underlying model, cleaner interface, and the foundation that all new OpenAI features (tool calling, structured output, streaming, multi-turn) are built on.

The examples below are TypeScript using the official openai SDK — the first time this track leaves the CLI/terminal. This lesson and the next assume you can read basic JavaScript/TypeScript (variables, functions, objects, await). Before running any of them, set up a minimal toolchain: install the SDK with npm install openai, and run a .ts file directly with tsx (no separate compile step) via npx tsx file.ts. Make sure your OPENAI_API_KEY is exported (the “Your OpenAI Account, API Keys, and Auth” lesson) so new OpenAI() can pick it up.

npm install openai
npx tsx your-first-call.ts   # runs the TypeScript file directly

The minimal call is three lines:

const client = new OpenAI()
const response = await client.responses.create({ model: "<model-name>", input: "What is 2 + 2?" })
console.log(response.output_text)

client.responses.create sends the request. The response object has output_text as the fast path to the generated text. When you need token usage, tool calls, or the full output array, those are at response.usage and response.output respectively.

Authentication and Setup

The openai SDK reads OPENAI_API_KEY from the environment automatically when you call new OpenAI() with no arguments. You do not need to pass the key explicitly.

npm install openai
export OPENAI_API_KEY=sk-...

The client also respects OPENAI_BASE_URL and OPENAI_ORG_ID if you need to route to a specific organization or proxy.

Adding Instructions

The instructions field is a system-level directive — equivalent to a system prompt in Chat Completions. Use it to give the model a role or behavioral constraint that applies to this request:

const response = await client.responses.create({
  model: "<model-name>",
  input: "Summarize the meeting notes: ...",
  instructions: "You are a technical writer. Be concise. Use bullet points for action items.",
})

The instructions field is processed before the input in the model's context, just like a system prompt. This is where you put persona definitions, output format requirements, and behavioral constraints for this request. (instructions applies per request; to carry state across turns you chain requests with previous_response_id or resend prior items, which later lessons build on.)

Streaming

Add stream: true to receive tokens as they are generated, rather than waiting for the full response:

const stream = await client.responses.create({
  model: "<model-name>",
  input: "Write a one-paragraph explanation of tool calling",
  stream: true,
})

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta)
  }
}

Streaming is the right choice for user-facing interfaces where you want the response to appear progressively — chat UIs, content editors, anything where waiting 3 seconds for a full response degrades the experience.

Usage and Cost

Every response includes a usage object with input_tokens, output_tokens, and total_tokens. These drive your invoice. Get in the habit of logging usage for every call in production:

const response = await client.responses.create({ model: "<model-name>", input: "Hello" })
console.log(response.output_text)
console.log("Tokens:", response.usage.total_tokens)

Token costs vary by model. As the “The Models Behind Codex” lesson covered, think in tiers, not fixed SKUs: a fast/mini tier model is the cost-optimized choice for high-volume tasks, while the advanced tier is appropriate where reasoning quality matters more than cost. Model names change often, so look up the current identifier for each tier at platform.openai.com/docs/models when you write the code. Knowing your token burn rate per operation is how you build AI products that have predictable unit economics.

The API Underneath the Agent

When Codex reads a file, it emits a tool call to a read_file function. When it writes code, it emits a write_file tool call. When it runs a command, it emits a shell tool call. The environment executes each of these and returns the result to the model, which continues reasoning and emits the next action.

The Responses API is exactly this mechanism — except you define what tools exist and you handle the execution. The next lesson covers tool calling in detail. For now, the key insight is that the agent is not magic: it is a loop built on the same client.responses.create you just learned, with tool definitions and environment execution wired in.