+190 XP

GPT actions: letting ChatGPT call your APIs

GPT Actions let a custom GPT call external APIs you describe, so instead of guessing, ChatGPT fetches live data or triggers a real system on your behalf. You write a small OpenAPI spec, point it at your endpoint, set up auth, and the model decides when to call it during a conversation.

This is the same machinery as function calling in the API, packaged for the no-code Custom GPT builder. You define the tools. ChatGPT handles when and how to call them.

What an Action actually is

An Action is one or more HTTP endpoints exposed to a GPT through an OpenAPI specification. OpenAPI (formerly Swagger) is a standard, machine-readable description of a REST API: its paths, parameters, request bodies, and responses.

When you add an Action to a GPT, three things happen at runtime:

  1. The model reads your operation descriptions and decides a call is needed.
  2. ChatGPT builds the HTTP request (filling in parameters from the conversation), attaches auth, and sends it.
  3. Your API responds with JSON, and the model reads that JSON to write its answer.

The model never sees your server. It only sees the schema you gave it and the response that comes back. So your `description` fields are prompt, and vague descriptions produce wrong calls.

Where Actions live

Actions are configured inside the GPT editor at chatgpt.com (GPTs, Create, then the Configure tab). Scroll to Actions and click Create new action. You paste a schema, choose an authentication type, and ChatGPT validates it on the spot.

Actions vs apps (formerly connectors)

ChatGPT now has a second way to reach external systems. In December 2025 OpenAI renamed connectors to apps. The catalog includes prebuilt, OpenAI-managed integrations such as Google Drive, SharePoint, and GitHub. Since October 2025, developers can also build their own apps with the Apps SDK, which is built on the Model Context Protocol (MCP). An app runs as an MCP server you host. It can expose tools, and it can optionally render interactive UI inside the chat. It works across ChatGPT conversations, not only inside one GPT.

A rough rule for choosing:

  • Use an existing app when one already covers the source (searching your Drive, for example).
  • Build an Action when you want one custom GPT to hit your REST backend and you already have, or can write, an OpenAPI spec.
  • Build an MCP-based app when the integration should be available across ChatGPT, needs rich UI, or should also be reusable by other MCP clients.

The design advice in this lesson applies to both. Clear tool descriptions, narrow operations, small responses, and server-side validation matter just as much in an MCP tool as in an Action.

A concrete example: order status lookup

Say your support team wants a GPT that answers "Where is order 10428?" by calling your internal orders API. Your endpoint already exists:

GET https://api.acme-shop.com/v1/orders/{orderId}

It returns something like:

json
{
  "orderId": "10428",
  "status": "shipped",
  "carrier": "DHL",
  "trackingNumber": "JD0149...",
  "estimatedDelivery": "2026-02-14"
}

Now you describe that endpoint to the GPT. Here is a clean, minimal OpenAPI 3.1 schema you can paste directly into the Actions editor:

yaml
openapi: 3.1.0
info:
  title: Acme Orders API
  version: 1.0.0
servers:
  - url: https://api.acme-shop.com/v1
paths:
  /orders/{orderId}:
    get:
      operationId: getOrderStatus
      summary: Get the current status and tracking info for one order.
      description: >
        Look up a single order by its numeric ID. Use this whenever a
        user asks where their order is, its delivery date, or its
        shipping status. Returns status, carrier, and tracking number.
      parameters:
        - name: orderId
          in: path
          required: true
          description: The order's numeric ID, e.g. 10428.
          schema:
            type: string
      responses:
        "200":
          description: Order found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId: { type: string }
                  status: { type: string }
                  carrier: { type: string }
                  trackingNumber: { type: string }
                  estimatedDelivery: { type: string, format: date }
        "404":
          description: No order with that ID exists.

A few things make this schema good rather than just valid:

  • operationId is descriptive. getOrderStatus reads better to the model than get1, and it becomes the function name.
  • The description tells the model when to use it. The "Use this whenever a user asks..." sentence is intent routing.
  • The 404 is documented. When the model gets a 404, it can tell the user "I couldn't find that order" instead of inventing a status.

Once saved, ChatGPT shows the available operation. Test it by asking the GPT a natural question. The first time it calls a new domain, ChatGPT asks the user to confirm, then sends the request.

