Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openai/openai-cookbook/llms.txt

Use this file to discover all available pages before exploring further.

ChatGPT Actions give GPT models the ability to call external APIs on behalf of a user — directly inside a conversation. You describe your API using an OpenAPI specification, and ChatGPT parses that spec to understand what endpoints are available, what parameters they accept, and what they return. When the model determines it needs live data or needs to take an action, it calls the appropriate endpoint and incorporates the response into its reply. This bridges the gap between a conversational model and the real systems your product already runs on.

​
How Actions work

An Action is a set of API endpoints you expose to a GPT, described through an OpenAPI 3.x specification. ChatGPT reads the spec at configuration time to build an internal understanding of the available operations. At runtime, when a user’s request matches an operation, the model issues a structured API call and uses the result to form its final answer.
1

Write an OpenAPI spec

Describe your API using the OpenAPI 3.1 format. Each operationId becomes a callable action. Descriptions in the spec are read by the model, so write them clearly — they influence when and how the model decides to call the endpoint.
2

Configure the Action in ChatGPT

In the GPT editor, paste your OpenAPI spec into the Actions panel. Set your authentication method and choose a privacy policy URL. ChatGPT validates the spec and surfaces the available operations.
3

Test in the playground

Use the ChatGPT interface to send messages that should trigger your action. Inspect what parameters the model sends and verify your API returns the expected shape. Iterate on your spec descriptions to improve model accuracy.
4

Publish

Choose a privacy setting (only me, anyone with the link, or everyone) and publish the GPT. Users can now interact with your live API through natural conversation.

​
Defining an Action with an OpenAPI spec

The spec below defines a simple weather lookup action. Notice the operationId and summary fields — the model uses these to decide when to call this endpoint and how to describe the action to users. 
openapi: 3.1.0
info:
  title: Weather API
  version: 1.0.0
paths:
  /weather:
    get:
      operationId: getWeather
      summary: Get current weather
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Weather data
          content:
            application/json:
              schema:
                type: object
                properties:
                  temperature:
                    type: number
                  conditions:
                    type: string
Write operationId values in camelCase and keep summary strings concise. The model uses both to reason about when to invoke an endpoint, so ambiguous or generic descriptions reduce accuracy.
A few principles for writing effective specs:
  • One operation per action — avoid overloaded endpoints. The model picks operations by reading descriptions, so a single endpoint that does many things is harder to use reliably.
  • Use descriptive parameter names — location is clearer than loc or q. The model sees parameter names when constructing calls.
  • Document response shapes — include properties in your response schema. The model uses the schema to extract and present the right fields to users.

​
Authentication options

ChatGPT Actions support three authentication modes. Choose the one that matches your API’s existing security model.

No auth

Your API is publicly accessible. Suitable for read-only public data endpoints where you don’t need to identify the caller.

API key

ChatGPT sends a static key in each request, either as a bearer token in the Authorization header or as a custom header you specify. Keys are stored encrypted per-GPT.

OAuth 2.0

ChatGPT runs a standard OAuth flow when a user first invokes the action. The user authenticates with your identity provider, and ChatGPT stores and refreshes tokens automatically.

​
API key configuration

When you select API key authentication in the GPT editor, you provide:
  • Auth type — Bearer (adds Authorization: Bearer <key>) or Custom (lets you name the header yourself, e.g. X-Api-Key)
  • API key value — stored encrypted and sent with every request your action makes

​
OAuth configuration

For OAuth, you provide your authorization URL, token URL, scope, and client credentials. ChatGPT handles the redirect, code exchange, and token refresh. Your API receives a valid access token on every call — no session management needed on the ChatGPT side. 
# In your OpenAPI spec, declare the security scheme
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://your-idp.example.com/oauth/authorize
          tokenUrl: https://your-idp.example.com/oauth/token
          scopes:
            read:data: Read access to data
security:
  - oauth2:
      - read:data
Never include real API keys or secrets inside your OpenAPI spec. Add them only through the ChatGPT Action editor’s auth configuration panel, where they are stored encrypted.

​
Privacy and access settings

Every GPT has an access level that controls who can discover and use it:
  • Only me — visible only to you. Use this during development and testing.
  • Anyone with the link — unlisted but shareable. Good for internal teams or beta users.
  • Everyone — listed in the GPT Store. Requires a published privacy policy URL.
Your OpenAPI spec must include a servers entry pointing to your API host. ChatGPT uses this to route requests and enforces that all calls go to the declared domain — it will not follow redirects to other origins.

​
Use cases

Customer service

Connect a support GPT to your ticketing system. The model can look up order status, create tickets, or escalate issues without leaving the conversation. Use tool_choice: required to ensure the model always calls a structured tool rather than guessing.

Data lookup

Give users natural-language access to internal databases, dashboards, or reporting APIs. The model translates conversational queries into structured API calls and summarizes the results.

Task automation

Trigger workflows — send emails, update CRM records, schedule meetings — directly from chat. The model handles disambiguation (asking clarifying questions) before committing an action.

Knowledge retrieval

Connect to internal knowledge bases or documentation APIs. The model retrieves relevant content and cites it in its answer, reducing hallucination compared to relying on training data alone.

​
Tips for reliable Actions

Keep your API responses small and focused. ChatGPT has a context limit, and large API payloads consume tokens quickly. Return only the fields the model needs to answer the user’s question.
  • Return structured JSON — flat objects are easier for the model to interpret than deeply nested structures. If your existing API returns complex shapes, consider adding a thin adapter layer.
  • Use clear error messages — when your API returns a non-2xx status, include a human-readable message field. The model will incorporate this into its response to the user.
  • Version your spec — treat your OpenAPI spec like code. Breaking changes to parameter names or response shapes require updating the spec in the GPT editor.

​
Next steps

Function calling

Understand the underlying function-calling mechanism that powers Actions in the Chat Completions API.

Agents overview

Go beyond single actions and build agents that chain multiple tool calls to complete complex tasks.

Build docs developers (and LLMs) love

Get started for freeTalk to us