AssistantsTools

API Request Tool

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

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

BehaviorAPI Request Tool behavior
EndpointSends requests to an HTTPS URL.
HTTP methodsSupports GET, POST, PUT, PATCH, and DELETE.
Model-generated valuesUses the body JSON Schema to define values the model can supply.
Server-resolved valuesSupports fixed values and Liquid templates in the URL, request headers, and static body fields.
AuthenticationApplies a reusable Vapi credential through credentialId.
TimeoutUses 20 seconds by default; timeoutSeconds accepts 1–300 seconds.
RetriesDoes not retry unless backoffPlan is configured. Fixed and exponential backoff are supported.
ExecutionWaits synchronously for the destination API before returning a result to the assistant.
Response dataMakes the current result available to the model. Variable extraction requires a JSON response.

See the Create Tool and Update Tool API references for the complete request schemas.

Start with a working example

Coffee-order quickstart

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

Configure requests

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

Handle latency and retries

Set timeouts, retry safe requests, and keep callers informed while a request runs.

Handle responses and errors

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

Use response data

Use the current result or extract values for subsequent tools.