Getting Started with OpenAI Responses API

Introduction & Goals

Welcome to your first lesson in building effective agents with GPT! Whether you're new to the OpenAI API or have some experience, this lesson will give you a solid foundation in structuring requests and interpreting responses — skills you'll reuse for agent workflows throughout this course. In this lesson, you'll learn how to send messages using the Responses API and understand the complete response structure. By the end, you'll be able to create a script that communicates with a chat-capable model and inspect the full JSON response. This matters because, throughout the course, we'll be working with different parts of Responses API outputs — from basic text to reasoning summaries and conversation flow control. The same patterns extend to more complex workflows later in the path, regardless of which compatible model you choose.

Environment and Setup

To communicate with GPT-5, you'll need two things: the OpenAI Node.js library and an API key from OpenAI. The library handles all the technical details of making API requests, and you'd normally install it through your package manager (for example, with npm install openai or yarn add openai). The API key authenticates your requests, and the OpenAI client automatically looks for it in the OPENAI_API_KEY environment variable. In CodeSignal, we've already configured everything for you — the library is pre-installed and your API key is set up, so you can focus on learning the core concepts without worrying about setup details.

How the Responses API Handles Messaging

Every interaction follows a structured conversation pattern. The Responses API uses role-based messaging : The system role (passed via instructions) sets behavior and context for the model — the model's "job description" for the conversation. The user role represents messages from you or your end users. The assistant role represents model responses. When you make a request, you provide a model, an instructions string, an input array representing the conversation history, and optional flags like store to control persistence. The API returns a structured JSON object containing the model's output and metadata — details we'll rely on later for reasoning tracking, conversation management, and error handling.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Examining the Complete Response Structure

To understand what GPT-5 returns, let's examine the complete response structure:

TypeScript

// Print the whole response as JSON
console.log(JSON.stringify(response, null, 2));

// Print the whole response as JSON
console.log(JSON.stringify(response, null, 2));

The JSON.stringify() method converts the response object into formatted JSON with 2-space indentation. You'll see output like this:

JSON

