---
title: "API connections"
description: "Turn any HTTP API into a function your agent can call mid-conversation: paste a cURL command and the wizard builds the tool definition, parameters, and auth."
---

API connections are custom HTTP functions your agents can call during a
conversation — look up an order, create a ticket, fetch account status
from your own backend. You define the endpoint once under
**Connections → APIs** (`/dashboard/api-connections`); agents that have
the connection attached can then invoke it whenever the conversation
calls for it.

There are two ways to build one: paste something the wizard can analyze,
or set the connection up manually.

## The fast path: paste and analyze

<Steps>
  <Step title="Click New API connection">
    The dialog opens on the wizard. Paste a sample **cURL command**,
    **OpenAPI/Swagger spec**, **Postman export**, **TypeScript
    interface**, or **Zod schema** into the box.
  </Step>
  <Step title="Click Analyze">
    ThunderPhone infers the whole connection from your paste — URL,
    method, headers, and a parameter schema derived from the query
    parameters and request body it found. Headers you pasted (including
    auth headers) are carried into the endpoint configuration.
  </Step>
  <Step title="Confirm the highlighted fields">
    The inferred configuration opens with the guessed fields highlighted
    for review. Adjust names, descriptions, and parameter types so the
    agent understands when and how to call the function — the description
    is what the model reads.
  </Step>
  <Step title="Validate & Save">
    Saving runs a live test request against your endpoint first. If the
    request fails, the connection isn't saved — fix the URL, auth
    headers, or body and try again. On success the connection is stored
    with a **Validated** badge.
  </Step>
</Steps>

If the wizard can't find a request URL in your paste, it will say so —
include a full `http(s)` endpoint and try again.

## Manual setup

Click **Set up manually →** in the wizard (or **Want AI to infer this?
Try the Wizard →** to go back). The manual builder has two editors:

- **Visual** — form fields for the display name, function name, request
  **URL**, **method** (`POST`, `GET`, `PUT`, `PATCH`, `DELETE`), custom
  **headers**, and the parameter schema (**Add property** for each
  argument the agent can supply).
- **JSON** — the same definition as raw JSON, for pasting or fine-tuning
  a tool spec directly.

A **Test Request** panel (optional) lets you fire the configured request
before saving and shows the status, latency, and a response preview.
**Validate & Save** always runs this test and only saves on success.

Header values are write-only. Once saved they are encrypted and never shown
again, in the dashboard or the API. When you edit a connection, a saved
header shows its name with dots in place of the value and a **Saved** note:
leave it as is to keep the saved value, or type a new one to replace it. Test
requests and live calls use the saved value. **Clone** copies saved values
to the new connection.

<Tip>
  Give parameters plain-language descriptions ("Customer email address,
  e.g. jane@example.com"). The agent chooses arguments from these
  descriptions in real time, mid-call.
</Tip>

## Manage your connections

Each connection row shows its validation status — **Validated**,
**Untested**, or **Error** — its function name, and which agents use it.
From the row's action menu you can:

- **Edit** — reopen the configuration.
- **Clone** — duplicate it as a starting point (the copy starts
  Untested).
- **Revision history** — view earlier versions and restore one into the
  editor.
- **Transfer** — copy or move the connection to another organization you
  belong to. Moving removes it here; agents that used it may need
  reconfiguration.
- **Delete** — permanent; agents using the connection will need to be
  reconfigured.

## Attach it to an agent

Add the connection to an agent in the builder's API connections section
([Build an agent](/guides/build-an-agent)). The list shows which agents
use each connection, so you can tell at a glance what a change affects.

## Next steps

<CardGroup cols={2}>
  <Card title="Tool integrations via API" icon="code" href="/guides/build-tool-integration">
    Create and manage the same connections programmatically.
  </Card>
  <Card title="Connect apps" icon="cable" href="/guides/connect-apps">
    Prebuilt Google, Slack, HubSpot, Salesforce, and Cal.com connections.
  </Card>
  <Card title="Add an MCP server" icon="server" href="/guides/mcp-servers">
    Expose a whole tool server to your agents.
  </Card>
  <Card title="Integrations API reference" icon="book" href="/api-reference/integrations">
    Every field on the integration resource.
  </Card>
</CardGroup>