> ## 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 Request Node

> Call your own APIs from inside a Voice Workflow using the unified API & Webhook tool, and map responses into variables so the flow can branch on live data.

# API Request Node

The **API Request** node lets a [Voice Workflow](/docs/voice/workflows) call
your own backend mid-call — check a slot, look up a customer, create a ticket —
and feed the result back into the flow as a [variable](/docs/voice/workflows/transitions).
It runs **instantly** (no caller turn), then passes through to the next node, so
the caller hears no dead air.

Under the hood it reuses the unified **API & Webhook** tool (`api_connect`) — the
*same* configuration as the agent's API & Webhook tool. Anything you can set up
there, you can set up here.

## Three modes

The API Request node exposes the same three modes as the agent tool. Pick the one
that matches what you're doing.

<CardGroup cols={3}>
  <Card title="API Endpoints" icon="plug">
    Define one or more endpoints (or **import an OpenAPI** spec) with typed
    parameters. Use this to **read or write data** mid-call — the most common
    mode for workflows that branch on live results.
  </Card>

  <Card title="Webhook" icon="right-left">
    Fire a single **fire-and-forget** webhook URL to kick off downstream
    automation (notify a CRM, trigger a Zap). No response mapping needed.
  </Card>

  <Card title="Free-form Request" icon="code-branch">
    Hand-build a one-off request when you don't want to define a reusable
    endpoint.
  </Card>
</CardGroup>

## Configure it

Select the node on the canvas to open the **Inspector**, then click **Configure
API** to open the API Connect modal — the same modal the agent's API & Webhook
tool uses.

<Steps>
  <Step title="Set the Base URL">
    A **public HTTPS** URL only. `localhost` and private/internal IPs are blocked,
    so the endpoint must be reachable from the internet.
  </Step>

  <Step title="Choose Auth">
    Pick **None**, **API Key Header**, **Bearer**, or **Basic**, and fill in the
    credentials. Auth is applied to every request the node makes.
  </Step>

  <Step title="Define endpoints (or import OpenAPI)">
    For the **API Endpoints** mode, add each endpoint with a **name**, **method**,
    **path**, and **typed parameters** — or **import an OpenAPI** spec to generate
    them automatically.
  </Step>

  <Step title="Test Connection">
    Use **Test Connection** to confirm the Base URL, auth, and endpoint respond
    before you enable the workflow.
  </Step>
</Steps>

Back in the Inspector, **pick which endpoint** this node should call.

<Note>
  The API Connect modal here is identical to the agent's API & Webhook tool. For the
  full reference — every auth type, OpenAPI import details, and free-form request
  options — see [API & Webhook tools](/docs/tools/api-webhooks).
</Note>

## How inputs flow in

The chosen endpoint's **parameters are filled from workflow variables of the same
name**. This is *extract-before-call*: by the time the flow reaches the API
Request node, earlier [Conversation or Collector nodes](/docs/voice/workflows/nodes)
should have captured the variables the endpoint needs.

For example, an endpoint parameter named `preferred_date` is automatically
populated from the workflow variable `{{preferred_date}}`. Declare those variables
in the **Variables** panel and make sure a preceding node collects them.

## Map the response into a variable

Reading data is only useful if the flow can act on it. The **Response → Variable
mapping** maps a response field — by **dot path** — into a workflow variable.

| Response field (dot path) | Mapped into          | Used for                              |
| ------------------------- | -------------------- | ------------------------------------- |
| `available`               | `{{slot_available}}` | A Condition branches on it            |
| `patient.id`              | `{{patient_id}}`     | Reused as a parameter in a later call |

Once a response field lands in a variable, a downstream
[Condition node](/docs/voice/workflows/nodes) can branch on it with an
[equation edge](/docs/voice/workflows/transitions) such as
`{{slot_available}} == true`.

## Error handling

On a **failed or timed-out** call, the node follows its **error edge** — the call
never hangs. Always give an API Request node a path to take when the request
doesn't succeed, so the agent can apologize, retry, or offer an alternative
instead of leaving the caller in silence.

## Worked example — slot availability

This is the **API Request** step from the
[Appointment Booking template](/docs/voice/workflows/templates).

<Steps>
  <Step title="Collect the date">
    An earlier Collector/Conversation node captures the caller's
    `{{preferred_date}}`.
  </Step>

  <Step title="Call the endpoint">
    The **Check Slot Availability** node calls `GET /availability`. Its
    `preferred_date` parameter is filled from `{{preferred_date}}` automatically
    (extract-before-call).
  </Step>

  <Step title="Map the response">
    The **Response → Variable mapping** maps the response field `available` into
    the boolean variable `{{slot_available}}`.
  </Step>

  <Step title="Branch on the result">
    The next **Condition** node checks the equation edge
    `{{slot_available}} == true` — routing to a "book it" branch when the slot is
    open, and to an "offer another time" branch otherwise.
  </Step>

  <Step title="Handle failures">
    If the call fails or times out, the node's **error edge** routes to a graceful
    fallback so the caller still gets a response.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Transitions & Variables" icon="code-branch" href="/docs/voice/workflows/transitions">
    Declare typed variables and write the equation edges that branch on your
    mapped response fields.
  </Card>

  <Card title="Node Types" icon="table-list" href="/docs/voice/workflows/nodes">
    See how the API Request node sits alongside Condition, Set Variable, and the
    other internal nodes.
  </Card>

  <Card title="Workflow Templates" icon="rocket" href="/docs/voice/workflows/templates">
    Start from Appointment Booking to see this exact API call wired up.
  </Card>

  <Card title="API & Webhook tools" icon="plug" href="/docs/tools/api-webhooks">
    The full reference for the unified API Connect tool this node reuses.
  </Card>
</CardGroup>