> ## Documentation Index
> Fetch the complete documentation index at: https://wiredesk.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API calls

> Let the agent look things up in your own systems mid-conversation.

An **API call** action gives the agent a tool that calls an HTTP endpoint of yours — an order lookup, a stock check, an appointment search. The agent decides when to call it from the description you write, fills in the parameters from the conversation, and answers from the response.

Add one on the agent's **Actions** page with **Add action → API call**. It is one of several [action types](/docs/actions/overview).

## Fields

| Field                                | What it is                                                                                                                                                                                                    |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tool name**                        | What the agent calls the tool, e.g. `look_up_order`. 3–40 characters of lowercase letters, digits and underscores, starting with a letter, and not one of the [reserved names](/docs/actions/overview#tool-names). |
| **When should the agent call this?** | The description the agent reads to decide when to use it. Required, up to 500 characters. Be specific: "When the customer asks where their order is and gives an order number."                               |
| **Method**                           | `GET`, `POST`, `PUT`, `PATCH` or `DELETE`.                                                                                                                                                                    |
| **URL**                              | Must be `https`. Parameters go in as `{{name}}`, URL-encoded: `https://api.example.com/orders/{{order_number}}`                                                                                               |
| **Params the agent fills in**        | Each one has a key, a description, and whether it is required. The agent will not call the tool without the required ones. Up to 10.                                                                          |
| **Request body**                     | For `POST`, `PUT` and `PATCH`. `{{name}}` placeholders are filled in as-is, and it is sent as `application/json`. Up to 4,000 characters.                                                                     |
| **Authentication**                   | **None**, **Bearer token**, or **X-Api-Key header**, using a saved API credential.                                                                                                                            |
| **Channels**                         | Which of voice, chat and email the action is available on.                                                                                                                                                    |

Every `{{placeholder}}` in the URL or body must be a declared param; saving fails otherwise.

## Example

A `GET` order lookup:

```text theme={null}
URL      https://api.example.com/orders/{{order_number}}
Params   order_number — "The customer's order number, e.g. 10482" (required)
Auth     Bearer token
```

When a customer asks "where is order 10482?", the agent calls:

```http theme={null}
GET /orders/10482 HTTP/1.1
Host: api.example.com
Authorization: Bearer <your saved credential>
```

The agent gets back the HTTP status code and the response body, and answers from them.

## API credentials

Add the key under **Authentication** while setting up the action, rather than pasting it into the URL: choose **Add a new key…** under **API key** and enter a label and the secret. It is stored encrypted, never shown again, and never given to the agent — it is only attached to the request. Saved keys are listed under **API credentials** on the **Actions** page, by label and last four characters, where they can be reused by other actions or removed.

If your API expects the key somewhere other than a header, put `{{credential}}` in the request body and the saved key is filled in there. It is never allowed in the URL.

Deleting a key stops every action that uses it until you attach a new one.

## Limits

* **Timeout:** 5 seconds on a phone call, 15 seconds on chat and email. On a call, the agent says a short holding line before calling.
* **Response size:** the agent reads the first 1,500 characters of the response on a call and the first 4,000 on chat and email. Return a small JSON object with just what the agent needs.
* **Redirects** are not followed. Point the URL at the final address.
* **Addresses:** the URL must be `https`, use a hostname rather than an IP address, and not point at a private network or `localhost`. This is checked again against the actual URL after parameters are filled in.
* Only the parameters you declared are filled in. The agent cannot add others.

If the call times out or fails, the agent is told and offers to follow up or take a message, and the conversation carries on.

## Designing the endpoint

* Return errors the agent can say out loud: `{"error": "No order 10482 — check the number on the confirmation email."}`.
* Treat every parameter as untrusted input from the public. The agent fills them from what a customer typed or said.
* Scope the credential to read-only access on what the action needs.

## Checking it works

Every call appears in the **Action log** under **Inbox → Extra fields**, with the tool name, `ok` or `failed`, how long it took, and a link to the conversation. `failed` means the request did not complete — a timeout, a redirect, a refused address. A response with an error status such as `404` still shows as `ok`, because your endpoint answered; read the conversation to see what the agent made of it.

Ask your agent a question that should trigger the action, then look there.

## Related

* [Actions overview](/docs/actions/overview)
* [Book meetings](/docs/actions/book-meetings)
* [Test your agent](/docs/agents/test-your-agent)
* [Security model](/docs/developers/security-model)