# Your API

> Let the agent check your own systems mid-conversation, like delivery areas, stock or a booking, by calling endpoints you add, with secrets, approvals, a test bench and a run log.

Source: https://www.hey.support/docs/capabilities/your-api

---

Your API lets the agent answer from your own systems while it chats. Add an endpoint, such as "which days do you deliver to this postcode?", and when a visitor asks something only that system knows, the agent calls it and answers from what comes back. There is no trigger to configure: the model decides when to use an endpoint from its description. You decide which endpoints exist and what they are allowed to do.

Open **Capabilities**, then **Your API** in the **Live data** group.

<Callout>
  Your API is available on Growth and above, with a monthly cap on endpoint runs. Starter does not include it. See [Plans](/docs/billing/plans).
</Callout>

<Callout type="info">
  Your API replaces AI Actions (October 2026). Custom actions you made are now endpoints and kept working. The ready-made app actions (HubSpot contact lookup, WooCommerce coupons, Shopify discount codes and product recommendations) were retired: product answers live in [Ecommerce](/docs/capabilities/ecommerce), and order lookups are [Order help](/docs/capabilities/order-help).
</Callout>

## Your endpoints

The Your API page lists the agent's endpoints, each with its own switch. The capability is on whenever at least one endpoint is on, so there is no separate power switch. Open an endpoint to see its whole story on one page: what it does, what the model sees, the request, the answer, a test bench, and its run log.

While any endpoint is on, the agent answers with GPT-4.1 instead of GPT-4.1 mini, so it can decide when to call your system. Replies take a moment longer.

## Starting an endpoint

**Paste what you already have.** Add an endpoint and paste a URL that works, with a real value in it (`https://api.example.com/delivery/41111`), or a cURL command. If it reads data, we run it once and show you what came back; a request that changes data is never run while you set up. Then we draft the rest for you to check:

* a name, and the description your agent reads to decide when to use it;
* the inputs hidden in the URL, so `41111` becomes `{postcode}` and the agent asks the visitor for it;
* the response fields worth keeping, picked from the real response. A `[*]` field reads every item in a list.

If your endpoint answers 401 or 403, paste the header it expects; we save the value as an encrypted key named for your API and send only a reference to it. A key pasted in a cURL command is replaced with that reference the same way. Only a workspace owner can save keys.

Before you switch it on, **try it in a chat**: ask what a visitor would ask, and see whether your agent uses the endpoint and what it answers. Nothing is saved.

Other ways to start:

* **Templates** fill in the shape of a common endpoint — look up an order, check a subscription, open a ticket, verify a licence key, check stock — and leave your host and your key to you.
* **Import from cURL** takes a command you already have working, from a vendor's docs or your terminal, and fills in the method, URL, headers and body. A header that looks like a credential is turned into a `{{secret.NAME}}` reference rather than being stored in the clear.
* **Start from scratch** if you know exactly what you want.

A new endpoint is created **switched off**, so nothing reaches visitors until you have run it and turned it on.

## What the AI sees

Every endpoint's page shows the exact tool definition we hand the model: the name, the description and the parameter schema. That is the whole contract — the model reads only the description to decide *when* to call — so if an endpoint never seems to fire, this is where to look.

It also shows what the model does **not** get. The URL, the headers and your secrets never leave our server.

Names are slugified for the tools API, so `Check delivery days` becomes `check_delivery_days`. If two endpoints would end up with the same name we tell you while you type.

## Inserting values

* `{parameter_name}` inserts a value the model collected — the parameters you declared, such as `{postcode}` in `https://api.example.com/delivery/{postcode}`.
* `{{visitor.name}}`, `{{visitor.email}}`, `{{visitor.phone}}`, `{{visitor.page_url}}`, `{{visitor.locale}}` and `{{visitor.timezone}}` insert what the visitor has already told this conversation, so the agent does not have to ask twice.
* `{{secret.NAME}}` inserts a stored secret, **in headers only**.

Values are escaped for wherever they land: percent-encoded in a URL, escaped for the body's content type. A customer called O'Brien cannot break the request.

<Callout type="warn">
  Visitor details are supplied by the visitor and are not verified. They are fine for personalising a request — never use one to decide what somebody is allowed to see.
</Callout>

## Secrets

APIs need keys, and you should never paste a key into a prompt. Store them as **secrets** in workspace settings, then reference them in an endpoint's headers as `{{secret.NAME}}`. Secrets are encrypted, only ever used in request headers, and are stripped from anything we store. See [Workspace settings](/docs/billing/workspace-settings).

## Safety

Every request goes through the same guard. It refuses private and internal addresses, including a public name that points at one, and it does not follow a redirect to another host, because your headers may carry a secret. A request that changes data is never sent twice. Responses over 1 MB are refused.

## The test bench

Run the endpoint against your real system with sample inputs. Nothing is saved and no usage is counted. Responses are read in full, up to 1 MB, so fields deep in a large response are found.

Before it fires, the bench shows **the request we will send** — the substituted URL, the real body, and the headers with secret values masked. You can copy it as a cURL command to hand to whoever owns the API.

## Choosing what comes back

By default the whole response goes to the model. On a chatty API that is mostly fields nobody reads.

After a successful test you can pick exactly which fields to send, straight off the real response. If a field later disappears from the API we send the whole body rather than sending the model nothing.

## Approvals

Some endpoints should not run without a human saying yes, like cancelling an order. Mark an endpoint as requiring approval, and when the agent wants to run it, the request lands in your [Inbox](/docs/conversations/inbox) as a card. A teammate approves or denies it, and the visitor waits for the result.

## The run log

Every run appears on the endpoint's page: what the model sent, what came back, the HTTP status, how long it took, and the error if it failed. Test runs are marked as such.

Secrets never appear there — they are injected into headers server-side and stripped from anything we store.

## Usage

Endpoint runs count against your plan's monthly cap, shown on the Your API page.