Reference 2026-06-04 06:52 UTC to 2026-06-05 06:45 UTC

1# API Overview1# API Overview

2 2 

3## Introduction3Use this reference to look up OpenAI API endpoints, request and response

4schemas, streaming events, client library methods, and shared behavior such as

5authentication, errors, rate limits, and request IDs.

4 6 

5This API reference describes the RESTful, streaming, and realtime APIs you can use to interact with the OpenAI platform. REST APIs are usable via HTTP in any environment that supports HTTP requests. Language-specific SDKs are listed [on the libraries page](https://developers.openai.com/docs/libraries).7## Start here

6 8 

7{/* TODO: Move this content into the main platform overview; keep this page minimal for now. */}91. Choose the API surface for your application:

10 - [Responses](https://developers.openai.com/api/reference/responses/overview) for direct model requests, tool use, audio, image, and text inputs, and stateful interactions.

11 - [Realtime API](https://developers.openai.com/api/docs/guides/realtime) for low-latency voice or audio sessions over WebRTC, WebSocket, or SIP. Use the [client events](https://developers.openai.com/api/reference/resources/realtime/client-events) and [server events](https://developers.openai.com/api/reference/resources/realtime/server-events) references while building sessions.

12 - [Administration](https://developers.openai.com/api/reference/administration/overview) for organization workflows such as users, invites, projects, API keys, and audit logs.

132. Create credentials. Use a standard [API key](https://platform.openai.com/settings/organization/api-keys) for application requests, an [Admin API key](https://platform.openai.com/settings/organization/admin-keys) for Administration endpoints, or [workload identity federation](https://developers.openai.com/api/docs/guides/workload-identity-federation) for short-lived access tokens.

143. Install an official client library from the [libraries page](https://developers.openai.com/api/docs/libraries), or call the HTTP API directly from any environment that supports HTTP requests.

154. Make a first request with the [developer quickstart](https://developers.openai.com/api/docs/quickstart) or go straight to the [Responses create reference](https://developers.openai.com/api/reference/resources/responses/methods/create).

165. Before production, review [error codes](https://developers.openai.com/api/docs/guides/error-codes), [rate limits](https://developers.openai.com/api/docs/guides/rate-limits), and request ID logging below.

8 17 

9## Authentication18## Authentication

10 19 

11The OpenAI API accepts bearer credentials from API keys or from short-lived access tokens created with [workload identity federation](https://developers.openai.com/api/docs/guides/workload-identity-federation). Create, manage, and learn more about API keys in your [organization settings](https://developers.openai.com/settings/organization/api-keys).20The OpenAI API accepts bearer credentials from API keys or from short-lived access tokens created with [workload identity federation](https://developers.openai.com/api/docs/guides/workload-identity-federation).

12 21 

13**Remember that your API key is a secret!** Do not share it with others or expose it in any client-side code (browsers, apps). API keys should be securely loaded from an environment variable or key management service on the server.22**Remember that your API key is a secret.** Don't share it with others or expose it in any client-side code such as browsers or apps. Load API keys from an environment variable or key management service on the server.

14 23 

15Provide API credentials via [HTTP Bearer authentication](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/).24Provide API credentials with [HTTP Bearer authentication](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/).

16 25 

17```bash26```bash

18Authorization: Bearer OPENAI_API_KEY_OR_ACCESS_TOKEN27Authorization: Bearer OPENAI_API_KEY_OR_ACCESS_TOKEN

19```28```

20 29 

21If you belong to multiple organizations or access projects through a legacy user API key, pass a header to specify which organization and project to use for an API request:30If you belong to more than one organization or access projects through a legacy user API key, pass a header to specify which organization and project to use for an API request:

22 31 

23```bash32```bash

24curl https://api.openai.com/v1/models \33curl https://api.openai.com/v1/models \

27 -H "OpenAI-Project: $PROJECT_ID"36 -H "OpenAI-Project: $PROJECT_ID"

28```37```

29 38 

30Usage from these API requests counts as usage for the specified organization and project. Organization IDs can be found on your [organization settings](https://developers.openai.com/settings/organization/general) page.39Usage from these API requests counts as usage for the specified organization and project. Find organization and project IDs in your [dashboard settings](https://platform.openai.com/settings/organization/general).

31Project IDs can be found on your [general settings](https://developers.openai.com/settings) page by selecting the specific project.

32 40 

33## Debugging requests41## Debugging requests

34 42 

35In addition to [error codes](https://developers.openai.com/docs/guides/error-codes) returned from API responses, you can inspect HTTP response headers containing the unique ID of a particular API request or information about rate limiting applied to your requests. Below is an incomplete list of HTTP headers returned with API responses:43[Error codes](https://developers.openai.com/api/docs/guides/error-codes) describe failures returned from API responses. Inspect HTTP response headers for the unique ID of a request and rate limit details. Common response headers include:

36 44 

37**API meta information**45**API meta information**

38 46 

39- `openai-organization`: The [organization](https://developers.openai.com/docs/guides/production-best-practices#setting-up-your-organization) associated with the request47- `openai-organization`: The [organization](https://developers.openai.com/api/docs/guides/production-best-practices#setting-up-your-organization) associated with the request

40- `openai-processing-ms`: Time taken processing your API request48- `openai-processing-ms`: Time taken processing your API request

41- `openai-version`: REST API version used for this request (currently `2020-10-01`)49- `openai-version`: REST API version used for this request (currently `2020-10-01`)

42- `x-request-id`: Unique identifier for this API request (used in troubleshooting)50- `x-request-id`: Unique identifier for this API request (used in troubleshooting)

43 51 

44**[Rate limiting information](https://developers.openai.com/docs/guides/rate-limits)**52**[Rate limiting information](https://developers.openai.com/api/docs/guides/rate-limits)**

45 53 

46- `x-ratelimit-limit-requests`54- `x-ratelimit-limit-requests`

47- `x-ratelimit-limit-tokens`55- `x-ratelimit-limit-tokens`

50- `x-ratelimit-reset-requests`58- `x-ratelimit-reset-requests`

51- `x-ratelimit-reset-tokens`59- `x-ratelimit-reset-tokens`

52 60 

53**OpenAI recommends logging request IDs in production deployments** for more efficient troubleshooting with our [support team](https://help.openai.com/en/), should the need arise. Our [official SDKs](https://developers.openai.com/docs/libraries) provide a property on top-level response objects containing the value of the `x-request-id` header.61**OpenAI recommends logging request IDs in production deployments** for more efficient troubleshooting with the [support team](https://help.openai.com/en/), should the need arise. Official [client libraries](https://developers.openai.com/api/docs/libraries) provide a property on top-level response objects containing the value of the `x-request-id` header.

54 62 

55### Supplying your own request ID with `X-Client-Request-Id`63### Supplying your own request ID with `X-Client-Request-Id`

56 64 

57In addition to the server-generated `x-request-id`, you can supply your own unique identifier for each request via the `X-Client-Request-Id` request header. This header is not added automatically; you must explicitly set it on the request.65Along with the server-generated `x-request-id`, you can supply your own unique identifier for each request via the `X-Client-Request-Id` request header. This header isn't added automatically; you must explicitly set it on the request.

58 66 

59When you include `X-Client-Request-Id`:67When you include `X-Client-Request-Id`:

60 68 

61- You control the ID format (for example, a UUID or your internal trace ID), but it must contain only ASCII characters and be no more than 512 characters long; otherwise, the request will fail with a 400 error. We strongly recommend making this value unique per request.69- You control the ID format (for example, a UUID or your internal trace ID), but it must contain only ASCII characters and be no more than 512 characters long; otherwise, the request will fail with a 400 error. Make this value unique per request.

62 70 

63- OpenAI will log this value in our internal logs for supported endpoints, including chat/completions, embeddings, responses, and more.71- OpenAI logs this value internally for supported endpoints, including chat/completions, embeddings, responses, and more.

64 72 

65- In cases like timeouts or network issues when you can't get the `X-Request-Id` response header, you can share the `X-Client-Request-Id` value with our support team, and we can look up whether we received the request and when.73- In cases like timeouts or network issues when you can't get the `X-Request-Id` response header, you can share the `X-Client-Request-Id` value with the support team to look up whether OpenAI received the request and when.

66 74 

67**Example:**75**Example:**

68 76 

74 82 

75## Backwards compatibility83## Backwards compatibility

76 84 

77OpenAI is committed to providing stability to API users by avoiding breaking changes in major API versions whenever reasonably possible. This includes:85OpenAI provides stability to API users by avoiding breaking changes in major API versions whenever reasonably possible. This includes:

78 86 

79- The REST API (currently `v1`)87- The REST API (currently `v1`)

80- Our first-party [SDKs](https://developers.openai.com/docs/libraries) (released SDKs adhere to [semantic versioning](https://semver.org/))88- First-party [client libraries](https://developers.openai.com/api/docs/libraries) (released libraries adhere to [semantic versioning](https://semver.org/))

81- [Model](https://developers.openai.com/docs/models) families (like `gpt-4o` or `o4-mini`)89- [Model](https://developers.openai.com/api/docs/models) families (like `gpt-4o` or `o4-mini`)

82 90 

83**Model prompting behavior between snapshots is subject to change**.91**Model prompting behavior between snapshots is subject to change**.

84Model outputs are by their nature variable, so expect changes in prompting and model behavior between snapshots. For example, if you moved from `gpt-4o-2024-05-13` to `gpt-4o-2024-08-06`, the same `system` or `user` messages could function differently between versions. The best way to ensure consistent prompting behavior and model output is to use pinned model versions, and to implement [evals](https://developers.openai.com/docs/guides/evals) for your applications.92Model outputs are by their nature variable, so expect changes in prompting and model behavior between snapshots. The best way to ensure consistent prompting behavior and model output is to use pinned model versions, and to run [evals](https://developers.openai.com/api/docs/guides/evals) for your applications.

85 93 

86**Backwards-compatible API changes**:94**Backwards-compatible API changes**:

87 95 

88- Adding new resources (URLs) to the REST API and SDKs96- Adding new resources (URLs) to the REST API and client libraries

89- Adding new optional API parameters97- Adding new optional API parameters

90- Adding new properties to JSON response objects or event data98- Adding new properties to JSON response objects or event data

91- Changing the order of properties in a JSON response object99- Changing the order of properties in a JSON response object

92- Changing the length or format of opaque strings, like resource identifiers and UUIDs100- Changing the length or format of opaque strings, like resource identifiers

93- Adding new event types (in either streaming or the Realtime API)101- Adding new event types in streaming APIs

94 102 

95See the [changelog](https://developers.openai.com/docs/changelog) for a list of backwards-compatible changes and rare breaking changes.

103See the [changelog](https://developers.openai.com/api/docs/changelog) for a list of backwards-compatible changes and rare breaking changes.