# OpenAI API docs — full documentation > Single-file Markdown export of API guides and docs. Curated index: https://developers.openai.com/api/docs/llms.txt # Data retrieval with GPT Actions One of the most common tasks an action in a GPT can perform is data retrieval. An action might: 1. Access an API to retrieve data based on a keyword search 2. Access a relational database to retrieve records based on a structured query 3. Access a vector database to retrieve text chunks based on semantic search We’ll explore considerations specific to the various types of retrieval integrations in this guide. ## Data retrieval using APIs Many organizations rely on 3rd party software to store important data. Think Salesforce for customer data, Zendesk for support data, Confluence for internal process data, and Google Drive for business documents. These providers often provide REST APIs which enable external systems to search for and retrieve information. When building an action to integrate with a provider's REST API, start by reviewing the existing documentation. You’ll need to confirm a few things: 1. Retrieval methods - **Search** - Each provider will support different search semantics, but generally you want a method which takes a keyword or query string and returns a list of matching documents. See [Google Drive’s `file.list` method](https://developers.google.com/drive/api/guides/search-files) for an example. - **Get** - Once you’ve found matching documents, you need a way to retrieve them. See [Google Drive’s `file.get` method](https://developers.google.com/drive/api/reference/rest/v3/files/get) for an example. 2. Authentication scheme - For example, [Google Drive uses OAuth](https://developers.google.com/workspace/guides/configure-oauth-consent) to authenticate users and ensure that only their available files are available for retrieval. 3. OpenAPI spec - Some providers will provide an OpenAPI spec document which you can import directly into your action. See [Zendesk](https://developer.zendesk.com/api-reference/ticketing/introduction/#download-openapi-file), for an example. - You may want to remove references to methods your GPT _won’t_ access, which constrains the actions your GPT can perform. - For providers who _don’t_ provide an OpenAPI spec document, you can create your own using the [ActionsGPT](https://chatgpt.com/g/g-TYEliDU6A-actionsgpt) (a GPT developed by OpenAI). Your goal is to get the GPT to use the action to search for and retrieve documents containing context which are relevant to the user’s prompt. Your GPT follows your instructions to use the provided search and get methods to achieve this goal. ## Data retrieval using Relational Databases Organizations use relational databases to store a variety of records pertaining to their business. These records can contain useful context that will help improve your GPT’s responses. For example, let’s say you are building a GPT to help users understand the status of an insurance claim. If the GPT can look up claims in a relational database based on a claims number, the GPT will be much more useful to the user. When building an action to integrate with a relational database, there are a few things to keep in mind: 1. Availability of REST APIs - Many relational databases do not natively expose a REST API for processing queries. In that case, you may need to build or buy middleware which can sit between your GPT and the database. - This middleware should do the following: - Accept a formal query string - Pass the query string to the database - Respond back to the requester with the returned records 2. Accessibility from the public internet - Unlike APIs which are designed to be accessed from the public internet, relational databases are traditionally designed to be used within an organization’s application infrastructure. Because GPTs are hosted on OpenAI’s infrastructure, you’ll need to make sure that any APIs you expose are accessible outside of your firewall. 3. Complex query strings - Relational databases uses formal query syntax like SQL to retrieve relevant records. This means that you need to provide additional instructions to the GPT indicating which query syntax is supported. The good news is that GPTs are usually very good at generating formal queries based on user input. 4. Database permissions - Although databases support user-level permissions, it is likely that your end users won’t have permission to access the database directly. If you opt to use a service account to provide access, consider giving the service account read-only permissions. This can avoid inadvertently overwriting or deleting existing data. Your goal is to get the GPT to write a formal query related to the user’s prompt, submit the query via the action, and then use the returned records to augment the response. ## Data retrieval using Vector Databases If you want to equip your GPT with the most relevant search results, you might consider integrating your GPT with a vector database which supports semantic search as described above. There are many managed and self hosted solutions available on the market, [see here for a partial list](https://github.com/openai/chatgpt-retrieval-plugin#choosing-a-vector-database). When building an action to integrate with a vector database, there are a few things to keep in mind: 1. Availability of REST APIs - Many relational databases do not natively expose a REST API for processing queries. In that case, you may need to build or buy middleware which can sit between your GPT and the database (more on middleware below). 2. Accessibility from the public internet - Unlike APIs which are designed to be accessed from the public internet, relational databases are traditionally designed to be used within an organization’s application infrastructure. Because GPTs are hosted on OpenAI’s infrastructure, you’ll need to make sure that any APIs you expose are accessible outside of your firewall. 3. Query embedding - As discussed above, vector databases typically accept a vector embedding (as opposed to plain text) as query input. This means that you need to use an embedding API to convert the query input into a vector embedding before you can submit it to the vector database. This conversion is best handled in the REST API gateway, so that the GPT can submit a plaintext query string. 4. Database permissions - Because vector databases store text chunks as opposed to full documents, it can be difficult to maintain user permissions which might have existed on the original source documents. Remember that any user who can access your GPT will have access to all of the text chunks in the database and plan accordingly. ### Middleware for vector databases As described above, middleware for vector databases typically needs to do two things: 1. Expose access to the vector database via a REST API 2. Convert plaintext query strings into vector embeddings ![Middleware for vector databases](https://cdn.openai.com/API/docs/images/actions-db-diagram.webp) The goal is to get your GPT to submit a relevant query to a vector database to trigger a semantic search, and then use the returned text chunks to augment the response. --- # Getting started with GPT Actions ## Weather.gov example The NSW (National Weather Service) maintains a [public API](https://www.weather.gov/documentation/services-web-api) that users can query to receive a weather forecast for any lat-long point. To retrieve a forecast, there’s 2 steps: 1. A user provides a lat-long to the api.weather.gov/points API and receives back a WFO (weather forecast office), grid-X, and grid-Y coordinates 2. Those 3 elements feed into the api.weather.gov/forecast API to retrieve a forecast for that coordinate For the purpose of this exercise, let’s build a Custom GPT where a user writes a city, landmark, or lat-long coordinates, and the Custom GPT answers questions about a weather forecast in that location. ## Step 1: Write and test Open API schema (using Actions GPT) A GPT Action requires an [Open API schema](https://swagger.io/specification/) to describe the parameters of the API call, which is a standard for describing APIs. OpenAI released a public [Actions GPT](https://chatgpt.com/g/g-TYEliDU6A-actionsgpt) to help developers write this schema. For example, go to the Actions GPT and ask: _“Go to https://www.weather.gov/documentation/services-web-api and read the documentation on that page. Build an Open API Schema for the /points/\{latitude},\{longitude} and /gridpoints/\{office}/\{gridX},\{gridY}/forecast” API calls”_ The above Actions GPT request Below is the full Open API Schema that the Actions GPT Returned: ```yaml openapi: 3.1.0 info: title: NWS Weather API description: Access to weather data including forecasts, alerts, and observations. version: 1.0.0 servers: - url: https://api.weather.gov description: Main API Server paths: /points/{latitude},{longitude}: get: operationId: getPointData summary: Get forecast grid endpoints for a specific location parameters: - name: latitude in: path required: true schema: type: number format: float description: Latitude of the point - name: longitude in: path required: true schema: type: number format: float description: Longitude of the point responses: "200": description: Successfully retrieved grid endpoints content: application/json: schema: type: object properties: properties: type: object properties: forecast: type: string format: uri forecastHourly: type: string format: uri forecastGridData: type: string format: uri /gridpoints/{office}/{gridX},{gridY}/forecast: get: operationId: getGridpointForecast summary: Get forecast for a given grid point parameters: - name: office in: path required: true schema: type: string description: Weather Forecast Office ID - name: gridX in: path required: true schema: type: integer description: X coordinate of the grid - name: gridY in: path required: true schema: type: integer description: Y coordinate of the grid responses: "200": description: Successfully retrieved gridpoint forecast content: application/json: schema: type: object properties: properties: type: object properties: periods: type: array items: type: object properties: number: type: integer name: type: string startTime: type: string format: date-time endTime: type: string format: date-time temperature: type: integer temperatureUnit: type: string windSpeed: type: string windDirection: type: string icon: type: string format: uri shortForecast: type: string detailedForecast: type: string ``` ChatGPT uses the **info** at the top (including the description in particular) to determine if this action is relevant for the user query. ```yaml info: title: NWS Weather API description: Access to weather data including forecasts, alerts, and observations. version: 1.0.0 ``` Then the **parameters** below further define each part of the schema. For example, we're informing ChatGPT that the _office_ parameter refers to the Weather Forecast Office (WFO). ```yaml /gridpoints/{office}/{gridX},{gridY}/forecast: get: operationId: getGridpointForecast summary: Get forecast for a given grid point parameters: - name: office in: path required: true schema: type: string description: Weather Forecast Office ID ``` **Key:** Pay special attention to the **schema names** and **descriptions** that you use in this Open API schema. ChatGPT uses those names and descriptions to understand (a) which API action should be called and (b) which parameter should be used. If a field is restricted to only certain values, you can also provide an "enum" with descriptive category names. While you can just try the Open API schema directly in a GPT Action, debugging directly in ChatGPT can be a challenge. We recommend using a 3rd party service, like [Postman](https://www.postman.com/), to test that your API call is working properly. Postman is free to sign up, verbose in its error-handling, and comprehensive in its authentication options. It even gives you the option of importing Open API schemas directly (see below). Choosing to import your API with Postman ## Step 2: Identify authentication requirements This Weather 3rd party service does not require authentication, so you can skip that step for this Custom GPT. For other GPT Actions that do require authentication, there are 2 options: API Key or OAuth. Asking ChatGPT can help you get started for most common applications. For example, if I needed to use OAuth to authenticate to Google Cloud, I can provide a screenshot and ask for details: _“I’m building a connection to Google Cloud via OAuth. Please provide instructions for how to fill out each of these boxes.”_ The above ChatGPT request Often, ChatGPT provides the correct directions on all 5 elements. Once you have those basics ready, try testing and debugging the authentication in Postman or another similar service. If you encounter an error, provide the error to ChatGPT, and it can usually help you debug from there. ## Step 3: Create the GPT Action and test Now is the time to create your Custom GPT. If you've never created a Custom GPT before, start at our [Creating a GPT guide](https://help.openai.com/en/articles/8554397-creating-a-gpt). 1. Provide a name, description, and image to describe your Custom GPT 2. Go to the Action section and paste in your Open API schema. Take a note of the Action names and json parameters when writing your instructions. 3. Add in your authentication settings 4. Go back to the main page and add in instructions There are many ways to write successful instructions: the most important thing is that the instructions enable the model to reflect the user's preferences. Typically, there are three sections: 1. _Context_ to explain to the model what the GPT Action(s) is doing 2. _Instructions_ on the sequence of steps – this is where you reference the Action name and any parameters the API call needs to pay attention to 3. _Additional Notes_ if there’s anything to keep in mind Here’s an example of the instructions for the Weather GPT. Notice how the instructions refer to the API action name and json parameters from the Open API schema. ```text **Context**: A user needs information related to a weather forecast of a specific location. **Instructions**: 1. The user will provide a lat-long point or a general location or landmark (e.g. New York City, the White House). If the user does not provide one, ask for the relevant location 2. If the user provides a general location or landmark, convert that into a lat-long coordinate. If required, browse the web to look up the lat-long point. 3. Run the "getPointData" API action and retrieve back the gridId, gridX, and gridY parameters. 4. Apply those variables as the office, gridX, and gridY variables in the "getGridpointForecast" API action to retrieve back a forecast 5. Use that forecast to answer the user's question **Additional Notes**: - Assume the user uses US weather units (e.g. Fahrenheit) unless otherwise specified - If the user says "Let's get started" or "What do I do?", explain the purpose of this Custom GPT ``` ### Test the GPT Action Next to each action, you'll see a **Test** button. Click on that for each action. In the test, you can see the detailed input and output of each API call. Available actions If your API call is working in a 3rd party tool like Postman and not in ChatGPT, there are a few possible culprits: - The parameters in ChatGPT are wrong or missing - An authentication issue in ChatGPT - Your instructions are incomplete or unclear - The descriptions in the Open API schema are unclear A preview response from testing the weather API call ## Step 4: Set up callback URL in the 3rd party app If your GPT Action uses OAuth Authentication, you’ll need to set up the callback URL in your 3rd party application. Once you set up a GPT Action with OAuth, ChatGPT provides you with a callback URL (this will update any time you update one of the OAuth parameters). Copy that callback URL and add it to the appropriate place in your application. Setting up a callback URL ## Step 5: Evaluate the Custom GPT Even though you tested the GPT Action in the step above, you still need to evaluate if the Instructions and GPT Action function in the way users expect. Try to come up with at least 5-10 representative questions (the more, the better) of an **“evaluation set”** of questions to ask your Custom GPT. **Key:** Test that the Custom GPT handles each one of your questions as you expect. An example question: _“What should I pack for a trip to the White House this weekend?”_ tests the Custom GPT’s ability to: (1) convert a landmark to a lat-long, (2) run both GPT Actions, and (3) answer the user’s question. The response to the above ChatGPT request, including weather data A continuation of the response above ## Common Debugging Steps _Challenge:_ The GPT Action is calling the wrong API call (or not calling it at all) - _Solution:_ Make sure the descriptions of the Actions are clear - and refer to the Action names in your Custom GPT Instructions _Challenge:_ The GPT Action is calling the right API call but not using the parameters correctly - _Solution:_ Add or modify the descriptions of the parameters in the GPT Action _Challenge:_ The Custom GPT is not working but I am not getting a clear error - _Solution:_ Make sure to test the Action - there are more robust logs in the test window. If that is still unclear, use Postman or another 3rd party service to better diagnose. _Challenge:_ The Custom GPT is giving an authentication error - _Solution:_ Make sure your callback URL is set up correctly. Try testing the exact same authentication settings in Postman or another 3rd party service _Challenge:_ The Custom GPT cannot handle more difficult / ambiguous questions - _Solution:_ Try to prompt engineer your instructions in the Custom GPT. See examples in our [prompt engineering guide](https://developers.openai.com/api/docs/guides/prompt-engineering) This concludes the guide to building a Custom GPT. Good luck building and leveraging the [OpenAI developer forum](https://community.openai.com/) if you have additional questions. --- # GPT Action authentication Actions offer different authentication schemas to accommodate various use cases. To specify the authentication schema for your action, use the GPT editor and select "None", "API Key", or "OAuth". By default, the authentication method for all actions is set to "None", but you can change this and allow different actions to have different authentication methods. ## No authentication We support flows without authentication for applications where users can send requests directly to your API without needing an API key or signing in with OAuth. Consider using no authentication for initial user interactions as you might experience a user drop off if they are forced to sign into an application. You can create a "signed out" experience and then move users to a "signed in" experience by enabling a separate action. ## API key authentication Just like how a user might already be using your API, we allow API key authentication through the GPT editor UI. We encrypt the secret key when we store it in our database to keep your API key secure. This approach is useful if you have an API that takes slightly more consequential actions than the no authentication flow but does not require an individual user to sign in. Adding API key authentication can protect your API and give you more fine-grained access controls along with visibility into where requests are coming from. ## OAuth Actions allow OAuth sign in for each user. This is the best way to provide personalized experiences and make the most powerful actions available to users. A simple example of the OAuth flow with actions will look like the following: - To start, select "Authentication" in the GPT editor UI, and select "OAuth". - You will be prompted to enter the OAuth client ID, client secret, authorization URL, token URL, and scope. - The client ID and secret can be simple text strings but should [follow OAuth best practices](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/). - We store an encrypted version of the client secret, while the client ID is available to end users. - OAuth requests will include the following information: `request={'grant_type': 'authorization_code', 'client_id': 'YOUR_CLIENT_ID', 'client_secret': 'YOUR_CLIENT_SECRET', 'code': 'abc123', 'redirect_uri': 'https://chat.openai.com/aip/{g-YOUR-GPT-ID-HERE}/oauth/callback'}` Note: `https://chatgpt.com/aip/{g-YOUR-GPT-ID-HERE}/oauth/callback` is also valid. - In order for someone to use an action with OAuth, they will need to send a message that invokes the action and then the user will be presented with a "Sign in to [domain]" button in the ChatGPT UI. - The `authorization_url` endpoint should return a response that looks like: `{ "access_token": "example_token", "token_type": "bearer", "refresh_token": "example_token", "expires_in": 59 }` - During the user sign in process, ChatGPT makes a request to your `authorization_url` using the specified `authorization_content_type`, we expect to get back an access token and optionally a [refresh token](https://auth0.com/learn/refresh-tokens) which we use to periodically fetch a new access token. - Each time a user makes a request to the action, the user’s token will be passed in the Authorization header: ("Authorization": "[Bearer/Basic] [user’s token]"). - We require that OAuth applications make use of the [state parameter](https://auth0.com/docs/secure/attack-protection/state-parameters#set-and-compare-state-parameter-values) for security reasons. Failure to login issues on Custom GPTs (Redirect URLs)? - Be sure to enable this redirect URL in your OAuth application: - #1 Redirect URL: `https://chat.openai.com/aip/{g-YOUR-GPT-ID-HERE}/oauth/callback` (Different domain possible for some clients) - #2 Redirect URL: `https://chatgpt.com/aip/{g-YOUR-GPT-ID-HERE}/oauth/callback` (Get your GPT ID in the URL bar of the ChatGPT UI once you save) if you have several GPTs you'd need to enable for each or a wildcard depending on risk tolerance. - Debug Note: Your Auth Provider will typically log failures (e.g. 'redirect_uri is not registered for client'), which helps debug login issues as well. --- # GPT Actions GPT Actions are stored in [Custom GPTs](https://openai.com/blog/introducing-gpts), which enable users to customize ChatGPT for specific use cases by providing instructions, attaching documents as knowledge, and connecting to 3rd party services. GPT Actions empower ChatGPT users to interact with external applications via RESTful APIs calls outside of ChatGPT simply by using natural language. They convert natural language text into the json schema required for an API call. GPT Actions are usually either used to do [data retrieval](https://developers.openai.com/api/docs/actions/data-retrieval) to ChatGPT (e.g. query a Data Warehouse) or take action in another application (e.g. file a JIRA ticket). ## How GPT Actions work At their core, GPT Actions leverage [Function Calling](https://developers.openai.com/api/docs/guides/function-calling) to execute API calls. Similar to ChatGPT's Data Analysis capability (which generates Python code and then executes it), they leverage Function Calling to (1) decide which API call is relevant to the user's question and (2) generate the json input necessary for the API call. Then finally, the GPT Action executes the API call using that json input. Developers can even specify the authentication mechanism of an action, and the Custom GPT will execute the API call using the third party app’s authentication. GPT Actions obfuscates the complexity of the API call to the end user: they simply ask a question in natural language, and ChatGPT provides the output in natural language as well. ## The Power of GPT Actions APIs allow for **interoperability** to enable your organization to access other applications. However, enabling users to access the right information from 3rd-party APIs can require significant overhead from developers. GPT Actions provide a viable alternative: developers can now simply describe the schema of an API call, configure authentication, and add in some instructions to the GPT, and ChatGPT provides the bridge between the user's natural language questions and the API layer. ## Simplified example The [getting started guide](https://developers.openai.com/api/docs/actions/getting-started) walks through an example using two API calls from [weather.gov](https://developers.openai.com/api/docs/actions/weather.gov) to generate a forecast: - /points/\{latitude},\{longitude} inputs lat-long coordinates and outputs forecast office (wfo) and x-y coordinates - /gridpoints/\{office}/\{gridX},\{gridY}/forecast inputs wfo,x,y coordinates and outputs a forecast Once a developer has encoded the json schema required to populate both of those API calls in a GPT Action, a user can simply ask "What I should pack on a trip to Washington DC this weekend?" The GPT Action will then figure out the lat-long of that location, execute both API calls in order, and respond with a packing list based on the weekend forecast it receives back. In this example, GPT Actions will supply api.weather.gov with two API inputs: /points API call: ```json { "latitude": 38.9072, "longitude": -77.0369 } ``` /forecast API call: ```json { "wfo": "LWX", "x": 97, "y": 71 } ``` ## Get started on building Check out the [getting started guide](https://developers.openai.com/api/docs/actions/getting-started) for a deeper dive on this weather example and our [actions library](https://developers.openai.com/api/docs/actions/actions-library) for pre-built example GPT Actions of the most common 3rd party apps. ## Additional information - Familiarize yourself with our [GPT policies](https://openai.com/policies/usage-policies#:~:text=or%20educational%20purposes.-,Building%20with%20ChatGPT,-Shared%20GPTs%20allow) - Check out the [GPT data privacy FAQs](https://help.openai.com/en/articles/8554402-gpts-data-privacy-faqs) - Find answers to [common GPT questions](https://help.openai.com/en/articles/8554407-gpts-faq) --- # GPT Actions library ## Purpose While GPT Actions should be significantly less work for an API developer to set up than an entire application using those APIs from scratch, there’s still some set up required to get GPT Actions up and running. A Library of GPT Actions is meant to provide guidance for building GPT Actions on common applications. ## Getting started If you’ve never built an action before, start by reading the [getting started guide](https://developers.openai.com/api/docs/actions/getting-started) first to understand better how actions work. Generally, this guide is meant for people with familiarity and comfort with calling API calls. For debugging help, try to explain your issues to ChatGPT - and include screenshots. ## How to access [The OpenAI Cookbook](https://developers.openai.com/cookbook) has a [directory](https://developers.openai.com/cookbook/topic/chatgpt) of 3rd party applications and middleware application. ### 3rd party Actions cookbook GPT Actions can integrate with HTTP services directly. GPT Actions leveraging SaaS API directly will authenticate and request resources directly from SaaS providers, such as [Google Drive](https://developers.openai.com/cookbook/examples/chatgpt/gpt_actions_library/gpt_action_google_drive) or [Snowflake](https://developers.openai.com/cookbook/examples/chatgpt/gpt_actions_library/gpt_action_snowflake_direct). ### Middleware Actions cookbook GPT Actions can benefit from having a middleware. It allows pre-processing, data formatting, data filtering or even connection to endpoints not exposed through HTTP (e.g: databases). Multiple middleware cookbooks are available describing an example implementation path, such as [Azure](https://developers.openai.com/cookbook/examples/chatgpt/gpt_actions_library/gpt_middleware_azure_function), [GCP](https://developers.openai.com/cookbook/examples/chatgpt/gpt_actions_library/gpt_middleware_google_cloud_function) and [AWS](https://developers.openai.com/cookbook/examples/chatgpt/gpt_actions_library/gpt_middleware_aws_function). ## Give us feedback Are there integrations that you’d like us to prioritize? Are there errors in our integrations? File a PR or issue on the cookbook page's github, and we’ll take a look. ## Contribute to our library If you’re interested in contributing to our library, please follow the below guidelines, then submit a PR in github for us to review. In general, follow the template similar to [this example GPT Action](https://developers.openai.com/cookbook/examples/chatgpt/gpt_actions_library/gpt_action_bigquery). Guidelines - include the following sections: - Application Information - describe the 3rd party application, and include a link to app website and API docs - Custom GPT Instructions - include the exact instructions to be included in a Custom GPT - OpenAPI Schema - include the exact OpenAPI schema to be included in the GPT Action - Authentication Instructions - for OAuth, include the exact set of items (authorization URL, token URL, scope, etc.); also include instructions on how to write the callback URL in the application (as well as any other steps) - FAQ and Troubleshooting - what are common pitfalls that users may encounter? Write them here and workarounds ## Disclaimers This action library is meant to be a guide for interacting with 3rd parties that OpenAI have no control over. These 3rd parties may change their API settings or configurations, and OpenAI cannot guarantee these Actions will work in perpetuity. Please see them as a starting point. This guide is meant for developers and people with comfort writing API calls. Non-technical users will likely find these steps challenging. --- # Production notes on GPT Actions ## Rate limits Consider implementing rate limiting on the API endpoints you expose. ChatGPT will respect 429 response codes and dynamically back off from sending requests to your action after receiving a certain number of 429's or 500's in a short period of time. ## Timeouts When making API calls during the actions experience, timeouts take place if the following thresholds are exceeded: - 45 seconds round trip for API calls ## Use TLS and HTTPS All traffic to your action must use TLS 1.2 or later on port 443 with a valid public certificate. ## IP egress ranges ChatGPT will call your action from one of the [published IP ranges](https://developers.openai.com/api/docs/guides/ip-addresses). You may wish to explicitly allowlist these IP addresses. ## Multiple authentication schemas When defining an action, you can mix a single authentication type (OAuth or API key) along with endpoints that do not require authentication. You can learn more about action authentication on our [actions authentication page](https://developers.openai.com/api/docs/actions/authentication). ## Open API specification limits Keep in mind the following limits in your OpenAPI specification, which are subject to change: - 300 characters max for each API endpoint description/summary field in API specification - 700 characters max for each API parameter description field in API specification ## Additional limitations There are a few limitations to be aware of when building with actions: - Custom headers are not supported - With the exception of Google, Microsoft and Adobe OAuth domains, all domains used in an OAuth flow must be the same as the domain used for the primary endpoints - Request and response payloads must be less than 100,000 characters each - Requests timeout after 45 seconds - Requests and responses can only contain text (no images or video) ## Consequential flag In the OpenAPI specification, you can now set certain endpoints as "consequential" as shown below: ```yaml paths: /todo: get: operationId: getTODOs description: Fetches items in a TODO list from the API. security: [] post: operationId: updateTODOs description: Mutates the TODO list. x-openai-isConsequential: true ``` A good example of a consequential action is booking a hotel room and paying for it on behalf of a user. - If the `x-openai-isConsequential` field is `true`, ChatGPT treats the operation as "must always prompt the user for confirmation before running" and don't show an "always allow" button (both are features of GPTs designed to give builders and users more control over actions). - If the `x-openai-isConsequential` field is `false`, ChatGPT shows the "always allow button". - If the field isn't present, ChatGPT defaults all GET operations to `false` and all other operations to `true` ## Best practices on feeding examples Here are some best practices to follow when writing your GPT instructions and descriptions in your schema, as well as when designing your API responses: 1. Your descriptions should not encourage the GPT to use the action when the user hasn't asked for your action's particular category of service. _Bad example_: > Whenever the user mentions any type of task, ask if they would like to use the TODO action to add something to their todo list. _Good example_: > The TODO list can add, remove and view the user's TODOs. 2. Your descriptions should not prescribe specific triggers for the GPT to use the action. ChatGPT is designed to use your action automatically when appropriate. _Bad example_: > When the user mentions a task, respond with "Would you like me to add this to your TODO list? Say 'yes' to continue." _Good example_: > [no instructions needed for this] 3. Action responses from an API should return raw data instead of natural language responses unless it's necessary. The GPT will provide its own natural language response using the returned data. _Bad example_: > I was able to find your todo list! You have 2 todos: get groceries and walk the dog. I can add more todos if you'd like! _Good example_: > \{ "todos": [ "get groceries", "walk the dog" ] } ## How GPT Action data is used GPT Actions connect ChatGPT to external apps. If a user interacts with a GPT’s custom action, ChatGPT may send parts of their conversation to the action’s endpoint. If you have questions or run into additional limitations, you can join the discussion on the [OpenAI developer forum](https://community.openai.com). --- # Sending and returning files with GPT Actions ## Sending files POST requests can include up to ten files (including DALL-E generated images) from the conversation. They will be sent as URLs which are valid for five minutes. For files to be part of your POST request, the parameter must be named `openaiFileIdRefs` and the description should explain to the model the type and quantity of the files which your API is expecting. The `openaiFileIdRefs` parameter will be populated with an array of JSON objects. Each object contains: - `name` The name of the file. This will be an auto generated name when created by DALL-E. - `id` A stable identifier for the file. - `mime_type` The mime type of the file. For user uploaded files this is based on file extension. - `download_link` The URL to fetch the file which is valid for five minutes. Here’s an example of an `openaiFileIdRefs` array with two elements: ```json [ { "name": "dalle-Lh2tg7WuosbyR9hk", "id": "file-XFlOqJYTPBPwMZE3IopCBv1Z", "mime_type": "image/webp", "download_link": "https://files.oaiusercontent.com/file-XFlOqJYTPBPwMZE3IopCBv1Z?se=2024-03-11T20%3A29%3A52Z&sp=r&sv=2021-08-06&sr=b&rscc=max-age%3D31536000%2C%20immutable&rscd=attachment%3B%20filename%3Da580bae6-ea30-478e-a3e2-1f6c06c3e02f.webp&sig=ZPWol5eXACxU1O9azLwRNgKVidCe%2BwgMOc/TdrPGYII%3D" }, { "name": "2023 Benefits Booklet.pdf", "id": "file-s5nX7o4junn2ig0J84r8Q0Ew", "mime_type": "application/pdf", "download_link": "https://files.oaiusercontent.com/file-s5nX7o4junn2ig0J84r8Q0Ew?se=2024-03-11T20%3A29%3A52Z&sp=r&sv=2021-08-06&sr=b&rscc=max-age%3D299%2C%20immutable&rscd=attachment%3B%20filename%3D2023%2520Benefits%2520Booklet.pdf&sig=Ivhviy%2BrgoyUjxZ%2BingpwtUwsA4%2BWaRfXy8ru9AfcII%3D" } ] ``` Actions can include files uploaded by the user, images generated by DALL-E, and files created by Code Interpreter. ### OpenAPI Example ```yaml /createWidget: post: operationId: createWidget summary: Creates a widget based on an image. description: Uploads a file reference using its file id. This file should be an image created by DALL·E or uploaded by the user. JPG, WEBP, and PNG are supported for widget creation. requestBody: required: true content: application/json: schema: type: object properties: openaiFileIdRefs: type: array items: type: string ``` While this schema shows `openaiFileIdRefs` as being an array of type `string`, at runtime this will be populated with an array of JSON objects as previously shown. ## Returning files Requests may return up to 10 files. Each file may be up to 10 MB and cannot be an image or video. These files will become part of the conversation similarly to if a user uploaded them, meaning they may be made available to code interpreter, file search, and sent as part of subsequent action invocations. In the web app users will see that the files have been returned and can download them. To return files, the body of the response must contain an `openaiFileResponse` parameter. This parameter must always be an array and must be populated in one of two ways. ### Inline option Each element of the array is a JSON object which contains: - `name` The name of the file. This will be visible to the user. - `mime_type` The MIME type of the file. This is used to determine eligibility and which features have access to the file. - `content` The base64 encoded contents of the file. Here’s an example of an openaiFileResponse array with two elements: ```json [ { "name": "example_document.pdf", "mime_type": "application/pdf", "content": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFIvRmlsdGVyIC9GbGF0ZURlY29kZT4+CnN0cmVhbQpHhD93PQplbmRzdHJlYW0KZW5kb2JqCg==" }, { "name": "sample_spreadsheet.csv", "mime_type": "text/csv", "content": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==" } ] ``` OpenAPI example ```yaml /papers: get: operationId: findPapers summary: Retrieve PDFs of relevant academic papers. description: Provided an academic topic, up to five relevant papers will be returned as PDFs. parameters: - in: query name: topic required: true schema: type: string description: The topic the papers should be about. responses: "200": description: Zero to five academic paper PDFs content: application/json: schema: type: object properties: openaiFileResponse: type: array items: type: object properties: name: type: string description: The name of the file. mime_type: type: string description: The MIME type of the file. content: type: string format: byte description: The content of the file in base64 encoding. ``` ### URL option Each element of the array is a URL referencing a file to be downloaded. The headers `Content-Disposition` and `Content-Type` must be set such that a file name and MIME type can be determined. The name of the file will be visible to the user. The MIME type of the file determines eligibility and which features have access to the file. There is a 10 second timeout for fetching each file. Here’s an example of an `openaiFileResponse` array with two elements: ```json [ "https://example.com/f/dca89f18-16d4-4a65-8ea2-ededced01646", "https://example.com/f/01fad6b0-635b-4803-a583-0f678b2e6153" ] ``` Here’s an example of the required headers for each URL: ```text Content-Type: application/pdf Content-Disposition: attachment; filename="example_document.pdf" ``` OpenAPI example ```yaml /papers: get: operationId: findPapers summary: Retrieve PDFs of relevant academic papers. description: Provided an academic topic, up to five relevant papers will be returned as PDFs. parameters: - in: query name: topic required: true schema: type: string description: The topic the papers should be about. responses: '200': description: Zero to five academic paper PDFs content: application/json: schema: type: object properties: openaiFileResponse: type: array items: type: string format: uri description: URLs to fetch the files. ``` --- # Assistants migration guide The Assistants API was officially sunset on August 26, 2026, and is no longer available. Use the [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses) for new integrations. Thank you to everyone who used the Assistants API. We appreciate everything you built and the feedback you shared along the way. Use this guide to migrate your integration to the [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses). Responses are simpler—send input items and get output items back. With the Responses API, you also get better performance and new features like [web search](https://developers.openai.com/api/docs/guides/tools-web-search), [MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp), and [computer use](https://developers.openai.com/api/docs/guides/tools-computer-use). This change also lets you manage conversations instead of passing back `previous_response_id`. ### What's changed?
Before Now Why?
`Assistants` `Prompts` Prompts hold configuration (model, tools, instructions) and are easier to version and update
`Threads` `Conversations` Streams of items instead of just messages
`Runs` `Responses` Responses send input items or use a conversation object and receive output items; tool call loops are explicitly managed
`Run steps` `Items` Generalized objects—can be messages, tool calls, outputs, and more
## From assistants to prompts Assistants were persistent API objects that bundled model choice, instructions, and tool declarations—created and managed entirely through the API. Their replacement, prompts, can only be created in the dashboard, where you can version them as you develop your product. ### Why this is helpful - **Portability and versioning**: You can snapshot, review, diff, and roll back prompt specs. You can also version a prompt, so your code can just point the latest version. - **Separation of concerns**: Your application code now handles orchestration (history pruning, tool loop, retries) while your prompt focuses on high‑level behavior and constraints (system guidance, tool availability, structured output schema, temperature defaults). - **Realtime compatibility**: The same prompt configuration can be reused when you connect through the Realtime API, giving you a single definition of behavior across chat, streaming, and low‑latency interactive sessions. - **Tool and output consistency**: Using prompts, every Responses or Realtime session you start inherits a consistent contract because prompts encapsulate tool schemas and structured output expectations. ### Practical migration steps 1. Identify each existing Assistant’s _instruction + tool_ bundle. 2. In the dashboard, recreate that bundle as a named prompt. 3. Store the prompt ID (or its exported spec) in source control so application code can refer to a stable identifier. 4. During rollout, run A/B tests by swapping prompt IDs—no need to create or delete assistant objects programmatically. Think of a prompt as a **versioned behavioral profile** to plug into either Responses or Realtime API. --- ## From threads to conversations A thread was a collection of messages stored server-side. Threads could _only_ store messages. Conversations store items, which can include messages, tool calls, tool outputs, and other data. ### Request example #### Python #### Thread object ```python thread = openai.beta.threads.create( messages=[{"role": "user", "content": "what are the 5 Ds of dodgeball?"}], metadata={"user_id": "peter_le_fleur"}, ) ``` #### Conversation object ```python conversation = openai.conversations.create( items=[{"role": "user", "content": "what are the 5 Ds of dodgeball?"}], metadata={"user_id": "peter_le_fleur"}, ) ``` #### Go #### Thread object (Go) ```go thread, err := client.Beta.Threads.New(context.Background(), openai.BetaThreadNewParams{ Messages: []openai.BetaThreadNewParamsMessage{{ Role: "user", Content: openai.BetaThreadNewParamsMessageContentUnion{ OfString: openai.String("what are the 5 Ds of dodgeball?"), }, }}, Metadata: shared.Metadata{"user_id": "peter_le_fleur"}, }) if err != nil { panic(err) } ``` #### Conversation object (Go) ```go conversation, err := client.Conversations.New(context.Background(), conversations.ConversationNewParams{ Items: []responses.ResponseInputItemUnionParam{ responses.ResponseInputItemParamOfMessage("what are the 5 Ds of dodgeball?", responses.EasyInputMessageRoleUser), }, Metadata: shared.Metadata{"user_id": "peter_le_fleur"}, }) if err != nil { panic(err) } ``` #### TypeScript #### Thread object (TypeScript) ```typescript import OpenAI from "openai"; const client = new OpenAI(); const thread = await client.beta.threads.create({ messages: [{ role: "user", content: "what are the 5 Ds of dodgeball?" }], metadata: { user_id: "peter_le_fleur" }, }); console.log(thread.id); ``` #### Conversation object (TypeScript) ```typescript import OpenAI from "openai"; const client = new OpenAI(); const conversation = await client.conversations.create({ items: [{ role: "user", content: "What are the five Ds of dodgeball?" }], metadata: { user_id: "peter_le_fleur" }, }); console.log(conversation.id); ``` ### Response example #### Thread object ```json { "id": "thread_CrXtCzcyEQbkAcXuNmVSKFs1", "object": "thread", "created_at": 1752855924, "metadata": { "user_id": "peter_le_fleur" }, "tool_resources": {} } ``` #### Conversation object ```json { "id": "conv_68542dc602388199a30af27d040cefd4087a04b576bfeb24", "object": "conversation", "created_at": 1752855924, "metadata": { "user_id": "peter_le_fleur" } } ``` --- ## From runs to responses Runs were asynchronous processes that executed against threads. See the example below. Responses are simpler: provide a set of input items to execute, and get a list of output items back. Responses are designed to be used alone, but you can also use them with prompt and conversation objects for storing context and configuration. ### Request example #### Python #### Run object ```python # Replace the illustrative IDs and URLs below with your own resource values. import time from openai import OpenAI openai = OpenAI() thread_id = "thread_123" assistant_id = "asst_123" run = openai.beta.threads.runs.create( thread_id=thread_id, assistant_id=assistant_id, ) while run.status in ("queued", "in_progress"): time.sleep(1) run = openai.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run.id) ``` #### Response object ```python # Replace the illustrative IDs and URLs below with your own resource values. from openai import OpenAI openai = OpenAI() conversation_id = "conv_123" response = openai.responses.create( model="gpt-6-astra", input=[{"role": "user", "content": "What are the 5 Ds of dodgeball?"}], conversation=conversation_id, ) ``` #### Go #### Run object (Go) ```go run, err := client.Beta.Threads.Runs.New(context.Background(), "thread_abc123", openai.BetaThreadRunNewParams{ AssistantID: "asst_abc123", }) if err != nil { panic(err) } for run.Status == openai.RunStatusQueued || run.Status == openai.RunStatusInProgress { time.Sleep(time.Second) run, err = client.Beta.Threads.Runs.Get(context.Background(), "thread_abc123", run.ID) if err != nil { panic(err) } } ``` #### Response object (Go) ```go _, err := client.Responses.New(context.Background(), responses.ResponseNewParams{ Model: "gpt-6-astra", Input: responses.ResponseNewParamsInputUnion{OfInputItemList: responses.ResponseInputParam{ responses.ResponseInputItemParamOfMessage("What are the 5 Ds of dodgeball?", responses.EasyInputMessageRoleUser), }}, Conversation: responses.ResponseNewParamsConversationUnion{OfString: openai.String("conv_abc123")}, }) if err != nil { panic(err) } ``` #### TypeScript #### Run object (TypeScript) ```typescript import { setTimeout } from "node:timers/promises"; import OpenAI from "openai"; const client = new OpenAI(); // Replace these illustrative IDs with your own resources. const threadId = "thread_123"; const assistantId = "asst_123"; let run = await client.beta.threads.runs.create(threadId, { assistant_id: assistantId, }); while (run.status === "queued" || run.status === "in_progress") { await setTimeout(1000); run = await client.beta.threads.runs.retrieve(run.id, { thread_id: threadId, }); } console.log(run.status); ``` #### Response object (TypeScript) ```typescript // Replace the illustrative IDs and URLs below with your own resource values. import OpenAI from "openai"; const client = new OpenAI(); const conversationId = "conv_123"; const response = await client.responses.create({ model: "gpt-6-astra", input: [{ role: "user", content: "What are the five Ds of dodgeball?" }], conversation: conversationId, }); console.log(response.output_text); ``` ### Response example #### Run object ```json { "id": "run_FKIpcs5ECSwuCmehBqsqkORj", "assistant_id": "asst_8fVY45hU3IM6creFkVi5MBKB", "cancelled_at": null, "completed_at": 1752857327, "created_at": 1752857322, "expires_at": null, "failed_at": null, "incomplete_details": null, "instructions": null, "last_error": null, "max_completion_tokens": null, "max_prompt_tokens": null, "metadata": {}, "model": "gpt-4.1", "object": "thread.run", "parallel_tool_calls": true, "required_action": null, "response_format": "auto", "started_at": 1752857324, "status": "completed", "thread_id": "thread_CrXtCzcyEQbkAcXuNmVSKFs1", "tool_choice": "auto", "tools": [], "truncation_strategy": { "type": "auto", "last_messages": null }, "usage": { "completion_tokens": 130, "prompt_tokens": 34, "total_tokens": 164, "prompt_token_details": { "cached_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0 } }, "temperature": 1.0, "top_p": 1.0, "tool_resources": {}, "reasoning_effort": null } ``` #### Response object ```json { "id": "resp_687a7b53036c819baad6012d58b39bcb074adcd9e24850fc", "created_at": 1752857427, "conversation": { "id": "conv_689667905b048191b4740501625afd940c7533ace33a2dab" }, "error": null, "incomplete_details": null, "instructions": null, "metadata": {}, "model": "gpt-5.5", "object": "response", "output": [ { "id": "msg_687a7b542948819ba79e77e14791ef83074adcd9e24850fc", "content": [ { "annotations": [], "text": "The \"5 Ds of Dodgeball\" are a humorous set of rules made famous by the 2004 comedy film **\"Dodgeball: A True Underdog Story.\"** In the movie, dodgeball coach Patches O’Houlihan teaches these basics to his team. The **5 Ds** are:\n\n1. **Dodge**\n2. **Duck**\n3. **Dip**\n4. **Dive**\n5. **Dodge** (yes, dodge is listed twice for emphasis!)\n\nIn summary: \n> **“If you can dodge a wrench, you can dodge a ball!”**\n\nThese 5 Ds are not official competitive rules, but have become a fun and memorable pop culture reference for the sport of dodgeball.", "type": "output_text", "logprobs": [] } ], "role": "assistant", "status": "completed", "type": "message" } ], "parallel_tool_calls": true, "temperature": 1.0, "tool_choice": "auto", "tools": [], "top_p": 1.0, "background": false, "max_output_tokens": null, "previous_response_id": null, "reasoning": { "effort": null, "generate_summary": null, "summary": null }, "service_tier": "scale", "status": "completed", "text": { "format": { "type": "text" } }, "truncation": "disabled", "usage": { "input_tokens": 17, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 150, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 167 }, "user": null, "max_tool_calls": null, "store": true, "top_logprobs": 0 } ``` --- ## Migrating your integration Follow the migration steps below to move from the Assistants API to the Responses API, without losing any feature support. ### 1. Create prompts from your assistants 1. Identify the most important assistant objects in your application. 1. Find these in the dashboard and click `Create prompt`. This will create a prompt object out of each existing assistant object. Reusable prompt objects are also being deprecated. If you use this migration path, review the [prompts deprecation timeline](https://developers.openai.com/api/docs/deprecations#2026-06-03-reusable-prompts) before adopting prompt objects in a long-lived integration. ### 2. Move new user chats over to conversations and responses Start new chats with the Conversations API and Responses API. To preserve earlier conversation history, use messages already stored by your application. The example below shows how thread history could be migrated before the sunset. The Assistants API call that retrieves thread messages no longer works; use your stored messages instead. ```python # Replace the illustrative IDs and URLs below with your own resource values. from openai import OpenAI openai = OpenAI() messages = [] thread_id = "thread_123" for page in openai.beta.threads.messages.list( thread_id=thread_id, order="asc" ).iter_pages(): messages += page.data items = [] for m in messages: item = {"role": m.role} item_content = [] for content in m.content: match content.type: case "text": item_content_type = "input_text" if m.role == "user" else "output_text" item_content += [ {"type": item_content_type, "text": content.text.value} ] case "image_url": item_content += [ { "type": "input_image", "image_url": content.image_url.url, "detail": content.image_url.detail, } ] item |= {"content": item_content} items.append(item) # create a conversation with your converted items conversation = openai.conversations.create(items=items) ``` ```ruby # Replace the illustrative IDs and URLs below with your own resource values. require "openai" client = OpenAI::Client.new thread_id = "thread_123" messages = client.beta.threads.messages.list(thread_id, order: :asc) items = [] messages.auto_paging_each do |message| content = message.content.filter_map do |part| case part when OpenAI::Models::Beta::Threads::TextContentBlock type = if message.role == OpenAI::Models::Beta::Threads::Message::Role::USER :input_text else :output_text end { type: type, text: part.text.value } when OpenAI::Models::Beta::Threads::ImageURLContentBlock { type: :input_image, image_url: part.image_url.url, detail: part.image_url.detail } end end items << { role: message.role, content: content } end conversation = client.conversations.create( items: items ) puts(conversation.id) ``` ## Comparing full examples Here are a few examples of integrations using both the Assistants API and the Responses API so you can see how they compare. ### User chat app Assistants API ```python # Replace the illustrative IDs and URLs below with your own resource values. threads_by_session: dict[str, str] = {} @app.post("/messages") async def message(message: Message): thread_id = threads_by_session.get(message.session_id) if thread_id is None: thread_id = openai.beta.threads.create().id threads_by_session[message.session_id] = thread_id openai.beta.threads.messages.create( thread_id=thread_id, role="user", content=message.content, ) example_assistant_id = "asst_123" run = openai.beta.threads.runs.create( assistant_id=example_assistant_id, thread_id=thread_id, ) while run.status in ("queued", "in_progress"): await asyncio.sleep(1) run = openai.beta.threads.runs.retrieve( thread_id=thread_id, run_id=run.id, ) messages = openai.beta.threads.messages.list( order="desc", limit=1, thread_id=thread_id, ) return {"content": messages.data[0].content} ``` ```ruby # Replace the illustrative IDs and URLs below with your own resource values. require "openai" client = OpenAI::Client.new assistant_id = "asst_123" threads_by_session = {} handle_message = lambda do |session_id:, content:| thread_id = threads_by_session[session_id] unless thread_id thread_id = client.beta.threads.create.id threads_by_session[session_id] = thread_id end client.beta.threads.messages.create( thread_id, role: :user, content: content ) run = client.beta.threads.runs.create( thread_id, assistant_id: assistant_id ) while [:queued, :in_progress].include?(run.status) sleep(1) run = client.beta.threads.runs.retrieve(run.id, thread_id: thread_id) end messages = client.beta.threads.messages.list( thread_id, order: :desc, limit: 1 ) { content: messages.data&.first&.content } end puts( handle_message.call( session_id: "example-session", content: "What are the five Ds of dodgeball?" ) ) ``` Responses API ```typescript // Replace the illustrative IDs and URLs below with your own resource values. import express from "express"; import OpenAI from "openai"; const app = express(); const client = new OpenAI(); const conversationsBySession = new Map>(); app.use(express.json()); app.post("/messages", async (request, response) => { const { content, session_id: sessionId } = request.body ?? {}; if ( typeof content !== "string" || !content.trim() || typeof sessionId !== "string" || !sessionId.trim() ) { response.status(400).json({ error: "content and session_id must be non-empty strings.", }); return; } let conversationIdPromise = conversationsBySession.get(sessionId); if (!conversationIdPromise) { conversationIdPromise = client.conversations .create() .then((conversation) => conversation.id) .catch((error) => { conversationsBySession.delete(sessionId); throw error; }); conversationsBySession.set(sessionId, conversationIdPromise); } const conversationId = await conversationIdPromise; const promptId = "pmpt_123"; const result = await client.responses.create({ prompt: { id: promptId }, input: [{ role: "user", content }], conversation: conversationId, }); response.json({ content: result.output_text }); }); app.listen(Number(process.env.OPENAI_EXAMPLE_PORT ?? 8000), "127.0.0.1"); ``` ```python # Replace the illustrative IDs and URLs below with your own resource values. conversations_by_session: dict[str, str] = {} @app.post("/messages") async def message(message: Message): if not message.session_id.strip() or not message.content.strip(): raise HTTPException( status_code=400, detail="session_id and content are required" ) conversation_id = conversations_by_session.get(message.session_id) if conversation_id is None: conversation_id = openai.conversations.create().id conversations_by_session[message.session_id] = conversation_id example_prompt_id = "pmpt_123" response = openai.responses.create( prompt={"id": example_prompt_id}, input=[{"role": "user", "content": message.content}], conversation=conversation_id, ) return {"content": response.output_text} ``` ```go func main() { client := openai.NewClient() server := &http.Server{ Addr: "127.0.0.1:8000", Handler: newChatHandler(client), ReadHeaderTimeout: 5 * time.Second, } log.Fatal(server.ListenAndServe()) } func newChatHandler(client openai.Client) http.Handler { var mutex sync.Mutex type sessionConversation struct { ready chan struct{} id string err error responseSlot chan struct{} } conversationsBySession := map[string]*sessionConversation{} mux := http.NewServeMux() mux.HandleFunc("POST /messages", func(w http.ResponseWriter, r *http.Request) { var message struct { Content string `json:"content"` SessionID string `json:"session_id"` } if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)).Decode(&message); err != nil || strings.TrimSpace(message.Content) == "" || strings.TrimSpace(message.SessionID) == "" { http.Error(w, "content and session_id must be non-empty strings", 400) return } // A demo session map. Bind session IDs to authenticated users in your application. mutex.Lock() session, exists := conversationsBySession[message.SessionID] if !exists { session = &sessionConversation{ready: make(chan struct{}), responseSlot: make(chan struct{}, 1)} conversationsBySession[message.SessionID] = session } mutex.Unlock() if !exists { go func() { // Creation belongs to the shared session, not the first HTTP request. ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) defer cancel() conversation, err := client.Conversations.New(ctx, conversations.ConversationNewParams{}) session.err = err if err == nil { session.id = conversation.ID } mutex.Lock() if err != nil { delete(conversationsBySession, message.SessionID) } close(session.ready) mutex.Unlock() }() } select { case <-r.Context().Done(): http.Error(w, "Request cancelled", http.StatusRequestTimeout) return case <-session.ready: } if session.err != nil { http.Error(w, "Could not create conversation", http.StatusInternalServerError) return } // Serialize responses within this conversation; waiting requests can cancel. select { case session.responseSlot <- struct{}{}: defer func() { <-session.responseSlot }() case <-r.Context().Done(): http.Error(w, "Request cancelled", http.StatusRequestTimeout) return } if r.Context().Err() != nil { http.Error(w, "Request cancelled", http.StatusRequestTimeout) return } // Replace this illustrative stored prompt ID with your prompt. result, err := client.Responses.New(r.Context(), responses.ResponseNewParams{ Prompt: responses.ResponsePromptParam{ ID: "pmpt_123", }, Input: responses.ResponseNewParamsInputUnion{ OfString: openai.String(message.Content), }, Conversation: responses.ResponseNewParamsConversationUnion{ OfString: openai.String(session.id), }, }) if err != nil || result.Status != responses.ResponseStatusCompleted { http.Error(w, "Could not create response", 500) return } w.Header().Set("Content-Type", "application/json") if err := json.NewEncoder(w).Encode(map[string]string{ "content": result.OutputText(), }); err != nil { log.Print(err) } }) return mux } ``` ```ruby # Replace the illustrative IDs and URLs below with your own resource values. require "openai" client = OpenAI::Client.new conversations_by_session = {} handle_message = lambda do |session_id:, content:| unless session_id.is_a?(String) && !session_id.strip.empty? && content.is_a?(String) && !content.strip.empty? raise ArgumentError, "session_id and content are required" end conversation_id = conversations_by_session[session_id] unless conversation_id conversation_id = client.conversations.create.id conversations_by_session[session_id] = conversation_id end response = client.responses.create( prompt: { id: "pmpt_123" }, input: [ { role: :user, content: content } ], conversation: conversation_id ) { content: response.output_text } end puts( handle_message.call( session_id: "example-session", content: "What are the five Ds of dodgeball?" ) ) ``` --- # Overview of OpenAI Crawlers OpenAI uses web crawlers (“robots”) and user agents to perform actions for its products, either automatically or triggered by user request. OpenAI uses OAI-SearchBot and GPTBot robots.txt tags to enable webmasters to manage how their sites and content work with AI. Each setting is independent of the others – for example, a webmaster can allow OAI-SearchBot in order to appear in search results while disallowing GPTBot to indicate that crawled content should not be used for training OpenAI’s generative AI foundation models. If your site has allowed both bots, we may use the results from just one crawl for both use cases to avoid duplicative crawling. For search results, please note it can take ~24 hours from a site’s robots.txt update for our systems to adjust. | User agent | Description & details | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | OAI-SearchBot | OAI-SearchBot is for search. OAI-SearchBot is used to surface websites in search results in ChatGPT's search features. Sites that are opted out of OAI-SearchBot will not be shown in ChatGPT search answers, though can still appear as navigational links. To help ensure your site appears in search results, we recommend allowing OAI-SearchBot in your site’s robots.txt file and allowing requests from our published IP ranges below. Example user-agent string (the version number may change): `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36; compatible; OAI-SearchBot/1.4; +https://openai.com/searchbot` When fetching robots.txt files, we may use a user-agent string with an additional `robots.txt` marker. The marker helps site owners more easily distinguish requests for the robots.txt file from requests for other resources, especially when their logs do not include paths: `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36; compatible; OAI-SearchBot/1.4; robots.txt; +https://openai.com/searchbot` Published IP addresses: https://openai.com/searchbot.json | OAI-AdsBot | OAI-AdsBot is used to validate the safety of web pages submitted as ads on ChatGPT. When you submit an ad, OpenAI may visit the landing page to ensure it complies with our policies. We may also use content from the landing page to determine when it's most relevant to show the ad to users. OAI-AdsBot only visits pages submitted as ads, and the data collected by OAI-AdsBot is not used to train generative AI foundation models. Full user-agent string: `Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; OAI-AdsBot/1.0; +https://openai.com/adsbot` Published IP addresses: https://openai.com/adsbot.json | GPTBot | GPTBot is used to make our generative AI foundation models more useful and safe. It is used to crawl content that may be used in training our generative AI foundation models. Disallowing GPTBot indicates a site’s content should not be used in training generative AI foundation models. Example user-agent string (the version number may change): `Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.4; +https://openai.com/gptbot` When fetching robots.txt files, we may add a `robots.txt` marker to the user-agent string to help site owners distinguish those requests from requests for other resources, especially when logs do not include paths. Published IP addresses: https://openai.com/gptbot.json | ChatGPT-User | OpenAI also uses ChatGPT-User for certain user actions in ChatGPT and [Custom GPTs](https://openai.com/index/introducing-gpts/). When users ask ChatGPT or a CustomGPT a question, it may visit a web page with a ChatGPT-User agent. ChatGPT users may also interact with external applications via [GPT Actions](https://developers.openai.com/api/docs/actions/introduction). ChatGPT-User is not used for crawling the web in an automatic fashion. Because these actions are initiated by a user, robots.txt rules may not apply. ChatGPT-User is not used to determine whether content may appear in Search. Please use OAI-SearchBot in robots.txt for managing Search opt outs and automatic crawl. Full user-agent string: `Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot` Published IP addresses: https://openai.com/chatgpt-user.json --- # Key concepts At OpenAI, protecting user data is fundamental to our mission. We do not train our models on inputs and outputs through our API. Learn more on our [API data privacy page](https://openai.com/api-data-privacy). ## Text generation models OpenAI's text generation models (often referred to as generative pre-trained transformers or "GPT" models for short), like [`gpt-6-astra`](https://developers.openai.com/api/docs/models/gpt-6-astra) and [`gpt-5.6-terra`](https://developers.openai.com/api/docs/models/gpt-5.6-terra), have been trained to understand natural and formal language. These models allow text outputs in response to their inputs. The inputs to these models are also referred to as "prompts." Designing a prompt is essentially how you "program" a model, usually by providing instructions or some examples of how to successfully complete a task. GPT models can be used across a great variety of tasks including content or code generation, summarization, conversation, creative writing, and more. Read more in our introductory [text generation guide](https://developers.openai.com/api/docs/guides/text) and in our [prompt engineering guide](https://developers.openai.com/api/docs/guides/prompt-engineering). ## Embeddings An embedding is a vector representation of a piece of data (e.g. some text) that is meant to preserve aspects of its content and/or its meaning. Chunks of data that are similar in some way will tend to have embeddings that are closer together than unrelated data. OpenAI offers text embedding models that take as input a text string and produce as output an embedding vector. Embeddings are useful for search, clustering, recommendations, anomaly detection, classification, and more. Read more about embeddings in our [embeddings guide](https://developers.openai.com/api/docs/guides/embeddings). ## Tokens Text generation and embeddings models process text in chunks called tokens. Tokens represent commonly occurring sequences of characters. For example, the string " tokenization" is decomposed as " token" and "ization", while a short and common word like " the" is represented as a single token. Note that in a sentence, the first token of each word typically starts with a space character. Check out our [tokenizer tool](https://platform.openai.com/tokenizer) to test specific strings and see how they are translated into tokens. As a rough rule of thumb, 1 token is approximately 4 characters or 0.75 words for English text. One limitation to keep in mind is that for a text generation model the prompt and the generated output combined must be no more than the model's maximum context length. For embeddings models (which do not output tokens), the input must be shorter than the model's maximum context length. The maximum context lengths for each text generation and embeddings model can be found in the [model index](https://developers.openai.com/api/docs/models). --- # Deprecations ## Overview As we launch safer and more capable models, we regularly retire older models. Software relying on OpenAI models may need occasional updates to keep working. Impacted customers will always be notified by email and in our documentation. Each model has one of three lifecycle states. - **Active.** You can use the model through the API. OpenAI hasn't announced its retirement. - **Deprecated.** OpenAI has announced the model's retirement. You can still use it until its shutdown date. - **Shutdown.** The model no longer accepts requests through the standard API. For deprecation notice periods and help migrating to a replacement model, see the [deprecation policy](#model-deprecation-notice-periods) and [migration guidance](#migration-guidance) below. See [feature and endpoint deprecations](#feature-and-endpoint-deprecations) for other upcoming API shutdowns. ## Upcoming deprecations | Shutdown date | Affected model | Status | Recommended replacement | Notice date | | ---------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- | ------------ | | **Dec 1, 2026** | `gpt-image-1-mini` | Deprecated | `gpt-image-2.6-sunburst` or `gpt-image-2.6-flare` | Jun 2, 2026 | | **Dec 1, 2026** | `gpt-image-1.5`, `gpt-image-1.5-2025-12-16` | Deprecated | `gpt-image-2.6-sunburst` or `gpt-image-2.6-flare` | Jun 2, 2026 | | **Dec 1, 2026** | `chatgpt-image-latest` | Deprecated | `gpt-image-2.6-sunburst` or `gpt-image-2.6-flare` | Jun 2, 2026 | | **Dec 11, 2026** | `gpt-5`, `gpt-5-2025-08-07` | Deprecated | `gpt-6.1-sol` | Jun 11, 2026 | | **Dec 11, 2026** | `gpt-5-mini`, `gpt-5-mini-2025-08-07` | Deprecated | `gpt-6.1-terra` | Jun 11, 2026 | | **Dec 11, 2026** | `gpt-5-nano`, `gpt-5-nano-2025-08-07` | Deprecated | `gpt-6-luna` | Jun 11, 2026 | | **Dec 11, 2026** | `gpt-5-pro`, `gpt-5-pro-2025-10-06` | Deprecated | `gpt-6.1-sol` (`reasoning.mode: pro`) in the Responses API | Jun 11, 2026 | | **Dec 11, 2026** | `o3`, `o3-2025-04-16` | Deprecated | `gpt-6.1-sol` | Jun 11, 2026 | | **Dec 11, 2026** | `o3-pro`, `o3-pro-2025-06-10` | Deprecated | `gpt-6.1-sol` (`reasoning.mode: pro`) in the Responses API | Jun 11, 2026 | | **Jan 6, 2027** | `tts-1` | Deprecated | `gpt-realtime-2.1-mini` | Oct 1, 2026 | | **Jan 6, 2027** | `tts-1-hd` | Deprecated | `gpt-realtime-2.1-mini` | Oct 1, 2026 | | **Jan 6, 2027** | `gpt-4o-mini-tts`, `gpt-4o-mini-tts-2025-03-20`, `gpt-4o-mini-tts-2025-12-15` | Deprecated | `gpt-realtime-2.1-mini` | Oct 1, 2026 | | **Jan 14, 2027** | GPT-4o (`gpt-4o-2024-08-06`, `gpt-4o-2024-11-20`) | Deprecated | `gpt-6-luna` | Oct 14, 2026 | | **Jan 14, 2027** | GPT-4o mini (`gpt-4o-mini-2024-07-18`) | Deprecated | `gpt-6-luna` | Oct 14, 2026 | | **Jan 14, 2027** | GPT-4.1 (`gpt-4.1-2025-04-14`) | Deprecated | `gpt-6-luna` | Oct 14, 2026 | | **Jan 14, 2027** | GPT-4.1 mini (`gpt-4.1-mini-2025-04-14`) | Deprecated | `gpt-6-luna` | Oct 14, 2026 | | **Jan 20, 2027** | `gpt-realtime`, `gpt-realtime-2025-08-28` | Deprecated | `gpt-realtime-2.1` | Jul 20, 2026 | | **Jan 20, 2027** | `gpt-audio`, `gpt-audio-2025-08-28` | Deprecated | `gpt-audio-1.5` | Jul 20, 2026 | | **Jan 20, 2027** | `gpt-4o-audio` | Deprecated | `gpt-audio-1.5` | Jul 20, 2026 | | **Jan 20, 2027** | `gpt-4o-realtime` | Deprecated | `gpt-realtime-2.1` | Jul 20, 2026 | | **Jan 20, 2027** | `gpt-realtime-mini`, `gpt-realtime-mini-2025-12-15` | Deprecated | `gpt-realtime-2.1-mini` | Jul 20, 2026 | | **Jan 20, 2027** | `gpt-audio-mini`, `gpt-audio-mini-2025-12-15` | Deprecated | `gpt-audio-1.5` | Jul 20, 2026 | | **Jan 20, 2027** | `gpt-4o-mini-realtime` | Deprecated | `gpt-realtime-2.1-mini` | Jul 20, 2026 | | **Jan 20, 2027** | `gpt-4o-mini-audio` | Deprecated | `gpt-audio-1.5` | Jul 20, 2026 | | **Jan 20, 2027** | `gpt-4o-mini-transcribe-2025-03-20` | Deprecated | `gpt-4o-mini-transcribe-2025-12-15` | Jul 20, 2026 | | **Feb 1, 2027** | `gpt-5.5-cyber-preview` | Deprecated | The most capable cyber model available to you. | Nov 5, 2026 | | **Feb 10, 2027** | `gpt-image-2`, `gpt-image-2-2026-04-21` | Deprecated | `gpt-image-2.6-sunburst` or `gpt-image-2.6-flare` | Nov 10, 2026 | | **Feb 26, 2027** | `whisper-1` | Deprecated | `gpt-live-transcribe` or `gpt-transcribe` | Aug 26, 2026 | | **Feb 26, 2027** | `gpt-4o-transcribe` | Deprecated | `gpt-live-transcribe` or `gpt-transcribe` | Aug 26, 2026 | | **Feb 26, 2027** | `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15` | Deprecated | `gpt-live-transcribe` or `gpt-transcribe` | Aug 26, 2026 | | **Feb 26, 2027** | `gpt-4o-transcribe-diarize` | Deprecated | `gpt-live-transcribe` or `gpt-transcribe` | Aug 26, 2026 | | **Apr 1, 2027** | `gpt-5.3-codex` | Deprecated | `gpt-6-sol` | Oct 1, 2026 | | **Apr 1, 2027** | `gpt-5.4-nano`, `gpt-5.4-nano-2026-03-17` | Deprecated | `gpt-6-luna` | Oct 1, 2026 | | **Apr 1, 2027** | `gpt-5.1`, `gpt-5.1-2025-11-13` | Deprecated | `gpt-6-sol` | Oct 1, 2026 | Fine-tuned versions of the models listed above follow the same shutdown schedule as their underlying base models. For speech migrations, see the [Realtime API guide](https://developers.openai.com/api/docs/guides/realtime) and the [transcription guide](https://developers.openai.com/api/docs/guides/transcription). ## Feature and endpoint deprecations | Shutdown date | Affected feature or endpoint | Status | Recommended replacement | Notice date | | ---------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | | **Nov 30, 2026** | `/v1/prompts` and reusable prompt objects | Deprecated | Move prompt content into your application code. [Migration guide](https://developers.openai.com/api/docs/guides/prompting/migrate-from-prompt-object) | Jun 3, 2026 | | **Nov 30, 2026** | Evals dashboard, API, and graders for eval workflows | Read-only | [Migrate to Promptfoo](https://developers.openai.com/cookbook/examples/evaluation/moving-from-openai-evals-to-promptfoo). For fine-tuning graders, see the [fine-tuning timeline](#update-to-openais-self-serve-fine-tuning). | Jun 3, 2026 | | **Nov 30, 2026** | Agent Builder | Deprecated | Agents SDK or ChatGPT Workspace Agents. [Migration guide](https://developers.openai.com/api/docs/guides/agent-builder/migrate-from-agent-builder). ChatKit remains available. | Jun 3, 2026 | | **Jan 6, 2027** | Self-serve fine-tuning job creation | Restricted access | See the [fine-tuning timeline](#update-to-openais-self-serve-fine-tuning). | May 7, 2026 | | **Feb 26, 2027** | `/v1/audio/translations` | Deprecated | [`/v1/realtime/translations`](https://developers.openai.com/api/docs/guides/realtime-translation) | Aug 26, 2026 | ## Model deprecation notice periods We provide advance notice before retiring models so customers have time to plan and migrate. When we announce a model deprecation, we notify customers who are actively using the model by email and document the deprecation on this page. Unless safety or compliance concerns require a faster timeline, we provide the following minimum notice periods before model retirement: - **Generally available models:** At least 6 months. - **Specialized variants of generally available models and image generation models:** At least 3 months. Examples include chat variants such as `gpt-5.1-chat-latest`, Codex variants such as `gpt-5.3-codex`, and deep research variants such as `o3-deep-research`. - **Preview models:** Preview models, identified by `preview` in the model name, may be retired with much shorter notice, such as 2 weeks. Examples include `computer-use-preview` and `gpt-4o-audio-preview`. We don't recommend using preview models for business-critical production workloads unless you can migrate on short notice. These notice periods give customers time to evaluate recommended replacement models, test application behavior, and complete migrations before a model is no longer available. In some cases, developers may be able to provision **dedicated capacity for continued access** after a model's shutdown date. To explore this option, [contact our sales team](https://openai.com/contact-sales/). ## Best practices - Check **the documentation** regularly for model deprecation updates. - To monitor model shutdowns **programmatically**, call the [List models endpoint](https://developers.openai.com/api/reference/resources/models/methods/list) (`GET /v1/models`) and check each model's optional `shutdown_date` field. The field is also available from the [Retrieve a model endpoint](https://developers.openai.com/api/reference/resources/models/methods/retrieve). ## Migration guidance - In Codex, invoke the [OpenAI Docs skill](https://github.com/openai/codex/tree/main/codex-rs/skills/src/assets/samples/openai-docs) with `$openai-docs` and ask it to migrate your project to the recommended replacement. - See the [**GPT-6 migration guide**](https://developers.openai.com/api/docs/guides/latest-model#gpt-6-astra-migration-quickstart). - Run representative requests against both models. Compare outputs, latency, and cost before switching production traffic to the replacement. ## Update to OpenAI’s self-serve fine-tuning On May 7th, 2026, we notified developers using OpenAI’s self-serve fine-tuning platform of updates to availability. Inference on fine-tuned models will continue to be available until the base models are deprecated. | Date | Update | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | May 7, 2026 | Creating fine-tuning jobs or training is not available to organizations that have not previously run fine-tuning. | | July 2, 2026 | Creating fine-tuning jobs is no longer available to organizations that have not run inference on a fine-tuned model in the past 60 days. | | Jan 6, 2027 | Active existing customers will no longer be able to create new fine-tuning jobs on this date. Inference on fine-tuned models will be disabled only when the underlying base model is deprecated. | ## Past deprecations | Shutdown date | Affected model or feature | Listed replacement | Notice date | | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------ | | **Oct 23, 2026** | `gpt-3.5-turbo-0125`, `gpt-3.5-turbo`, `gpt-3.5-turbo-completions` | `gpt-5.6-terra` | Apr 22, 2026 | | **Oct 23, 2026** | `gpt-4-0613`, `gpt-4`, `gpt-4-0613-completions`, `gpt-4-completions` | `gpt-5.6-sol` | Apr 22, 2026 | | **Oct 23, 2026** | `gpt-4-1106-preview` | `gpt-5.6-sol` | Apr 22, 2026 | | **Oct 23, 2026** | `gpt-4-turbo`, `gpt-4-turbo-2024-04-09`, `gpt-4-turbo-completions` | `gpt-5.6-sol` | Apr 22, 2026 | | **Oct 23, 2026** | `gpt-4.1-nano`, `gpt-4.1-nano-2025-04-14` | `gpt-5.6-luna` | Apr 22, 2026 | | **Oct 23, 2026** | `gpt-4o-2024-05-13` | `gpt-5.6-sol` | Apr 22, 2026 | | **Oct 23, 2026** | `gpt-image-1` | `gpt-image-2.5-sunburst` or `gpt-image-2.5-flare` | Apr 22, 2026 | | **Oct 23, 2026** | `o1-2024-12-17`, `o1` | `gpt-5.6-sol` | Apr 22, 2026 | | **Oct 23, 2026** | `o1-pro-2025-03-19`, `o1-pro` | `gpt-5.6-sol` (`reasoning.mode: pro`) | Apr 22, 2026 | | **Oct 23, 2026** | `o3-mini-2025-01-31`, `o3-mini` | `gpt-5.6-sol` | Apr 22, 2026 | | **Oct 23, 2026** | `ft-o4-mini-2025-04-16` | `gpt-5.6-terra` | Apr 22, 2026 | | **Oct 23, 2026** | `o4-mini-2025-04-16`, `o4-mini` | `gpt-5.6-terra` | Apr 22, 2026 | | **Oct 1, 2026** | `gpt-5.4-cyber` | The most capable cyber model available to you. | Sep 11, 2026 | | **Sep 28, 2026** | `gpt-3.5-turbo-instruct` | `gpt-5.6-terra` | Sep 26, 2025 | | **Sep 28, 2026** | `babbage-002` | `gpt-5.6-terra` | Sep 26, 2025 | | **Sep 28, 2026** | `davinci-002` | `gpt-5.6-terra` | Sep 26, 2025 | | **Sep 28, 2026** | `gpt-3.5-turbo-1106` | `gpt-5.6-terra` | Sep 26, 2025 | | **Sep 24, 2026** | Videos API | No one-to-one replacement | Mar 24, 2026 | | **Sep 24, 2026** | `sora-2` | No one-to-one replacement | Mar 24, 2026 | | **Sep 24, 2026** | `sora-2-pro` | No one-to-one replacement | Mar 24, 2026 | | **Sep 24, 2026** | `sora-2-2025-10-06` | No one-to-one replacement | Mar 24, 2026 | | **Sep 24, 2026** | `sora-2-2025-12-08` | No one-to-one replacement | Mar 24, 2026 | | **Sep 24, 2026** | `sora-2-pro-2025-10-06` | No one-to-one replacement | Mar 24, 2026 | | **Aug 26, 2026** | Assistants API | Responses API and Conversations API ([migration guide](https://developers.openai.com/api/docs/assistants/migration)) | Aug 26, 2025 | | **Aug 10, 2026** | `gpt-5.2-chat-latest` | `gpt-5.6-sol` | May 8, 2026 | | **Aug 10, 2026** | `gpt-5.3-chat-latest` | `gpt-5.6-sol` | May 8, 2026 | | **Jul 23, 2026** | `computer-use-preview-2025-03-11`, `computer-use-preview` | `gpt-5.6-terra` | Apr 22, 2026 | | **Jul 23, 2026** | `gpt-4o-mini-search-preview-2025-03-11` | `gpt-5.6-terra` | Apr 22, 2026 | | **Jul 23, 2026** | `gpt-4o-search-preview-2025-03-11` | `gpt-5.6-terra` | Apr 22, 2026 | | **Jul 23, 2026** | `gpt-5-chat-latest` | `gpt-5.6-sol` | Apr 22, 2026 | | **Jul 23, 2026** | `gpt-5-codex` | `gpt-5.6-sol` | Apr 22, 2026 | | **Jul 23, 2026** | `gpt-5.1-chat-latest` | `gpt-5.6-sol` | Apr 22, 2026 | | **Jul 23, 2026** | `gpt-5.1-codex` | `gpt-5.6-sol` | Apr 22, 2026 | | **Jul 23, 2026** | `gpt-5.1-codex-max` | `gpt-5.6-sol` | Apr 22, 2026 | | **Jul 23, 2026** | `gpt-5.1-codex-mini` | `gpt-5.6-terra` | Apr 22, 2026 | | **Jul 23, 2026** | `gpt-audio-mini-2025-10-06` | `gpt-audio-1.5` | Apr 22, 2026 | | **Jul 23, 2026** | `gpt-realtime-mini-2025-10-06` | `gpt-realtime-2.1-mini` | Apr 22, 2026 | | **Jul 23, 2026** | `o3-deep-research-2025-06-26`, `o3-deep-research` | `gpt-5.6-sol` | Apr 22, 2026 | | **Jul 23, 2026** | `o4-mini-deep-research-2025-06-26`, `o4-mini-deep-research` | `gpt-5.6-sol` | Apr 22, 2026 | | **Jul 23, 2026** | `gpt-5.2-codex` | `gpt-5.6-sol` | Apr 22, 2026 | | **May 12, 2026** | `dall-e-2` | `gpt-image-2`, `gpt-image-1`, or `gpt-image-1-mini` | Nov 14, 2025 | | **May 12, 2026** | `dall-e-3` | `gpt-image-2`, `gpt-image-1`, or `gpt-image-1-mini` | Nov 14, 2025 | | **May 12, 2026** | OpenAI-Beta: realtime=v1 | [Realtime API migration guide](https://developers.openai.com/api/docs/guides/realtime#beta-to-ga-migration) | Sep 15, 2025 | | **May 7, 2026** | `gpt-4o-realtime-preview` | `gpt-realtime-1.5` | Sep 15, 2025 | | **May 7, 2026** | `gpt-4o-realtime-preview-2025-06-03` | `gpt-realtime-1.5` | Sep 15, 2025 | | **May 7, 2026** | `gpt-4o-realtime-preview-2024-12-17` | `gpt-realtime-1.5` | Sep 15, 2025 | | **May 7, 2026** | `gpt-4o-mini-realtime-preview` | `gpt-realtime-mini` | Sep 15, 2025 | | **May 7, 2026** | `gpt-4o-audio-preview` | `gpt-audio-1.5` | Sep 15, 2025 | | **May 7, 2026** | `gpt-4o-mini-audio-preview` | `gpt-audio-mini` | Sep 15, 2025 | | **Mar 26, 2026** | `gpt-4-0314` | `gpt-5`, or `gpt-4.1` for latency-sensitive tasks that don't require reasoning | Sep 26, 2025 | | **Mar 26, 2026** | `gpt-4-0125-preview` (including `gpt-4-turbo-preview` and `gpt-4-turbo-preview-completions`, which point to this snapshot) | `gpt-5`, or `gpt-4.1` for latency-sensitive tasks that don't require reasoning | Sep 26, 2025 | | **Feb 17, 2026** | `chatgpt-4o-latest` | `gpt-5.1-chat-latest` | Nov 18, 2025 | | **Feb 12, 2026** | `codex-mini-latest` | `gpt-5-codex-mini` | Nov 17, 2025 | | **Oct 27, 2025** | `text-moderation-007` | `omni-moderation` | Apr 28, 2025 | | **Oct 27, 2025** | `text-moderation-stable` | `omni-moderation` | Apr 28, 2025 | | **Oct 27, 2025** | `text-moderation-latest` | `omni-moderation` | Apr 28, 2025 | | **Oct 27, 2025** | `o1-mini` | `o4-mini` | Apr 28, 2025 | | **Oct 10, 2025** | `gpt-4o-realtime-preview-2024-10-01` | `gpt-realtime-1.5` | Jun 10, 2025 | | **Oct 10, 2025** | `gpt-4o-audio-preview-2024-10-01` | `gpt-audio-1.5` | Jun 10, 2025 | | **Jul 28, 2025** | `o1-preview` | `o3` | Apr 28, 2025 | | **Jul 14, 2025** | `gpt-4.5-preview` | `gpt-4.1` | Apr 14, 2025 | | **Jun 6, 2025** | `gpt-4-32k` Historical price $60.00 / 1M input tokens + $120 / 1M output tokens | `gpt-4o` | Jun 6, 2024 | | **Jun 6, 2025** | `gpt-4-32k-0613` Historical price $60.00 / 1M input tokens + $120 / 1M output tokens | `gpt-4o` | Jun 6, 2024 | | **Jun 6, 2025** | `gpt-4-32k-0314` Historical price $60.00 / 1M input tokens + $120 / 1M output tokens | `gpt-4o` | Jun 13, 2023 | | **Dec 18, 2024** | OpenAI-Beta: assistants=v1 | OpenAI-Beta: assistants=v2 ([migration guide](https://developers.openai.com/api/docs/assistants/migration)) | Oct 2, 2024 | | **Dec 6, 2024** | `gpt-4-vision-preview` Historical price $10.00 / 1M input tokens + $30 / 1M output tokens | `gpt-4o` | Jun 6, 2024 | | **Dec 6, 2024** | `gpt-4-1106-vision-preview` Historical price $10.00 / 1M input tokens + $30 / 1M output tokens | `gpt-4o` | Jun 6, 2024 | | **Oct 28, 2024** | New fine-tuning training on `babbage-002` | `gpt-4o-mini` | Aug 29, 2024 | | **Oct 28, 2024** | New fine-tuning training on `davinci-002` | `gpt-4o-mini` | Aug 29, 2024 | | **Sep 13, 2024** | `gpt-3.5-turbo-0613` Historical price $1.50 / 1M input tokens + $2.00 / 1M output tokens | `gpt-3.5-turbo` | Nov 6, 2023 | | **Sep 13, 2024** | `gpt-3.5-turbo-16k-0613` Historical price $3.00 / 1M input tokens + $4.00 / 1M output tokens | `gpt-3.5-turbo` | Nov 6, 2023 | | **Sep 13, 2024** | `gpt-3.5-turbo-0301` Historical price $15.00 / 1M input tokens + $20.00 / 1M output tokens | `gpt-3.5-turbo` | Jun 13, 2023 | | **Jun 13, 2024** Earliest estimate | `gpt-4-0314` Historical price $30.00 / 1M input tokens + $60.00 / 1M output tokens | `gpt-4o` | Jun 13, 2023 | | **Jan 4, 2024** | `/v1/fine-tunes` | `/v1/fine_tuning/jobs` | Aug 22, 2023 | | **Jan 4, 2024** | `text-ada-001` Historical price $0.40 / 1M tokens | `gpt-3.5-turbo-instruct` | Jul 6, 2023 | | **Jan 4, 2024** | `text-babbage-001` Historical price $0.50 / 1M tokens | `gpt-3.5-turbo-instruct` | Jul 6, 2023 | | **Jan 4, 2024** | `text-curie-001` Historical price $2.00 / 1M tokens | `gpt-3.5-turbo-instruct` | Jul 6, 2023 | | **Jan 4, 2024** | `text-davinci-001` Historical price $20.00 / 1M tokens | `gpt-3.5-turbo-instruct` | Jul 6, 2023 | | **Jan 4, 2024** | `text-davinci-002` Historical price $20.00 / 1M tokens | `gpt-3.5-turbo-instruct` | Jul 6, 2023 | | **Jan 4, 2024** | `text-davinci-003` Historical price $20.00 / 1M tokens | `gpt-3.5-turbo-instruct` | Jul 6, 2023 | | **Jan 4, 2024** | `ada` Historical price $0.40 / 1M tokens | `babbage-002` | Jul 6, 2023 | | **Jan 4, 2024** | `babbage` Historical price $0.50 / 1M tokens | `babbage-002` | Jul 6, 2023 | | **Jan 4, 2024** | `curie` Historical price $2.00 / 1M tokens | `davinci-002` | Jul 6, 2023 | | **Jan 4, 2024** | `davinci` Historical price $20.00 / 1M tokens | `davinci-002` | Jul 6, 2023 | | **Jan 4, 2024** | `code-davinci-002` (base GPT models) | `gpt-3.5-turbo-instruct` | Jul 6, 2023 | | **Jan 4, 2024** | `text-davinci-edit-001` | `gpt-4o` | Jul 6, 2023 | | **Jan 4, 2024** | `code-davinci-edit-001` | `gpt-4o` | Jul 6, 2023 | | **Jan 4, 2024** | `/v1/edits` | `/v1/chat/completions` | Jul 6, 2023 | | **Jan 4, 2024** | Fine-tuning on `ada` Training price $0.40 / 1M tokens. Usage price $1.60 / 1M tokens | `babbage-002` | Jul 6, 2023 | | **Jan 4, 2024** | Fine-tuning on `babbage` Training price $0.60 / 1M tokens. Usage price $2.40 / 1M tokens | `babbage-002` | Jul 6, 2023 | | **Jan 4, 2024** | Fine-tuning on `curie` Training price $3.00 / 1M tokens. Usage price $12.00 / 1M tokens | `davinci-002` | Jul 6, 2023 | | **Jan 4, 2024** | Fine-tuning on `davinci` Training price $30.00 / 1M tokens. Usage price $120.00 / 1K tokens | `davinci-002`, `gpt-3.5-turbo`, `gpt-4o` | Jul 6, 2023 | | **Jan 4, 2024** | `text-similarity-ada-001` Historical price $4.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `text-search-ada-doc-001` Historical price $4.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `text-search-ada-query-001` Historical price $4.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `code-search-ada-code-001` Historical price $4.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `code-search-ada-text-001` Historical price $4.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `text-similarity-babbage-001` Historical price $5.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `text-search-babbage-doc-001` Historical price $5.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `text-search-babbage-query-001` Historical price $5.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `code-search-babbage-code-001` Historical price $5.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `code-search-babbage-text-001` Historical price $5.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `text-similarity-curie-001` Historical price $20.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `text-search-curie-doc-001` Historical price $20.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `text-search-curie-query-001` Historical price $20.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `text-similarity-davinci-001` Historical price $200.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `text-search-davinci-doc-001` Historical price $200.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Jan 4, 2024** | `text-search-davinci-query-001` Historical price $200.00 / 1M tokens | `text-embedding-3-small` | Jul 6, 2023 | | **Mar 23, 2023** | `code-davinci-002` (Codex models) | `gpt-4o` | Mar 20, 2023 | | **Mar 23, 2023** | `code-davinci-001` | `gpt-4o` | Mar 20, 2023 | | **Mar 23, 2023** | `code-cushman-002` | `gpt-4o` | Mar 20, 2023 | | **Mar 23, 2023** | `code-cushman-001` | `gpt-4o` | Mar 20, 2023 | | **Dec 3, 2022** | `/v1/engines` | [/v1/models](https://platform.openai.com/docs/api-reference/models/list) | Jun 3, 2022 | | **Dec 3, 2022** | `/v1/search` | [View transition guide](https://help.openai.com/en/articles/6272952-search-transition-guide) | Jun 3, 2022 | | **Dec 3, 2022** | `/v1/classifications` | [View transition guide](https://help.openai.com/en/articles/6272941-classifications-transition-guide) | Jun 3, 2022 | | **Dec 3, 2022** | `/v1/answers` | [View transition guide](https://help.openai.com/en/articles/6233728-answers-transition-guide) | Jun 3, 2022 | ### Historical notes - Fine-tuned versions of the [legacy GPT models shut down in October 2026](https://developers.openai.com/api/docs/deprecations#2026-04-22-legacy-gpt-model-snapshots) followed the same shutdown schedule as their underlying base models. - The [`codex-mini-latest` shutdown](https://developers.openai.com/api/docs/deprecations#2025-11-17-codex-mini-latest-model-snapshot) also ended support for the legacy local shell tool. For new integrations, use the [shell tool](https://developers.openai.com/api/docs/guides/tools-shell). - The [Assistants API notice](https://developers.openai.com/api/docs/deprecations#2025-08-20-assistants-api) followed the release of the Responses API in [March 2025](https://developers.openai.com/api/docs/changelog). We first announced plans to retire the Assistants API v1 beta when we [released v2 in April 2024](https://developers.openai.com/api/docs/assistants/migration). - The October 2024 shutdown for [fine-tuning training on `babbage-002` and `davinci-002`](https://developers.openai.com/api/docs/deprecations#2024-08-29-fine-tuning-training-on-babbage-002-and-davinci-002-models) applied to creating new fine-tuned models. Existing fine-tuned models were unaffected by that change. - The June 6, 2024 notice reconfirmed the retirement of `gpt-4-32k-0314`. Starting June 17, 2024, access to the GPT-4-32K and Vision Preview models and the GPT-3.5 Turbo snapshots announced in [November 2023](https://openai.com/blog/new-models-and-developer-products-announced-at-devday) was limited to existing users. Existing fine-tuned models from those GPT-3.5 Turbo snapshots were unaffected by that shutdown. - The [legacy fine-tunes endpoint shutdown](https://developers.openai.com/api/docs/deprecations#2023-08-22-fine-tunes-endpoint) also removed access to models trained with that endpoint. Developers had to train new models through the [updated fine-tuning API](https://openai.com/blog/gpt-3-5-turbo-fine-tuning-and-api-updates). - The [July 2023 announcement](https://openai.com/blog/gpt-4-api-general-availability) covered older GPT-3 and GPT-3.5 models served through the completions endpoint and first-generation text embedding models. See the [pricing page](https://openai.com/api/pricing) for current model pricing. - The [June 2023 announcement](https://openai.com/blog/function-calling-and-other-api-updates) gave an earliest retirement date of June 13, 2024 for the original chat models. Starting January 10, 2024, access was limited to existing users. See the [March 2026 shutdown notice](https://developers.openai.com/api/docs/deprecations#2025-09-26-legacy-gpt-model-snapshots-march-2026-shutdown) for the final shutdown date of `gpt-4-0314`. --- # GPT Release Notes Keep track of updates to OpenAI GPTs. You can also view all of the broader [ChatGPT releases](https://help.openai.com/en/articles/6825453-chatgpt-release-notes) which is used to share new features and capabilities. This page is maintained in a best effort fashion and may not reflect all changes being made. ### May 13th, 2024 - Actions can [return](https://developers.openai.com/api/docs/actions/sending-files#returning-files) up to 10 files per request to be integrated into the conversation ### April 8th, 2024 - Files created by Code Interpreter can now be [included](https://developers.openai.com/api/docs/actions/sending-files#sending-files) in POST requests ### Mar 18th, 2024 - GPT Builders can view and restore previous versions of their GPTs ### Mar 15th, 2024 - POST requests can [include up to ten files](https://developers.openai.com/api/docs/actions/sending-files#sending-files) (including DALL-E generated images) from the conversation ### Feb 22nd, 2024 - Users can now rate GPTs, which provides feedback for builders and signal for otherusers in the Store - Users can now leave private feedback for Builders if/when they opt in - Every GPT now has an About page with information about the GPT including Rating, Category, Conversation Count, Starter Prompts, and more - Builders can now link their social profiles from Twitter, LinkedIn, and GitHub to their GPT ### Jan 10th, 2024 - The [GPT Store](https://openai.com/blog/introducing-gpts) launched publicly, with categories and various leaderboards ### Nov 6th, 2023 - [GPTs](https://openai.com/blog/introducing-gpts) allow users to customize ChatGPT for various use cases and share these with other users --- # Actions in ChatKit Actions are a way for the ChatKit SDK frontend to trigger a streaming response without the user submitting a message. They can also be used to trigger side-effects outside ChatKit SDK. ## Triggering actions ### In response to user interaction with widgets Actions can be triggered by attaching an `ActionConfig` to any widget node that supports it. For example, you can respond to click events on Buttons. When a user clicks on this button, the action will be sent to your server where you can update the widget, run inference, stream new thread items, etc. ```python button = Button( label="Example", onClickAction=ActionConfig( type="example", payload={"id": 123}, ), ) ``` Actions can also be sent imperatively by your frontend with `sendCustomAction()`. This is probably most useful when you need ChatKit to respond to interaction happening outside ChatKit, but it can also be used to chain actions when you need to respond on both the client and the server (more on that below). ```typescript await chatKit.sendCustomAction({ type: "example", payload: { id: 123 }, }); ``` ## Handling actions ### On the server By default, actions are sent to your server. You can handle actions on your server by implementing the `action` method on `ChatKitServer`. ```python class MyChatKitServer(ChatKitServer[RequestContext]): async def action( self, thread: ThreadMetadata, action: Action[str, Any], sender: WidgetItem | None, context: RequestContext, ) -> AsyncIterator[Event]: if action.type == "example": await do_thing(action.payload["id"]) # Often you'll want to add a HiddenContextItem so the model # can see that the user did something. await self.store.add_thread_item( thread.id, HiddenContextItem( id=self.store.generate_item_id("message", thread, context), thread_id=thread.id, created_at=datetime.now(), content="The user did a thing", ), context, ) # Then you might want to run inference to stream a response # back to the user. async for event in self.generate(context, thread): yield event ``` Treat actions and their payloads as untrusted data because the client sends them to your server. ### Client Sometimes you’ll want to handle actions in your client integration. To do that you need to specify that the action should be sent to your client-side action handler by adding `handler="client"` to the `ActionConfig`. ```python button = Button( label="Example", onClickAction=ActionConfig(type="example", payload={"id": 123}, handler="client"), ) ``` Then, when the action is triggered, it will then be passed to a callback that you provide when instantiating ChatKit. ```typescript async function handleWidgetAction(action: { type: string }) { if (action.type === "example") { const res = await doSomething(action); // You can fire off actions to your server from here as well. // For example, stream new thread items or update a widget. await chatKit.sendCustomAction({ type: "example_complete", payload: res, }); } } chatKit.setOptions({ // Other options... widgets: { onAction: handleWidgetAction }, }); ``` ## Strongly typed actions By default `Action` and `ActionConfig` are not strongly typed. However, we do expose a `create` helper on `Action` that generates `ActionConfig`s from a set of strongly-typed actions. ```python class ExamplePayload(BaseModel): id: int ExampleAction = Action[Literal["example"], ExamplePayload] OtherAction = Action[Literal["other"], None] AppAction = Annotated[ ExampleAction | OtherAction, Field(discriminator="type"), ] ActionAdapter: TypeAdapter[AppAction] = TypeAdapter(AppAction) def parse_app_action(action: Action[str, Any]) -> AppAction: return ActionAdapter.validate_python(action) # Usage in a widget # Action provides a create helper which makes it easy to generate # ActionConfigs from strongly typed actions. button = Button( label="Example", onClickAction=ExampleAction.create(ExamplePayload(id=123)), ) # usage in action handler class MyChatKitServer(ChatKitServer[RequestContext]): async def action( self, thread: ThreadMetadata, action: Action[str, Any], sender: WidgetItem | None, context: RequestContext, ) -> AsyncIterator[Event]: # add custom error handling if needed app_action = parse_app_action(action) if app_action.type == "example": await do_thing(app_action.payload.id) yield ThreadItemDoneEvent( item=AssistantMessageItem( id=self.store.generate_item_id("message", thread, context), thread_id=thread.id, created_at=datetime.now(), content=[AssistantMessageContent(text="Action complete.")], ) ) ``` ## Use widgets and actions to create custom forms When widget nodes that take user input are mounted inside a `Form`, the values from those fields will be included in the `payload` of all actions that originate from within the `Form`. Form values are keyed in the `payload` by their `name` e.g. - `Select(name="title")` → `action.payload.title` - `Select(name="todo.title")` → `action.payload.todo.title` ```python form = Form( direction="col", onSubmitAction=ActionConfig( type="update_todo", payload={"id": todo.id}, ), children=[ Title(value="Edit Todo"), Text(value="Title", color="secondary", size="sm"), Text( value=todo.title, editable=EditableProps(name="title", required=True), ), Text(value="Description", color="secondary", size="sm"), Text( value=todo.description, editable=EditableProps(name="description"), ), Button(label="Save", submit=True), ], ) class MyChatKitServer(ChatKitServer[RequestContext]): async def action( self, thread: ThreadMetadata, action: Action[str, Any], sender: WidgetItem | None, context: RequestContext, ) -> AsyncIterator[Event]: if action.type == "update_todo": todo_id = action.payload["id"] # Any action that originates from within the Form will # include title and description. title = action.payload["title"] description = action.payload["description"] await update_todo(todo_id, title, description) yield ThreadItemDoneEvent( item=AssistantMessageItem( id=self.store.generate_item_id("message", thread, context), thread_id=thread.id, created_at=datetime.now(), content=[AssistantMessageContent(text="Todo updated.")], ) ) ``` ### Validation `Form` uses basic native form validation; enforcing `required` and `pattern` on fields where they are configured and blocking submission when the form has any invalid field. We may add new validation modes with better UX, more expressive validation, custom error display, etc in the future. Until then, widgets are not a great medium for complex forms with tricky validation. If you have this need, a better pattern would be to use client side action handling to trigger a modal, show a custom form there, then pass the result back into ChatKit with `sendAction`. ### Treating `Card` as a `Form` You can pass `asForm=True` to `Card` and it will behave as a `Form`, running validation and passing collected fields to the Card’s `confirm` action. ### Payload key collisions If there is a naming collision with some other existing pre-defined key on your payload, the form value will be ignored. This is probably a bug, so we’ll emit an `error` event when we see this. ## Control loading state interactions in widgets Use `ActionConfig.loadingBehavior` to control how actions trigger different loading states in a widget. ```python button = Button( label="This may take a while...", onClickAction=ActionConfig( type="long_running_action_that_should_block_other_ui_interactions", loadingBehavior="container", ), ) ``` | Value | Behavior | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `auto` | The action will adapt to how it’s being used. (_default_) | | `self` | The action triggers loading state on the widget node that the action was bound to. | | `container` | The action triggers loading state on the entire widget container. This causes the widget to fade out slightly and become inert. | | `none` | No loading state | ### Using `auto` behavior Generally, we recommend using `auto`, which is the default. `auto` triggers loading states based on where the action is bound, for example: - `Button.onClickAction` → `self` - `Select.onChangeAction` → `none` - `Card.confirm.action` → `container` --- # Add custom MCP server [