> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/tools/api-request/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# API Request tool

> Learn when to use an API Request Tool, how requests move between an assistant and an HTTP endpoint, and how to build your first working integration with Vapi.

An API Request Tool lets an assistant call an HTTP endpoint during a conversation. The assistant collects values defined by a request schema, Vapi sends the request, and the assistant can use the response when it speaks to the caller.

## When to use an API Request Tool

Use an API Request Tool when your assistant needs to:

* Send structured data to an existing HTTP API
* Read data from an API and use it in the conversation
* Authenticate requests with a reusable Vapi credential
* Combine model-generated parameters with trusted static values

The tool name and description are visible to people configuring the assistant and help the model decide when to call the tool. Describe the action, the required conditions, and what the assistant should do with the result.

## How it works

1. The assistant collects the values defined in the tool's request schema.
2. Vapi builds and sends the HTTP request to your endpoint.
3. Your endpoint returns a response.
4. The assistant uses the response according to its system prompt.

Keep calculations and business rules on your server when they must be deterministic. For example, an order API should calculate the final price instead of asking the model to calculate it.

## Behavior at a glance

| Behavior               | API Request Tool behavior                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| Endpoint               | Sends requests to an HTTPS URL.                                                                 |
| HTTP methods           | Supports `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.                                           |
| Model-generated values | Uses the `body` JSON Schema to define values the model can supply.                              |
| Server-resolved values | Supports fixed values and Liquid templates in the URL, request headers, and static body fields. |
| Authentication         | Applies a reusable Vapi credential through `credentialId`.                                      |
| Timeout                | Uses 20 seconds by default; `timeoutSeconds` accepts 1–300 seconds.                             |
| Execution              | Waits synchronously for the destination API before returning a result to the assistant.         |
| Response data          | Makes the current result available to the model. Variable extraction requires a JSON response.  |

See the [Create Tool](/api-reference/tools/create) and [Update Tool](/api-reference/tools/update) API references for the complete request schemas.

## Start with a working example

#### [Coffee-order quickstart](/tools/api-request/quickstart)

Create an assistant that sends a confirmed coffee order to a public test endpoint and reads the result to the caller.

#### [Configure requests](/tools/api-request/configuration)

Configure the endpoint, request body, headers, static body fields, and Liquid values.

#### [Handle latency and retries](/tools/api-request/reliability)

Set timeouts, handle failures safely, and keep callers informed while a request runs.

#### [Handle responses and errors](/tools/api-request/response-handling)

Design response contracts, test failures, and inspect tool results.

#### [Use response data](/tools/api-request/response-data)

Use the current result or extract values for subsequent tools.

#### [Lookup-based transfers](/calls/transfer-calls-with-api-lookup)

Look up a caller's branch, then transfer them with a Transfer Call tool.

## Related documentation

* [Create Tool API reference](/api-reference/tools/create)
* [Update Tool API reference](/api-reference/tools/update)
* [Get Tool API reference](/api-reference/tools/get)
* [Create Assistant API reference](/api-reference/assistants/create)
* [Update Assistant API reference](/api-reference/assistants/update)
* [Get Call API reference](/api-reference/calls/get)
* [Built-in tools](/tools/default-tools)
* [Static variables and aliases](/tools/static-variables-and-aliases)
* [Argument encryption](/tools/arguments-encryption)

> Call an HTTP endpoint from an assistant with a structured request and use its response

## Docs

- [API Request tool quickstart](https://docs.vapi.ai/tools/api-request/quickstart.md): Build a coffee-order assistant that sends confirmed orders to a public endpoint and reads the server-calculated total and order number back to the caller.
- [Customize API Request tool requests](https://docs.vapi.ai/tools/api-request/configuration.md): Configure an API Request Tool's URL, method, model-generated body, request headers, static body fields, and Liquid values with Dashboard and cURL examples.
- [Get order status](https://docs.vapi.ai/tools/api-request/order-status.md): Add an order-status API Request Tool to the coffee-order assistant, update its opening and system prompt, and verify status lookup across two inbound calls.
- [Handle API Request Tool latency and retries](https://docs.vapi.ai/tools/api-request/reliability.md): Learn how API Request Tool timeouts and failed HTTP requests behave, keep callers informed, and handle safe retries in a service you control.
- [Handle API Request tool responses and errors](https://docs.vapi.ai/tools/api-request/response-handling.md): Handle successful and failed API Request Tool responses, test structured errors, guide assistant recovery, and inspect call results in the Dashboard or with cURL.
- [Use API Request tool response data](https://docs.vapi.ai/tools/api-request/response-data.md): Use API Request Tool JSON responses immediately, extract response fields with schemas or aliases, and pass extracted variables to subsequent tools.