OpenAPI and GPT Actions

Purpose and Scope

This page explains how OpenAPI-backed integrations and GPT Actions relate to the openai-node SDK. GPT Actions are a ChatGPT product capability: a Custom GPT can use a REST API schema, authentication configuration, and instructions to turn a natural-language request into a structured API call. The SDK does not replace that Custom GPT configuration surface. Instead, it gives TypeScript and JavaScript developers a generated client for the OpenAI REST API, including model interaction surfaces where tool-like workflows, response items, and streaming behavior are represented in code.

Sources: README.md, api.md, src/resources/responses/index.ts

The most important distinction is between two OpenAPI roles. First, openai-node itself is generated from OpenAI's OpenAPI specification, so its resource classes, request parameters, response types, and importable entrypoints mirror the public OpenAI REST API. Second, GPT Actions use an OpenAPI-style description of a third-party REST API so ChatGPT can decide which operation to call and generate JSON arguments for that call. In practice, you use this SDK to build, test, or operate the OpenAI side of an application, while the action schema describes the external service being connected.

Relevant Source Files

• README.md - Establishes that this package is the official TypeScript and JavaScript library for the OpenAI REST API, generated from the OpenAI OpenAPI specification with Stainless, and points readers to the generated API reference and platform documentation.
• api.md - Serves as the generated API surface reference for the full SDK. For OpenAPI-backed work, this is the place to inspect generated resources, method names, request types, response types, and examples for the OpenAI API.
• src/resources/responses/index.ts - Defines the Responses namespace exports, including Responses, InputItems, InputTokens, WebSocket client option types, and reconnect option types that matter when action-like workflows are modeled through response inputs, outputs, tokens, or streaming sessions.

Conceptual Model

GPT Actions are built around REST interoperability. A developer describes a third-party API operation with a schema, configures authentication, and writes instructions that help the GPT decide when to call it. At runtime, the model maps the user's natural-language request to the JSON shape needed by the API operation, invokes the API, and turns the result back into natural-language output. The official Actions documentation describes common patterns such as data retrieval from another system and state-changing operations like filing tickets or updating external records.

The SDK enters that architecture when your application needs to call OpenAI APIs from JavaScript or TypeScript. The README presents the Responses API as the primary API for interacting with OpenAI models, with a client constructed from OpenAI and a client.responses.create call that accepts fields such as model, instructions, and input. That request shape is relevant to action-oriented systems because the model-facing portion of the workflow still needs a stable way to send context, instructions, and user input to OpenAI before or after external API work happens.

Sources: README.md, api.md, src/resources/responses/index.ts

System-to-Code Mapping

Execution Flow for an OpenAPI-Backed Integration

A typical integration begins with the external API contract, not with SDK code. Decide which third-party operations are safe and useful for natural-language access, write an OpenAPI schema for those operations, and configure the authentication mechanism in the action environment. The official Actions docs emphasize that this schema is what lets ChatGPT generate the JSON arguments for an API call. If you need preprocessing, filtering, or access to systems that are not directly exposed through HTTP, a middleware service can sit between the action and the final backend.

Next, use openai-node for the parts of your application that talk to OpenAI. The README's minimal pattern is to import OpenAI, construct a client, and call client.responses.create with model input. In an action-oriented service, that same pattern can be used to generate assistant output before an action, summarize data after an action, or coordinate an application flow that combines instructions, user input, and external results. The key implementation boundary is that the SDK call targets OpenAI's API, while the GPT Action call targets the third-party API described by your action schema.

Sources: README.md, api.md, src/resources/responses/index.ts

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'],
});
 
const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions: 'Use external system results carefully and explain the final answer clearly.',
  input: 'Summarize the status returned by my integration workflow.',
});
 
console.log(response.output_text);

API Components and Reference

The Responses resource is the SDK surface to start with when connecting model behavior to integration workflows. The README identifies it as the primary API for model interaction, and src/resources/responses/index.ts shows that the namespace is more than a single create method wrapper. It exports Responses for the main resource implementation, InputItems for response input item access, and InputTokens for token-counting support. It also exports WebSocket-related option types, ResponsesWSClientOptions and ResponsesWSReconnectOptions, which indicate that streaming or realtime-style response interactions are represented as typed SDK options.

For reference work, keep api.md open beside your implementation. Because the SDK is generated, the generated reference is the contract source for concrete method names, parameter objects, response object types, and examples. This matters for OpenAPI-backed integrations because you often need to compare two schemas: the OpenAI API schema exposed through the SDK and the third-party API schema exposed to GPT Actions. Avoid copying assumptions from one side into the other. The OpenAI client accepts OpenAI request shapes; the action schema describes the external operation and its JSON arguments.

Sources: README.md, api.md, src/resources/responses/index.ts

Design Guidance and Next Steps

When building a GPT Action, treat natural language as the user interface, the action OpenAPI schema as the external API contract, and openai-node as the programmatic OpenAI client for JavaScript and TypeScript services. Keep authentication responsibilities explicit: the SDK client uses OpenAI API credentials, while a GPT Action or middleware service uses the credentials needed by the third-party service. This separation makes debugging easier because OpenAI request failures, schema-mapping issues, and downstream API errors can be isolated to different layers of the system.

If you are starting from this repository, first read the README usage section to confirm client construction and the Responses API pattern. Then use api.md to inspect the exact generated OpenAI operations you need. Finally, map any action workflow to the Responses namespace when your application needs model input, output, response items, token counting, or streaming support. For adjacent topics, continue with the Responses API concepts page, the Tools and approvals page, MCP integrations, or the ChatKit page if your action is triggered from a ChatKit frontend interaction.