Authentication

Actions support three auth modes in the builder: None, API Key, and OAuth. The schema declares what to call. Auth controls how you prove who you are.

API Key

This is the simplest secured option. You paste a key into the GPT editor, choose how it is sent (Bearer header, Basic, or a custom header), and OpenAI stores it encrypted. ChatGPT attaches it to every call. Add a matching securitySchemes block to your schema:

yaml
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
security:
  - bearerAuth: []

Everyone who uses the GPT shares that key. That is fine for a read-only internal endpoint behind your own network controls. It is not fine when each user should see only their own data, because the model would act with one shared identity.

OAuth

When you need per-user identity (each support agent, or each customer, authenticating as themselves), use OAuth. You provide the authorization URL, token URL, client ID, client secret, and scopes. ChatGPT runs the standard OAuth flow: the user clicks Sign in, approves access on your auth server, and ChatGPT stores that user's token. Calls then carry that user's permissions.

Use OAuth for anything that writes data or exposes private records. Full setup is in the Actions authentication docs. MCP-based apps use OAuth too, so the auth server you set up here carries over if you later build an app.

Build a Custom GPT with Actions

Watch on YouTube

A note on secrets and rate limits

Never put credentials in the schema itself or in the GPT's instructions. Anyone who can use a GPT can sometimes coax it into revealing its configuration. Keep secrets in the dedicated auth fields, and protect your endpoint with its own rate limiting. A popular GPT can generate real traffic, and the model may retry on errors.

Designing the API for a model, not a human

A REST API built for engineers and one built for an LLM differ in small ways. Tighten these:

  • Return small, flat JSON. The response goes into the context window and costs tokens. An order lookup does not need the full audit log.
  • Use clear field names. estimatedDelivery beats est_dlv_dt, because the model reasons over names.
  • Make errors legible with a human-readable message on failures, so the model can relay it.
  • Keep operations narrow. One endpoint that does five things confuses routing. Prefer getOrderStatus, cancelOrder, and getInvoice as separate operations with separate descriptions.

The model can only do what your schema describes. If you want it to cancel orders, you need a cancelOrder operation (a POST or DELETE) with its own description and, ideally, OAuth so the action runs as a real user with permission to cancel.

Knowledge check

1. What is the primary purpose of a GPT Action?

2. Why does the lesson stress that your OpenAPI 'description' fields are 'prompt, not documentation'?

3. In a scenario where you need to bring data from Google Drive into ChatGPT for search and retrieval, what should you use?

MULTIPLE CHOICE

4. Select ALL statements that correctly describe what happens at runtime when a GPT uses an Action.

Select all the correct answers.

MULTIPLE CHOICE

5. Select ALL correct statements distinguishing Actions from Connectors.

Select all the correct answers.

Consequential actions and confirmation

Some calls are read-only. Others change the world: refund a payment, send an email, delete a record. ChatGPT treats these differently.

By default, ChatGPT asks the user to confirm before calling an Action on a new domain. For writes, you want that friction. You can mark operations so the user must confirm each time, which is good practice for anything destructive. Treat every `POST`, `PUT`, `PATCH`, and `DELETE` as consequential until proven otherwise. Design your endpoint so a confirmation step is cheap, for example with a two-call flow: one call to preview, one to commit.

The GPT reasons over your descriptions and may call the wrong operation or pass the wrong argument. Your server is the real authority. Validate every request server-side: check that the order belongs to the authenticated user, that the amount is within limits, that the ID is well-formed. Never assume the model got it right.

How this relates to the API and the Agents SDK

Actions are the Custom GPT surface for tool use. The same idea powers the OpenAI API, where you define tools as JSON schemas and the model returns a structured tool call for your code to execute. If you outgrow the GPT builder (you need custom logic between calls, your own UI, or orchestration across many tools), move to the Responses API or the Agents SDK, where you control the loop directly.

The descriptions and parameter schemas you wrote for an Action translate almost directly into tool definitions in code, or into tools on an MCP server. Think of GPT Actions as the hosted, no-orchestration version of the pattern. Prototype an integration as an Action. Then move it to the Agents SDK when you need full control, or to an Apps SDK app when you want it available across ChatGPT.

Debugging Actions

