> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a Custom Action with Backstage, no setup forms

> Have Backstage build, test, and turn on a Chatbase Custom Action from your API docs in one conversation, with API keys kept out of the chat.

Backstage can build a [Custom Action](https://chatbase.co/docs/user-guides/chatbot/actions/custom-action.md) for you in conversation: the endpoint, headers, query parameters, body, and the details your AI agent asks customers for. You describe what the AI agent should be able to do and share your API docs, and Backstage drafts the Action, tests it against your real API, and turns it on after one approval. It's the fastest way to connect your AI agent to your own systems if you'd rather not fill in the Action form yourself.

## Build an Action

**1. Describe the job**

Tell Backstage what your AI agent should be able to do, and include links to the API docs if there are any.

**2. Answer any open question**

If your request leaves a real choice open, such as which endpoint to use or whether the Action should change data, Backstage asks you one question first.

**3. Approve the build**

Backstage reads the docs, drafts the Action, and asks for one approval that covers the whole build: the configuration, the test call, and turning the Action on.

Along the way, Backstage shows a masked input if the endpoint needs an API key, and a test card with a **Run** button for the test call. Both are covered below. Then try the Action in the [Playground](https://chatbase.co/docs/user-guides/chatbot/playground.md) with a question that should trigger it.

### Example: a weather lookup

> I want my agent to tell people the current weather in their city. Here are the docs: [https://open-meteo.com/en/docs](https://open-meteo.com/en/docs)

Backstage works out how the API expects its inputs. Here it notices that the API takes coordinates rather than city names, so it builds the Action with latitude and longitude as inputs. Compare it with the [Weather API example](https://chatbase.co/docs/user-guides/chatbot/actions/custom-action.md#weather-api) built by hand.

### Example: an order status lookup

> Acme customers keep asking where their order is. Our API is `GET https://api.example.com/orders/{order_id}` with an `x-api-key` header. Build an Action that looks up an order by its number, like #1042.

Because the endpoint needs a key, Backstage shows a masked input for the `x-api-key` value instead of asking you to paste it in the chat.

## API keys stay out of the chat

When an endpoint needs an API key, Backstage shows a masked input. The value goes straight from your browser to the Action, and Backstage never sees it. When Backstage reads the Action back later, any saved key appears as `[set]`.

The form also shows which Action the key is for and the host it will be sent to, so you can check both before pasting a live key.

Once saved, the key is a normal header or parameter on the Action. In the Action editor, header and parameter values are shown in plain text to anyone who can edit the Action, so use a key scoped to only what the Action needs. See [Authentication](https://chatbase.co/docs/user-guides/chatbot/actions/custom-action.md#authentication).

## Testing against your real endpoint

Nothing is sent to your API until you click **Run**. Before that, the test card shows the exact request that will be sent, and warns you when the method can change data (`POST`, `PUT`, `PATCH`, or `DELETE`).

Backstage only receives the shape of the response (field names, types, and short samples), never the full body. Those fields become the data your AI agent can see when it calls the Action. Narrow them later from the Action's [Data Access](https://chatbase.co/docs/user-guides/chatbot/actions/custom-action.md#data-access) settings in the dashboard.

> [!WARNING]
>
> Testing a `POST`, `PUT`, `PATCH`, or `DELETE` request runs it for real. Point the test at a test record or a sandbox if the call creates, changes, or deletes data.

## Spotting missing Actions

When Backstage reviews your conversations, it can notice that customers keep asking for something only an Action could answer, and offer to build that Action. Many gaps are better solved with a Q\&A or a source fix, and in those cases Backstage suggests that instead of an Action. [Scheduled audits](https://chatbase.co/docs/user-guides/chatbot/backstage/scheduled-audits.md) follow the same order: a Q\&A first, then a source fix, an instructions change, and an Action last.

## Good to know

* If the request uses a `{{variable}}` that your AI agent never collects from the customer, Backstage points it out. See [Variables](https://chatbase.co/docs/user-guides/chatbot/actions/custom-action.md#variables).
* On Slack, the **Run** button works right in the thread. Entering an API key opens Backstage on the web.
* Building or editing an Action always needs your approval, even in [auto mode](https://chatbase.co/docs/user-guides/chatbot/backstage/approvals-and-auto-mode.md#auto-mode), because Actions aren't one of the auto mode areas.
* A reply that triggers an Action costs twice the model's usual message credits. See [Actions](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md).

## Frequently asked questions

> [accordion] Can Backstage see my API key?
>
> No. You type the key into a masked input, and it goes straight from your browser to the Action. When Backstage reads the Action later, the key shows as `[set]`.

> [accordion] Does Backstage call my API without asking?
>
> No. Nothing is sent until you click **Run** on the test card, which first shows the exact request and warns you if the method can change data.

> [accordion] Does Backstage see my customers' data from the test call?
>
> Backstage receives only the shape of the response: field names, types, and short samples. It never receives the full response body.

> [accordion] Can I edit an Action Backstage built?
>
> Yes. It's a normal Custom Action under **Build > Actions**. You can change it there, or ask Backstage to change it, with your approval.

> [accordion] Can I build an Action from Slack?
>
> Yes. You can describe the Action and run the test from the Slack thread. Entering an API key opens Backstage on the web.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.