> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/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)