AssistantsTools

When to use API Request or Function tools

Choose API Request for direct HTTPS APIs and Function for Vapi tool-calls webhooks

Use an API Request tool when your assistant needs to call an ordinary HTTPS API. Use a Function tool when your server implements Vapi’s tool-calls webhook protocol, when the tool must run asynchronously, or when it runs in the browser through the Web SDK.

If you are unsure, start with an API Request tool.

Choose a tool

Your integrationUseWhy
Calls an existing REST APIAPI Request toolVapi builds and sends a direct HTTP request.
Needs a configurable URL, method, headers, or JSON bodyAPI Request toolThese are available fields on the tool.
Returns JSON that the assistant should use immediatelyAPI Request toolThe successful JSON response becomes the tool result.
Receives Vapi call, assistant, artifact, and tool-call contextFunction toolVapi sends a tool-calls webhook envelope to your server.
Routes several custom tools through one webhookFunction toolYour server can dispatch calls by tool name and correlate results with toolCallId.
Runs without waiting for a resultFunction toolFunction tools support top-level async: true.
Triggers a browser-side action through the Web SDKFunction toolA Function tool without a server URL can emit a client-side tool-calls event.
Must translate Vapi tool calls into XML, multipart data, or another custom protocolFunction tool with an adapterYour webhook can transform the Vapi request before calling the downstream service.
Uses live call controlFunction toolThe webhook includes call context and message.call.monitor.controlUrl, allowing your server to transfer, hand off, end, speak into, or add messages to the active call.

Compare how they work

BehaviorAPI Request toolFunction tool
DestinationA required HTTPS url configured directly on the toolFor server-side execution, a Vapi-aware webhook selected in this order: tool, assistant, phone number, then organization server URL
What receives the callThe destination API receives a direct HTTP requestA server receives an HTTP POST containing a Vapi tool-calls message with tool and call context; a client-side tool emits a Web SDK tool-calls event instead
HTTP methodChoose GET, POST, PUT, PATCH, or DELETEVapi sends a POST request to your Function webhook
Model-generated input schemaTop-level bodyfunction.parameters
Static valuesparameters are added to the request body and override model-generated values.parameters are added to the function arguments and override model-generated values
AuthenticationTop-level credentialIdThe credential on the selected server configuration, such as tool.server.credentialId
Successful responseA 2xx response containing valid JSONFor synchronous tools, HTTP 200 with a string result matched to each toolCallId
Failure responseA non-2xx response or invalid JSON fails the requestFor synchronous tool-specific failures, return HTTP 200 with a string in the matching results[].error
ExecutionSynchronous; the assistant waits for the destination APISynchronous by default; with top-level async: true, the assistant continues without waiting for the webhook response
Web SDK callsSupported; Vapi executes the API requestSupported; Vapi can call a server webhook or emit a client-side event
Performs custom, server-driven Live Call ControlFunction toolThe webhook includes call context and message.call.monitor.controlUrl, allowing your server to control the active call.

Both tool types let the model decide when to call the tool and which model-generated arguments to supply. Validate caller-controlled values at the destination before using them for sensitive actions.

API Request tool example

This tool sends a direct request to an existing order API:

{
  "type": "apiRequest",
  "name": "createOrder",
  "description": "Creates an order only after the caller confirms the product and quantity.",
  "method": "POST",
  "url": "https://api.example.com/orders",
  "credentialId": "550e8400-e29b-41d4-a716-446655440000",
  "body": {
    "type": "object",
    "properties": {
      "productId": {
        "type": "string",
        "description": "The product confirmed by the caller."
      },
      "quantity": {
        "type": "integer",
        "minimum": 1,
        "description": "The confirmed quantity."
      }
    },
    "required": ["productId", "quantity"],
    "additionalProperties": false
  },
  "parameters": [
    {
      "key": "source",
      "value": "voice-assistant"
    }
  ],
  "timeoutSeconds": 10
}

The destination receives a JSON body:

{
  "productId": "coffee-beans",
  "quantity": 2,
  "source": "voice-assistant"
}

It can return the result directly:

{
  "success": true,
  "orderId": "ord_123",
  "totalDisplay": "$36.00"
}

Function tool example

This tool sends a Vapi webhook to infrastructure that you control:

{
  "type": "function",
  "async": false,
  "function": {
    "name": "lookupCustomer",
    "description": "Looks up a customer after confirming their email address.",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "description": "The confirmed customer email address."
        }
      },
      "required": ["email"],
      "additionalProperties": false
    }
  },
  "server": {
    "url": "https://example.com/vapi/tools",
    "credentialId": "0000000-0000-0000-0000-00000000000",
    "timeoutSeconds": 10
  }
}

Vapi sends a tool-calls message that includes the tool call and call context. Your server must return a result associated with the incoming tool-call ID:

{
  "results": [
    {
      "toolCallId": "call_abc123",
      "result": "{\"found\":true,\"customerId\":\"cus_456\"}"
    }
  ]
}
API Request tool

Call an HTTP endpoint directly from an assistant with a structured request.

Function tools

Connect an assistant to your own server through Vapi’s tool-calls webhook.

Client-side tools

Handle tool calls in the browser through the Web SDK, with no server URL.

Configure requests

Add headers, static fields, Liquid values, and authentication to a request.

Handle responses and errors

Design response contracts and recover from failed tool calls.

Static variables and aliases

Inject server-controlled values and chain data between tool calls.

Create Tool API reference

The complete tool creation API reference.