Overview
Purpose and Scope
The OpenAI Node repository is the official TypeScript and JavaScript SDK for the OpenAI API. Its purpose is to give application developers a typed, convenient client for calling the OpenAI REST API from JavaScript runtimes while preserving close alignment with the public API surface. The README frames the package as generated from the OpenAI OpenAPI specification with Stainless, so the repository should be read as both a developer-facing library and a generated binding layer over the platform API. For product behavior, policy, permissions, and data controls, the README intentionally points readers back to the OpenAI API Reference and platform documentation rather than duplicating all platform guidance here.
Sources: README.md, src/index.ts
This overview page helps you decide where to start. If you want to make a first model request, begin with the client constructor and the Responses API examples. If you need method-level details, use the generated API reference. If you are integrating in a specific runtime or provider environment, move from the base package entrypoint to the runtime, Azure, Bedrock, or authentication pages. The repository is not only a set of examples; it also defines the published package metadata, export map, public TypeScript entrypoints, error classes, pagination helpers, upload helpers, and provider variants that downstream applications import.
Sources: README.md, package.json, src/index.ts, api.md
Relevant Source Files
- README.md — Introduces the library, installation commands, primary usage path, Responses API examples, Chat Completions compatibility notes, conversation-state guidance, and links to the platform documentation and generated API reference.
- package.json — Defines the published npm package named openai, its version, CommonJS package type, TypeScript declaration entry, import and require exports, scripts, peer dependencies, and optional provider/runtime dependencies.
- src/index.ts — Defines the public TypeScript entrypoint by re-exporting the default OpenAI client, ClientOptions, upload utilities, promises, pagination, error classes, AzureOpenAI, and BedrockOpenAI.
- api.md — Serves as the generated full API reference named by the README for detailed resource, method, type, and example coverage.
System-to-Code Mapping
At the top level, the SDK has three important documentation layers. The README gives a task-oriented introduction and shows the expected first interaction: import the default client, provide an API key through the environment or constructor options, and call the Responses API. The package metadata defines how that same client is resolved by JavaScript tooling in applications. The public index file defines what symbols are intentionally exported to users. The generated reference then expands those public resource surfaces into method-level documentation. Together, these files tell readers what the SDK is, how it is installed, what can be imported, and where detailed API coverage lives.
Sources: README.md, package.json, src/index.ts, api.md
The SDK’s generation model is central to interpreting the repository. Both the README and index file identify the code as generated from the OpenAPI specification by Stainless, which means many resource modules and types reflect the upstream API schema rather than hand-written wrappers. That matters for developers because naming, request shapes, response types, and nested resource organization are expected to track the OpenAI API. It also matters for contributors because generated code should be approached differently from handwritten examples or tests. When learning the SDK, prefer the public client and generated reference instead of internal implementation details unless you are debugging packaging or contributing.
Sources: README.md, src/index.ts, api.md
| Reader question | Primary source | What to look for |
|---|---|---|
| What is this package? | README.md | Official TypeScript and JavaScript library for convenient OpenAI REST API access |
| How is it published? | package.json | Package name, version, declaration file, CommonJS type, and export map |
| What can I import? | src/index.ts | Default client, named client, options, errors, upload helpers, pagination, Azure, and Bedrock exports |
| Where are all methods documented? | api.md | Generated API reference and examples named by the README |
Primary Usage Model
The README identifies the Responses API as the primary model interaction surface. In the introductory example, a developer creates a new client, passes an API key from the environment when needed, and calls the responses create method with a model, instructions, and input. The response object exposes output text for simple text generation. This flow establishes several conventions used throughout the SDK: the client owns authentication and base request behavior, resource namespaces group API endpoints, request bodies are plain JavaScript objects, and response values are typed objects returned through promises.
Sources: README.md, src/index.ts
The same README also preserves Chat Completions as the previous standard and says it is supported indefinitely. That positioning is important for teams migrating older applications: Chat Completions remains a first-class namespace, but new work should usually start with Responses because it unifies text generation, multimodal input, conversation continuation, and tool-oriented workflows. The overview should therefore not treat the SDK as a single endpoint wrapper. It is a broad generated API client whose current learning path starts at Responses while still exposing legacy-compatible and specialized resources through the same OpenAI client object.
Sources: README.md, api.md
Conversation state is another early signal of how the SDK expects developers to compose calls. The README warns that manually replaying only message output can drop reasoning or tool-call items required by a later Responses request. It recommends normalizing replayable output with a helper or using a previous response identifier for simple continuation. This is a useful example of the SDK’s role: it does not merely send HTTP requests, it also provides helper methods that encode safe usage patterns around complex platform features. Readers building agents, tools, or multi-turn applications should follow those helper-oriented patterns before writing their own transcript filtering.
Sources: README.md
Package Entrypoints and Public API Components
The package metadata publishes the library under the openai name and marks the main declaration file as the generated TypeScript definitions in the distribution build. Its export map supports both import and require consumers at the package root, while also allowing subpath resolution for generated files. This explains why examples can use the default import in TypeScript or modern JavaScript while CommonJS applications can still resolve the package through the require export. The package file also records build, test, lint, and formatting scripts, making it the source of truth for how the repository is packaged and validated.
Sources: package.json
The public index file is the compact contract most users experience. It re-exports the default OpenAI client and the named OpenAI class with ClientOptions, making client construction the main entrypoint. It also exports upload helpers such as toFile, promise and pagination abstractions, a full hierarchy of API and connection error classes, webhook signature errors, OAuth-related errors, and provider-specific client variants for Azure OpenAI and AWS Bedrock. Those exports show that the SDK covers more than model calls: it includes request lifecycle primitives, file upload support, paginated list handling, structured error handling, and alternate provider authentication surfaces.
Sources: src/index.ts, package.json
Relationship to OpenAI Platform Documentation
The SDK README links readers to the OpenAI API Reference and platform documentation for learning how to use the OpenAI API. That separation is intentional. This repository documents the client library, package entrypoints, generated types, examples, and runtime behavior; the platform docs remain the place for conceptual product guidance such as permissions, data controls, policy-sensitive behavior, and API feature semantics. When a question is about how to construct a JavaScript request, look in this repository and the generated reference. When a question is about organizational access, retention settings, or product-level capability meaning, use the platform documentation alongside the SDK.
Sources: README.md, api.md
Next Steps
Start with the developer quickstart if you want to make a first Responses API call. Continue to client configuration and authentication when you need API keys, organization or project scoping, custom fetch behavior, retries, or request-level options. Use the Responses, streaming, structured outputs, files, and tool-related pages when building richer model workflows. Use the reference pages when you need exact methods and request types. For provider-specific deployments, read the Azure OpenAI, AWS Bedrock, workload identity federation, and runtime pages after you understand the base OpenAI client and its exported public primitives.
Sources: README.md, package.json, src/index.ts, api.md