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

# Custom API

> Connect any external API once and let your agents call it by name

Custom API connections give every external HTTP API — a shipping tracker, an alerting webhook, an internal tool — one home on the Integrations page. You configure the endpoint and credential once; any agent you allow can then call it by name through the [External API Request](/agents/tools/management/external-api-request) tool.

<Info>
  Connections are the only way to give an agent an external API — the old per-agent configuration editor was retired after every existing setup was migrated to connections. One definition and one credential, shared by every agent: rotating a key updates all of them at once.
</Info>

## Add a connection

Open [**Integrations**](https://dashboard.neoagent.io/integrations), find **Custom API** under **Other**, and click **Add API**. The wizard walks through five steps:

<Steps>
  <Step title="Point Neo at the API">
    Name the connection, paste the web address, and pick what Neo does there — **GET**, **POST**, **PUT**, **PATCH**, or **DELETE**. A `{placeholder}` segment in the address (e.g. `.../track/{trackingNumber}`) becomes a value the agent fills in on every call.
  </Step>

  <Step title="Prove who Neo is">
    Pick how the API authenticates:

    | Option                             | When to use                                                                                           |
    | ---------------------------------- | ----------------------------------------------------------------------------------------------------- |
    | **API key**                        | The service gave you a single code, sent in a custom header                                           |
    | **Access token**                   | The docs say `Authorization: Bearer`                                                                  |
    | **Username & password**            | HTTP Basic authentication                                                                             |
    | **Client ID & secret (OAuth 2.0)** | The API issues short-lived tokens from a token endpoint; Neo fetches and refreshes them automatically |
    | **No key needed**                  | Public endpoints and pre-authenticated webhook URLs                                                   |

    Keys and secrets are stored in a secure vault, shown masked afterwards, and never appear in logs or event history.

    For OAuth 2.0 providers that need more than a client ID and secret, expand **Advanced OAuth options**: add custom token request parameters (when any are set, that list becomes the whole token request — include `grant_type` and everything else the provider's docs list, marking passwords as secret) and, if the provider wants credentials in a header on the token request, token-endpoint Basic auth.
  </Step>

  <Step title="Teach Neo the blanks">
    Optional. Define **Query parameters** and, for requests with a body, **Information Neo sends** — each field gets a name, a type, a description, and whether it's required. The agent reads the descriptions to fill fields correctly, so write what the value means, not just its name.
  </Step>

  <Step title="Try it out">
    Send one real request before saving. The result is recorded on the connection, so you can see at a glance which connections have been verified.
  </Step>

  <Step title="Review & save">
    A plain-words summary of what you built. Save, and the connection appears under **Connected APIs** on the tile.
  </Step>
</Steps>

## Test a saved connection

On the Custom API tile, every connection has a **Test** button (▶). It opens a dialog asking for any parameters the API needs, sends one real request with the stored credential, and records the outcome next to the connection.

## Use a connection from an agent

In the agent builder, enable the **External API Request** tool and pick the connection under **Connected APIs**. The agent calls it by its connection name, so use names your instructions can reference naturally — `DHL_Tracking`, `slack_alert`.

## Update a credential

Edit the connection and type the new value over the masked one — a masked field left untouched keeps what's stored. Every agent that references the connection uses the new credential immediately; nothing needs re-saving on the agents.