GPT actions: letting ChatGPT call your apis

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 constructs the HTTP request (filling in parameters from the conversation), attaches auth, and sends it.

3. Your APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → responds with JSON, and the model reads that JSON to write its answer.

The model never sees your server. It only sees the schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition → you gave it and the response that comes back. That means your description fields are not documentation, they are *prompt*. Vague descriptions produce wrong calls.

Where Actions live

Actions are configured inside the GPT editor at chatgpt.com (Explore GPTs, Create, then the Configure tab). Scroll to Actions and click Create new action. You paste a schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition →, choose an authentication type, and ChatGPT validates it on the spot.

Do not confuse Actions with Connectors. Connectors are prebuilt, OpenAI-managed integrations (Google Drive, SharePoint, GitHub, and others) that bring data *into* ChatGPT for search and retrieval. Actions are *your* custom APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → calls, defined by you. Use a Connector when one exists for the source; build an Action when you need to hit your own backend or trigger something.

A concrete example: order status lookup

Say your support team wants a GPT that answers "Where is order 10428?" by calling your internal orders APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →. Your endpoint already exists:

It returns something like:

Now you describe that endpoint to the GPT. Here is a clean, minimal OpenAPI 3.1 schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition → you can paste directly into the Actions editor:

A few things make this schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition → good rather than just valid:

• `operationId` is descriptive. getOrderStatus reads better to the model than get1. This becomes the function name.
• The `description` tells the model when to use it. Note the "Use this whenever a user asks..." sentence. That 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 hallucinating 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 prompts the user to confirm, then sends the request.

Authentication

Actions support three auth modes in the builder: None, API Key, and OAuth. The schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition → above declares *what* to call; auth controls *how you prove who you are*.

APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → Key

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 schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition →:

The key is shared by everyone who uses the GPT. 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 dataown dataData collected directly from your own customers and prospects through your own channels: your most reliable and privacy-compliant source.View full definition →, 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, tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → 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 tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition →. Calls then carry *that user's* permissions.

This is the right choice for anything that writes data or exposes private records. Full setup is in the Actions authentication docs.

A note on secrets and rate limits

Never put credentials in the schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition → 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 APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → for a model, not a human

A REST APIREST APIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → built for engineers and one built for an LLMLLMA Large Language Model is an AI system trained on vast text data to predict and generate language, enabling tasks like writing, summarizing, and answering questions.View full definition → differ in subtle ways. Tighten these:

• Return small, flat JSON. The response goes into the context windowcontext windowThe context window is the maximum amount of text (measured in tokens) a language model can process at once, including both the input prompt and the generated output.View full definition → and costs tokenstokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition →. Strip fields the model does not need. An order lookup does not need the full audit log.
• Use clear field names. estimatedDelivery beats est_dlv_dt. The model reasons over names.
• Make errors legible. Return 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.

A consequence worth internalizing: the model can only do what your schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition → *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.

Consequential actions and confirmation

Some calls are read-only. Some 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, and design your endpoint so a confirmation step is cheap (for example, a two-call flow: one to preview, one to commit).

Keep a clear boundary in mind. The GPT is reasoning 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 APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → and the Agents SDK

Actions are the Custom GPT surface for tool use. Under the hood, the same idea powers the OpenAI APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →, 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), you move to the Responses API or the Agents SDK, where you control the loop directly.

The migration path is clean: the descriptions and parameter schemas you wrote for an Action translate almost directly into tool definitions in code. Think of GPT Actions as the hosted, no-server-orchestration version of the same pattern. Prototype an integration as an Action, then graduate it to the Agents SDK when you need full control.

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 the 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 tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → 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.

A fast curl sanity check before you ever touch the builder:

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 schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition → and auth config.

Key Takeaways

• Write descriptions as prompts, not docs. The operationId, summary, and description fields are how the model decides when and how to call your APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →. Include an explicit "Use this when..." sentence in each operation.
• Match auth to identity needs. Use APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → Key for shared, read-only internal endpoints; use OAuth whenever each user should act as themselves or the action writes data.