When a call misbehaves, work through these in order:

  1. Did the model call it at all? If it answered from guesswork, your description is too weak or too generic. Add an explicit "Use this when..." trigger sentence.
  2. Wrong parameters? Check parameter description fields and types. Ambiguity here produces malformed requests.
  3. Auth failures? Test the endpoint with the exact same key or token outside ChatGPT (a curl call) to isolate whether the problem is your auth or the GPT's config.
  4. Schema rejected on save? The editor validates against OpenAPI 3.1. Paste your YAML into an external validator to find the offending line.

Run a quick curl sanity check before you ever touch the builder:

bash
curl -s https://api.acme-shop.com/v1/orders/10428 \
  -H "Authorization: Bearer $ACME_TOKEN"

If that returns clean JSON, the GPT side is just schema and auth config.

Key Takeaways

  • Write descriptions as prompts. The operationId, summary, and description fields decide when and how the model calls your API, so include an explicit "Use this when..." sentence in each operation.
  • Pick the right surface. Use an Action for one custom GPT talking to your REST API. Use an existing app (formerly a connector) when one covers the source. Build an MCP-based app with the Apps SDK for integrations that should work across ChatGPT.
  • Match auth to identity needs: API Key for shared, read-only internal endpoints, OAuth whenever each user should act as themselves or the action writes data.
  • Treat the model as untrusted input. Validate every request server-side and mark write operations as consequential so users confirm before anything changes.
  • Keep responses small and flat, since they consume context tokens and the model reasons over your field names.
  • Prototype as an Action, then graduate to the Agents SDK or an app. The same schemas carry over.

Frequently asked questions

What is a GPT Action in ChatGPT?

A GPT Action is one or more HTTP endpoints exposed to a custom GPT through an OpenAPI specification. You paste the schema in the GPT editor, set an authentication type, and ChatGPT then decides during a conversation when to build the request, attach auth, and send it. Your API returns JSON, and the model uses that JSON to write its answer.

What's the difference between a GPT Action and a ChatGPT app?

An Action lives inside one custom GPT and calls your REST API from an OpenAPI spec. An app (the name OpenAI gave connectors in December 2025) runs as an MCP server you host, works across ChatGPT conversations rather than inside a single GPT, and can render interactive UI in the chat. Use an existing app when one already covers the source, build an Action for a single GPT hitting your backend, and build an MCP-based app with the Apps SDK when the integration should be available everywhere in ChatGPT.

Should I use an API key or OAuth for my GPT Action?

Use an API key only for shared, read-only internal endpoints: everyone using the GPT calls with the same identity, which OpenAI stores encrypted and attaches to every request. Use OAuth whenever each user should see only their own data or the Action writes anything, since ChatGPT then runs the standard flow and stores a per-user token carrying that user's permissions. OAuth also carries over if you later rebuild the integration as an MCP-based app.

Why doesn't ChatGPT call my Action when I ask the question?

Almost always because the operation description is too weak or too generic, so the model answers from guesswork instead of routing to your endpoint. Add an explicit "Use this when a user asks..." sentence in the description and give the operation a readable operationId like getOrderStatus rather than get1. Those description fields are prompt, not documentation.

How do I design a REST API so a model uses it correctly?

Return small, flat JSON, since every response consumes context tokens and the model reasons over your field names: estimatedDelivery beats est_dlv_dt. Keep operations narrow, one job each, with separate descriptions for getOrderStatus, cancelOrder, and getInvoice rather than one endpoint doing everything. Document error codes too, so a 404 lets the model say the order wasn't found instead of inventing a status.

How do I stop a custom GPT from triggering a destructive call by mistake?

Treat every POST, PUT, PATCH, and DELETE as consequential and mark those operations so the user confirms each time; ChatGPT already asks for confirmation the first time it calls a new domain. Then treat the model as untrusted input and validate server-side: check that the record belongs to the authenticated user, that amounts are within limits, that IDs are well-formed. A two-call flow, one to preview and one to commit, makes the confirmation step cheap.

What to do, from this lesson

These actions are compiled in the role's Playbook.

  • Write Action operationId, summary, and description as when-to-use prompts
  • Use OAuth for user-scoped or write Actions; API keys only for shared read-only
See the full action playbook →

Related articles

Recent articles from the blog that build on this lesson.