# OpenAI official SDKs — atlas

**Status:** Python `openai` 3.16.2 and Node `openai` 7.18.0 (7.19.0 in the downloaded package.json) are installed here; their defaults below were read from the installed source (`LIVE_VERIFIED` / `sdk_types`) and `webhooks.unwrap` was executed offline. .NET, Java, Go, Ruby, CLI and the Agents SDK are `DOCUMENTED` from the libraries page (`UNVERIFIED`).
**Sources:** [Libraries & CLI](https://developers.openai.com/api/docs/libraries) · [Admin APIs guide (SDK versions)](https://developers.openai.com/api/docs/guides/admin-apis) · [Error codes → Python library error types](https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types) · [Rate limits → SDK retries](https://developers.openai.com/api/docs/guides/rate-limits#retrying-with-exponential-backoff) · [Webhooks guide](https://developers.openai.com/api/docs/guides/webhooks) · SDK surfaces `sources/openai/openapi/{python,node}-sdk-api.md` · installed sources `.venv/lib/python3.12/site-packages/openai/*`, `node_modules/openai/*`.
**Last verified:** 2026-09-18. Machine-readable: `generated/fragments/sdks/openai-sdks.json` (9 records).

## 1. Matrix

| | Python | TypeScript / JS | .NET | Java | Go | Ruby |
|---|---|---|---|---|---|---|
| Package | `openai` (PyPI) | `openai` (npm, also `jsr:@openai/openai`) | `OpenAI` (NuGet) | `com.openai:openai-java` | `github.com/openai/openai-go/v3` | `openai` gem |
| Version seen | 3.16.2 | 7.18.0 / 7.19.0 | — | 4.65.0 | v3 | — |
| Maturity | GA | GA | GA (Microsoft co-maintained; Responses under `OPENAI001`) | beta | beta | GA |
| Admin API since | 2.34.0 | 6.36.0 | not listed | 4.34.0 | 3.34.0 | 0.61.0 |
| Install | `pip install openai` | `npm i openai` | `dotnet add package OpenAI` | Maven dep | `go get …/openai-go/v3` | `gem "openai"` |
| Client | `OpenAI()` / `AsyncOpenAI()` | `new OpenAI()` | `new ResponsesClient(key)` | `OpenAIOkHttpClient.fromEnv()` | `openai.NewClient()` | `OpenAI::Client.new` |
| Default max retries | 2 | 2 | 3 (System.ClientModel) | 2 | 2 | 2 |
| Default timeout | 600 s total, 5 s connect | 600 000 ms | 100 s network (System.ClientModel) | 10 min | context-driven | 600 s |
| Raw response | `.with_raw_response` / `.with_streaming_response` | `.withResponse()` / `.asResponse()` | `ClientResult.GetRawResponse()` | `.withRawResponse()` | `option.WithResponseInto(&res)` | request_options |
| Request id | `obj._request_id`, `err.request_id` | `obj._request_id`, `err.requestID` | headers | headers | `res.Header` | headers |
| Pagination | `for x in client.….list()` auto-pages | `for await (const x of …list())` | `GetAllValues()` | `.autoPager()` | `ListAutoPaging` | `.auto_paging_each` |
| Streaming | `stream=True` iterator; `.responses.stream()` helper | `for await`; `.responses.stream()` events | `IAsyncEnumerable` | `createStreaming` | `NewStreaming` | `.stream` |
| Webhooks | `client.webhooks.unwrap/verify_signature` | `client.webhooks.unwrap/verifySignature` | — | — | — | `client.webhooks.unwrap` |
| Azure | `AzureOpenAI`, `AsyncAzureOpenAI` | `AzureOpenAI` | `Azure.AI.OpenAI` | Azure lib | `azopenai` | — |

## 2. Python (`openai` 3.16.2) — verified details

```python
from openai import OpenAI, AsyncOpenAI
client = OpenAI(                       # every argument optional
    api_key=...,                       # OPENAI_API_KEY
    admin_api_key=...,                 # OPENAI_ADMIN_KEY  → client.admin.*
    organization=..., project=...,     # OPENAI_ORG_ID / OPENAI_PROJECT_ID
    webhook_secret=...,                # OPENAI_WEBHOOK_SECRET → client.webhooks.unwrap
    workload_identity=...,             # WIF subject-token provider (mutually exclusive with api_key)
    base_url=...,                      # OPENAI_BASE_URL (e.g. https://eu.api.openai.com/v1)
    timeout=600.0, max_retries=2, default_headers={...}, http_client=httpx.Client(...))
```
- Constants (`openai/_constants.py`): `DEFAULT_TIMEOUT = httpx.Timeout(timeout=600, connect=5.0)`, `DEFAULT_MAX_RETRIES = 2`, `INITIAL_RETRY_DELAY = 0.5`, `MAX_RETRY_DELAY = 8.0`, connection pool 1000 / 100 keep-alive.
- Retry logic (`_base_client.py`): retries connection errors, 408, 409, 429, ≥ 500; reads `retry-after-ms` then `Retry-After` (seconds or HTTP-date), refuses to wait above 60 s; `x-should-retry` header wins. `client.with_options(max_retries=0, timeout=30)` per call.
- Errors: `openai.APIError` → `APIStatusError` (`BadRequestError` 400, `AuthenticationError` 401, `PermissionDeniedError` 403, `NotFoundError` 404, `ConflictError` 409, `UnprocessableEntityError` 422, `RateLimitError` 429, `InternalServerError` ≥ 500 incl. 503) plus `APIConnectionError`, `APITimeoutError`, `InvalidWebhookSignatureError`. Attributes: `status_code`, `code`, `param`, `type`, `body`, `request_id`, `response`.
- Raw/streamed responses: `client.responses.with_raw_response.create(...)` → `.headers`, `.parse()`; `client.files.with_streaming_response.content(id)`.
- Pagination classes: `SyncPage`, `SyncCursorPage`, `SyncConversationCursorPage`, `SyncNextCursorPage` (+ async twins) — iterate directly, or `.has_next_page()` / `.get_next_page()` / `.iter_pages()`.
- Streaming helpers: `client.responses.stream(...)` (context manager, typed events, `get_final_response()`), `client.chat.completions.stream(...)`, `client.beta.chat.completions.parse(...)` for structured outputs; Realtime `client.realtime.connect(model=...)`; `openai.lib.streaming`.
- Types: Pydantic models in `openai.types.*`; params as TypedDicts (`openai.types.responses.response_create_params`); `openai.NOT_GIVEN`.
- Webhooks: `client.webhooks.unwrap(payload, headers, *, secret=None)` → typed event union; `verify_signature(payload, headers, *, secret=None, tolerance=300)`; implementation `openai/lib/_webhooks.py` (HMAC-SHA256, `whsec_` base64 secret, `v1,` signatures, ±300 s).
- Admin: `OpenAI(admin_api_key=…).admin.organization.*` (see `docs/openai/admin-api.md`); Admin key is sent for routes whose OpenAPI security is `AdminApiKeyAuth`.
- Azure: `AzureOpenAI(api_version=..., azure_endpoint=..., api_key=... | azure_ad_token_provider=...)`; `openai.lib.azure`, plus `openai.lib.bedrock` shim.
- Logging: `OPENAI_LOG=debug`.

## 3. TypeScript / JavaScript (`openai` 7.18.0) — verified details

```ts
import OpenAI from "openai";
const client = new OpenAI({
  apiKey, adminAPIKey, organization, project, webhookSecret, workloadIdentity, baseURL,
  timeout: 600_000, maxRetries: 2, defaultHeaders, defaultQuery, fetch, fetchOptions, logLevel: "debug",
});
```
- `OpenAI.DEFAULT_TIMEOUT = 600000` (10 min); `maxRetries` default 2 with exponential backoff + jitter, `retry-after-ms` / `Retry-After` ≤ 60 s, `x-should-retry`. Per-request: `client.responses.create(params, { maxRetries: 0, timeout: 5_000, signal, headers })`.
- Node ≥ 22 (`engines`), ESM + CJS builds, `.d.mts` types; browsers need `dangerouslyAllowBrowser: true`.
- `APIPromise`: `await p.withResponse()` → `{ data, response, request_id }`; `await p.asResponse()` → fetch `Response`; results carry `_request_id`.
- Pagination: `for await (const item of client.fineTuning.jobs.list())`; pages expose `hasNextPage()` / `getNextPage()`.
- Streaming: `stream: true` → async iterable (`for await`), `stream.controller.abort()`; helpers `client.responses.stream()` with `.on(...)`/`finalResponse()`, `client.chat.completions.stream()`; Zod helpers `openai/helpers/zod` (`zodTextFormat`, `zodResponseFormat`).
- Errors: `OpenAI.APIError` (`status`, `code`, `type`, `param`, `error`, `requestID`, `headers`) with subclasses `BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `UnprocessableEntityError`, `RateLimitError`, `InternalServerError`, `APIConnectionError`, `APIConnectionTimeoutError`, `APIUserAbortError`, `InvalidWebhookSignatureError`.
- Webhooks: `await client.webhooks.unwrap(rawBody, headers, secret?, tolerance = 300)`, `verifySignature(...)`; verified identical to the Python scheme in `examples/openai/webhooks/offline_test.ts`.
- Realtime: `openai/realtime/websocket` (`OpenAIRealtimeWebSocket`), `openai/realtime/ws`; WIF helpers in `openai/auth/subject-token-providers`; Azure `AzureOpenAI` from `openai`; Bedrock shim `openai/bedrock`.

## 4. Other official clients (documented only)

- **.NET**: `dotnet add package OpenAI`; `ResponsesClient client = new(key); await client.CreateResponseAsync("gpt-6-astra", "…")` (`#pragma warning disable OPENAI001`); Microsoft's `Azure.AI.OpenAI` wraps it.
- **Java** (beta, 4.65.0): `OpenAIOkHttpClient.fromEnv()`; `client.responses().create(params)`; streaming `createStreaming`; async `client.async()`; exceptions `OpenAIServiceException` → `RateLimitException` (429), `InternalServerException` (5xx). Admin: `.adminApiKey(...)` builder + `client.admin().organization()…` (≥ 4.34.0).
- **Go** (beta, v3): `openai.NewClient(option.WithAPIKey(...))`, `client.Responses.New(ctx, responses.ResponseNewParams{...})`, errors `var apiErr *openai.Error; errors.As(err, &apiErr)`; admin `option.WithAdminAPIKey` + `client.Admin.Organization…` (≥ 3.34.0).
- **Ruby**: `OpenAI::Client.new(api_key:, admin_api_key:, webhook_secret:)`; `client.responses.create(...)`; `client.with_options(data_residency: :eu)`; `OpenAI::Errors::APIError`, `InvalidWebhookSignatureError`; typed webhook events `OpenAI::Models::Webhooks::ResponseCompletedWebhookEvent` (admin ≥ 0.61.0).
- **CLI**: `brew install openai/tools/openai`; `openai responses create --model … --input … --raw-output --transform '…'` (gjson-style transform); guide `docs/libraries/openai-cli`.
- **Agents SDK**: `openai-agents` (Python) / `@openai/agents` (TS) — orchestration (agents, tools, handoffs, guardrails, tracing, sandboxes) on top of Responses; use the plain SDK for direct calls.
- **Azure libraries**: .NET, JS, Java, Go clients maintained by Microsoft, compatible with both Azure OpenAI and the OpenAI API.
- **Community**: Clojure, Dart, Delphi, Elixir, Kotlin, PHP (`openai-php/client`), Rust (`async-openai`), Scala, Swift, Unity, Unreal — unverified by OpenAI.

## 5. Behaviour to remember

1. Both first-party SDKs retry 2× by default — disable (`max_retries=0`) when you implement your own retry or when measuring error shapes, otherwise a 429/5xx costs three requests.
2. `RateLimitError` ≠ overload: 503 `server_is_overloaded` surfaces as `InternalServerError`; catch both.
3. SDKs never send `Idempotency-Key`; long generations should use `background: true` + webhooks/polling rather than raising the 10-minute timeout.
4. `_request_id` is only populated from `x-request-id`; edge 404s (unknown URL) have none.
5. Admin routes require `admin_api_key` / `adminAPIKey`; passing a project key there yields `PermissionDeniedError` 403 (`AuthenticationError` 401 for audit logs) — reproduced in `examples/openai/admin/admin_readonly.{py,ts}`.