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

# API & Webhooks

> One tool to connect an agent to any external API, CRM, or webhook. Three modes — define named API endpoints (with OpenAPI import), fire a webhook, or let the agent make free-form HTTP requests.

# API & Webhooks

The **API & Webhooks** tool is the single way to connect an agent to anything that speaks HTTP — your own backend, a CRM, or an automation platform. It has three modes; pick the one that matches what the agent needs to do.

<CardGroup cols={3}>
  <Card title="API Endpoints" icon="plug">
    Define endpoints (or import an OpenAPI spec). Each becomes a function the agent can call by name — `get_doctors`, `book_appointment`. Use when the agent must **read or write data** in your system.
  </Card>

  <Card title="Webhook" icon="bolt">
    Fire-and-forget: POST conversation data to a Zapier / Make.com / n8n / custom URL. The agent does **not** read the response. Use to **trigger an automation**.
  </Card>

  <Card title="Free-form Request" icon="globe">
    The agent composes its own GET/POST requests under a base URL. Use only when you **cannot define the endpoints** up front.
  </Card>
</CardGroup>

<Note>
  This tool replaces the older separate **Webhook**, **REST API**, **Custom API**, **Make.com**, and **n8n** tiles. Agents saved with those still work — they load as the matching mode.
</Note>

## Mode 1 — API Endpoints (recommended)

The agent gets one named, typed function per endpoint, so a voice or chat agent in any language can call `get_slot_availability(doctor_id, date)` directly instead of constructing raw HTTP.

### Set the base URL and auth

| Field               | What it is                                                                                                                 |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **API Name**        | Friendly name shown to the agent, e.g. "Hospital Booking API".                                                             |
| **Base URL**        | Public HTTPS root, e.g. `https://api.yourhospital.com`. `localhost`, private IPs, and plain HTTP are blocked for security. |
| **Auth Type**       | `API Key Header` (e.g. `X-API-Key: <key>`), `Bearer Token` (`Authorization: Bearer <key>`), `Basic Auth`, or none.         |
| **Default Headers** | Optional JSON object sent on every request.                                                                                |

<Warning>
  Your API must be reachable from the public internet over HTTPS with a valid certificate. If your spec says `https://localhost/...`, deploy to a public host first — the platform cannot reach your local machine.
</Warning>

### Define endpoints

Each endpoint needs:

* **Function name** — what the agent calls: `get_doctors`, `create_appointment`.
* **Method + Path** — `GET /api/doctors`, `POST /api/appointments`. Use `{braces}` for path variables: `/api/slot/{doctor_id}/availability`.
* **Description** — tells the agent *when* to use it: "Get available appointment slots for a doctor on a date."
* **Parameters** — name, location (`path` / `query` / `body`), type, required flag, and a description. Good parameter descriptions ("Date in YYYY-MM-DD format") stop the agent guessing wrong formats.

Example — a hospital appointment API becomes three functions:

| Function                | Method & path                            | Parameters                                  |
| ----------------------- | ---------------------------------------- | ------------------------------------------- |
| `get_doctors`           | `GET /api/doctors`                       | `limit` (query, optional)                   |
| `get_slot_availability` | `GET /api/slot/{doctor_id}/availability` | `doctor_id` (path), `date` (query)          |
| `create_appointment`    | `POST /api/appointments`                 | `patient_id`, `doctor_id`, `slot_id` (body) |

### Import from OpenAPI

Click **Import OpenAPI**, paste your OpenAPI 3.x or Swagger 2.0 JSON, and the endpoints are generated automatically — operation IDs become function names, summaries become descriptions, and path/query/body parameters are mapped with their types. Edit anything after import.

### Test the connection

Click **Test Connection**. The platform probes your API with the configured auth and tells you exactly what happened — including a specific message when the URL is reachable but the key is rejected (HTTP 401/403), so auth problems surface before your first live call.

### Tell the agent when to act

```text theme={null}
When a caller wants an appointment: call get_doctors to find the doctor,
get_slot_availability for their requested date, read the open slots back to
the caller, and once they pick one call create_appointment. Never invent
doctors, slots, or IDs — always read them from the API.
```

## Mode 2 — Webhook

Fires a single POST to one URL when the agent decides something noteworthy happened (lead captured, appointment booked, ticket raised). The platform receiving it — Zapier, Make.com, n8n, or your own endpoint — does the rest.

1. In your automation platform, create a trigger that starts with an incoming/custom webhook and copy its URL.
2. Add the **API & Webhooks** tool, choose **Webhook** mode, and paste the URL.
3. (Optional) Set a secret — sent as `X-Webhook-Secret` — or custom headers (e.g. `X-API-Key`) for endpoints that need auth.
4. Tell the agent when to fire it, e.g. *"After booking, send a `appointment_booked` event with the caller's name and slot."*

Platform-specific setup: [Make.com](/docs/tools/make) · [n8n](/docs/tools/n8n).

## Mode 3 — Free-form Request

The agent composes its own requests under a base URL using a single `make_request` function. This is the most flexible but least guided option — prefer **API Endpoints** mode whenever you can list the endpoints, because named functions are far more reliable for the model (especially in voice).

## Limits and behavior

* **API Endpoints**: up to 25 endpoints per tool, 30 parameters each.
* Responses return to the agent as `{status_code, data}` JSON, truncated at \~4,000 characters — prefer `limit`/pagination parameters for large collections.
* Timeouts are configurable (1–120 s, default 15 s). Keep voice agents under \~10 s.
* All requests are SSRF-guarded: URLs are validated and re-resolved against private/reserved IP ranges.

## Troubleshooting

| Symptom                                  | Likely cause                                                                                                             |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| "authentication failed (HTTP 401/403)"   | Wrong Auth Type or header name — check whether your API expects `X-API-Key` or `Authorization: Bearer`.                  |
| "Only HTTPS URLs are allowed"            | Base/target URL uses `http://` or points to `localhost` / a private IP.                                                  |
| Agent says it acted but nothing happened | A required parameter was missing — the function returns an error the agent may paraphrase. Check the call's tool traces. |
| Responses cut off                        | Body exceeded the \~4,000-character budget. Add pagination/limit parameters.                                             |

## Using HTTP inside flows and workflows

* **Flow Editor**: drop an **HTTP Request** node onto the canvas to call an API at a specific step and pass the response to the next node.
* **Voice Workflows (state machines)**: an **API Request** step calls an API mid-call and maps response fields into workflow variables for later branches.

Both use the same engine (auth, SSRF guard, response shaping) as this tool.