{
  "id": "resp_0883d40a2e846037016916307aa80c81a38f1c21a2e93f8e00",
  "created_at": 1763061882,
  ...,
  "model": "gpt-5-2025-08-07",
  "object": "response",
  "output": [
    {
      "id": "rs_0883d40a2e846037016916307af9d081a3ad530b171275c22d",
      "summary": [],
      "type": "reasoning",
      ...
    },
    {
      "id": "msg_0883d40a2e846037016916307e706481a3baa7786f85668242",
      "content": [
        {
          "annotations": [],
          "text": "Cats are generally more independent and low‑maintenance (litter box, self-grooming), while dogs are more social and trainable but need more time, exercise, and attention.",
          "type": "output_text",
          "logprobs": []
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  ...,
  "status": "completed",
  ...,
  "usage": {
    "input_tokens": 32,
    ...,
    "output_tokens": 171,
    "output_tokens_details": {
      "reasoning_tokens": 128
    },
    "total_tokens": 203
  },
  ...,
  "store": false
}

{
  "id": "resp_0883d40a2e846037016916307aa80c81a38f1c21a2e93f8e00",
  "created_at": 1763061882,
  ...,
  "model": "gpt-5-2025-08-07",
  "object": "response",
  "output": [
    {
      "id": "rs_0883d40a2e846037016916307af9d081a3ad530b171275c22d",
      "summary": [],
      "type": "reasoning",
      ...
    },
    {
      "id": "msg_0883d40a2e846037016916307e706481a3baa7786f85668242",
      "content": [
        {
          "annotations": [],
          "text": "Cats are generally more independent and low‑maintenance (litter box, self-grooming), while dogs are more social and trainable but need more time, exercise, and attention.",
          "type": "output_text",
          "logprobs": []
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  ...,
  "status": "completed",
  ...,
  "usage": {
    "input_tokens": 32,
    ...,
    "output_tokens": 171,
    "output_tokens_details": {
      "reasoning_tokens": 128
    },
    "total_tokens": 203
  },
  ...,
  "store": false
}

This structure contains everything you need to see how the API processed your request and what it returned.

Examining Reasoning Responses

Let's examine the full response structure to see both GPT-5's internal reasoning summary and its final answer:

TypeScript

// Print the whole response as JSON first
console.log(JSON.stringify(thirdResponse, null, 2));

// Print the whole response as JSON first
console.log(JSON.stringify(thirdResponse, null, 2));

You'll see output that includes both a reasoning block with a summary and a message block with the final answer:

JSON

{
  "id": "resp_03732b58b4fc23fb01691630839c14819cb5a6d022f72be3d9",
  "created_at": 1763061891,
  ...,
  "model": "gpt-5-2025-08-07",
  "object": "response",
  "output": [
    {
      "id": "rs_03732b58b4fc23fb01691630842694819ca5c5b1a37288a29f",
      "type": "reasoning",
      "summary": [
        {
          "type": "summary_text",
          "text": "**Comparing grooming needs**\n\nThe user is asking about grooming requirements, so I want to keep this brief. Cats are generally more self-sufficient with their grooming and usually just need an occasional brushing, especially the long-haired ones, along with nail trims. In contrast, dogs require regular brushing, baths, and nail trims. They also need ear cleaning, and some breeds will need professional grooming due to their specific coat types. It's all about frequency and the level of care needed!"
        }
      ]
    },
    {
      "id": "msg_03732b58b4fc23fb016916308857f8819c8a40b06184b8fe7d",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "logprobs": [],
          "text": "- Cats: Mostly self‑groom. Brush weekly (daily for long‑hair), trim nails every 2–4 weeks; occasional baths only if needed.\n- Dogs: Need regular brushing (frequency depends on coat), baths every 4–8 weeks, nail trims every 3–6 weeks, ear cleaning; many breeds need professional grooming every 4–8 weeks."
        }
      ],
      "role": "assistant"
    }
  ],
  ...,
  "status": "completed",
  ...,
  "usage": {
    "input_tokens": 129,
    ...,
    "output_tokens": 147,
    "output_tokens_details": {
      "reasoning_tokens": 64
    },
    "total_tokens": 276
  },
  ...,
  "store": false
}

{
  "id": "resp_03732b58b4fc23fb01691630839c14819cb5a6d022f72be3d9",
  "created_at": 1763061891,
  ...,
  "model": "gpt-5-2025-08-07",
  "object": "response",
  "output": [
    {
      "id": "rs_03732b58b4fc23fb01691630842694819ca5c5b1a37288a29f",
      "type": "reasoning",
      "summary": [
        {
          "type": "summary_text",
          "text": "**Comparing grooming needs**\n\nThe user is asking about grooming requirements, so I want to keep this brief. Cats are generally more self-sufficient with their grooming and usually just need an occasional brushing, especially the long-haired ones, along with nail trims. In contrast, dogs require regular brushing, baths, and nail trims. They also need ear cleaning, and some breeds will need professional grooming due to their specific coat types. It's all about frequency and the level of care needed!"
        }
      ]
    },
    {
      "id": "msg_03732b58b4fc23fb016916308857f8819c8a40b06184b8fe7d",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "logprobs": [],
          "text": "- Cats: Mostly self‑groom. Brush weekly (daily for long‑hair), trim nails every 2–4 weeks; occasional baths only if needed.\n- Dogs: Need regular brushing (frequency depends on coat), baths every 4–8 weeks, nail trims every 3–6 weeks, ear cleaning; many breeds need professional grooming every 4–8 weeks."
        }
      ],
      "role": "assistant"
    }
  ],
  ...,
  "status": "completed",
  ...,
  "usage": {
    "input_tokens": 129,
    ...,
    "output_tokens": 147,
    "output_tokens_details": {
      "reasoning_tokens": 64
    },
    "total_tokens": 276
  },
  ...,
  "store": false
}

Notice how the response now contains two output blocks: a reasoning block showing GPT-5's internal thought process as a summary and a message block with the polished final answer. The usage section also breaks down token consumption, showing that 64 tokens were used for reasoning.

When reasoning is enabled, you can access the summary through the response structure, but the output_text property still gives you just the final answer:

TypeScript

// Print the response content
console.log(thirdResponse.output_text);

// Print the response content
console.log(thirdResponse.output_text);

This produces the clean final output:

text

- Cats: Mostly self‑groom. Brush weekly (daily for long‑hair), trim nails every 2–4 weeks; occasional baths only if needed.
- Dogs: Need regular brushing (frequency depends on coat), baths every 4–8 weeks, nail trims every 3–6 weeks, ear cleaning; many breeds need professional grooming every 4–8 weeks.

- Cats: Mostly self‑groom. Brush weekly (daily for long‑hair), trim nails every 2–4 weeks; occasional baths only if needed.
- Dogs: Need regular brushing (frequency depends on coat), baths every 4–8 weeks, nail trims every 3–6 weeks, ear cleaning; many breeds need professional grooming every 4–8 weeks.

The reasoning summary provides insight into how GPT-5 approached the problem, which can be valuable for debugging and understanding the model's decision-making process, especially when building complex agent workflows.

Introduction & Goals

Environment and Setup

How the Responses API Handles Messaging

Join the 1M+ learners on CodeSignal

Setting Up the Client and Configuration

Creating Your First Message

Sending the Message with the Responses API

Examining the Complete Response Structure

Understanding Response Fields

Extracting the Text Response

Building Multi-Turn Conversations

Enabling Enhanced Reasoning

Examining Reasoning Responses

Summary & Next Steps