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

# Connect an API so your agent can call your systems

> Create an API request tool: URL, method, authentication, headers, parameters and timeout, how to test it, and how single prompt and flow agents send it.

An API request tool calls one endpoint of your system during a call, with values the agent collected from the caller. Use it to look up an order, check availability, create a ticket or anything else your API can do. This page covers every setting, how to test the tool, and the differences between single prompt and flow agents when they send the request.

## Before you start

* You need permission to create tools. See [APIs & MCPs](https://docs.tryhamsa.com/agents/tools/overview.md#before-you-start).
* Your endpoint must be reachable from the internet over HTTPS.
* If the API needs a key or password, store it first as a [secret](https://docs.tryhamsa.com/agents/tools/secrets.md).

## Create an API request

**1. Start a new tool**

Open **APIs & MCPs**, click **Add new tool** and choose **API request**. The form **Add new API request** opens.

**2. Name and describe it**

Enter a **Tool name** and a **Description**. Write the description for the agent: what the tool does and when to use it, for example "Looks up the status of an order. Use it when the caller asks where their order is."

**3. Set the request**

Under **Tool settings**, enter the **URL**, pick the **Method**, and set **Authentication** and **Headers** if your API needs them.

**4. Define the parameters**

Under **Function configuration**, add the **Parameters** the agent should send, with a clear description for each.

**5. Save and test**

Click **Create**, then open the tool and click **Test** to send a sample request.

Then attach the tool to an agent: in a single prompt agent under **Tools**, in a flow with a **Tool** step. See [Attach a tool to an agent](https://docs.tryhamsa.com/agents/tools/overview.md#attach-a-tool-to-an-agent).

![The Add new API request form with Tool name get\_order\_status, a description, the URL and Method GET](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/tools/api-request-form-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=21613457a7413398be918af828e4c815)

## Settings

| Field | What it does | Default |
| - | - | - |
| **Tool name** | The name the agent sees. Up to 250 characters, unique in the project, with at least one letter. | |
| **Description** | Tells the agent what the tool does and when to call it. Up to 1,000 characters. | |
| **URL** | The endpoint to call. Must start with `https://`. | |
| **Method** | GET, POST, PUT, PATCH or DELETE. | POST |
| **Timeout** | How long to wait for an answer, in seconds, from 1 to 60. See [Timeouts](#timeouts). | 5 |
| **On hold music** | Plays hold music to the caller while the tool runs (single prompt agents). | Off |
| **Authentication** | How the request proves who it is. See [Authentication](#authentication). | **No authentication** |
| **Headers** | Extra HTTP headers. Click **Add header**, then enter **Header name** and **Header value**. | `Content-Type: application/json` (**Auto**) |
| **Async execution** | Don't wait for the result. See [Async execution](#async-execution). | Off |
| **Payload type** | **Object (JSON)** sends named parameters. **Array (JSON)** sends a list. Switching resets the parameters. | **Object (JSON)** |
| **Parameters** | The values the agent fills in and sends. | None |

Header names can contain letters, numbers, hyphens and underscores, and must be unique. Headers that browsers forbid (such as `Cookie`, `Host`, `User-Agent` or `Content-Length`) are refused.

## Authentication

| Option | What is sent | When to use it |
| - | - | - |
| **No authentication** | Nothing. | Public endpoints. |
| **Bearer token** | `Authorization: Bearer <token>` | Most modern APIs (OAuth 2.0, JWT, API keys). |
| **Token** | `Authorization: Token <token>` | APIs that expect the `Token` scheme, such as GitHub or GitLab. |
| **Basic authentication** | `Authorization: Basic <username:password, base64-encoded>` | APIs that use a username and password. |

![The API request form with Authentication set to Bearer token holding a secret, and an X-Store-Id header](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/tools/api-request-auth-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=65ae7d191b33c9479eaf4c0081360018)

To use a secret, click the key icon next to the token field and pick the secret. The field then holds `{{secrets.NAME}}`, and the value is filled in when the request is sent. Basic authentication can't use a secret: the username and password are stored with the tool.

Use either **Authentication** or your own `Authorization` header, not both.

## Parameters

Parameters are the values the agent sends in the request. For each one, set:

* **Name**: the key your API expects, for example `order_id`.
* **Type**: string, number, boolean, array or object.
* **Description**: what the value is and how to get it, for example "The 8-digit order number the caller reads from their receipt." The agent reads it to know what to ask for.
* **Required**: whether the request needs it.
* **Enum values** (strings only): a fixed list of allowed values, one per line.

![The Request body parameters dialog with an order\_id parameter of type String, Required, and its description](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/tools/api-request-parameters-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=c7245fd398bb374ba3af0166b85d504c)

The agent collects the values from the conversation. To send a value the caller never says, such as a customer ID passed when the call starts, set the parameter in the agent's **Tool configuration** to a [variable](https://docs.tryhamsa.com/agents/variables/overview.md) instead. See [Change a tool for one agent](#change-a-tool-for-one-agent).

## Single prompt and flow agents

Both types of agent fill in `{{variables}}` and `{{secrets.NAME}}` in the **URL**, header values, token and parameter values when the request is sent. A few other things differ depending on the type of agent that calls the tool.

| | Single prompt agent | Flow agent |
| - | - | - |
| How parameters are sent | Always as a JSON body, also for GET. | GET: in the query string (text, number and true/false values). POST, PUT, PATCH: JSON body. DELETE: no body. |
| Hold music | The tool's **On hold music**. The caller isn't heard while it plays. | The step's **Put on hold**. The tool's **On hold music** is not used. The caller is still heard, and what they say is answered by the next step that speaks. |

You can build the URL from a variable, for example `https://api.example.com/orders/{{order_id}}`, where `order_id` is a variable the agent already has.

## Timeouts

A request that takes longer than the tool's **Timeout** fails. A single prompt agent is told the action couldn't be completed; a flow's Tool step takes **On failure**. The default of 5 seconds suits fast lookups; raise it for slower APIs, up to 60. An agent can set its own **Timeout** for the tool in **Tool configuration**.

## Test the tool

Open the tool and click **Test** (in a flow, the **Test tool** button on a **Tool** step does the same). Enter sample values for the parameters and run it. The test shows the response, which you can use to set up the values a flow step extracts.

Under **Advanced configuration** you can change the URL, method, authentication, headers and **Request timeout (seconds)** for this test only.

> [!NOTE]
>
> The test sends the request from Hamsa's servers and fills in secrets, as calls do. If the tool uses variables that have no value yet, for example when you test it from **APIs & MCPs** before attaching it to an agent, **Test** first asks you for a value for each one, then sends the request with them filled in. The test may retry a failed request up to three times; calls don't retry.

## Change a tool for one agent

Each agent can change a tool's settings without changing the tool for other agents. In a single prompt agent, open **Tool configuration** under **Tools**. In a flow, open the **Tool** step and its **Tool configuration**.

You can change the **Tool name**, **Tool description**, **URL**, **HTTP method**, **Auth type** and **Token**, **Timeout (seconds)**, **HTTP headers**, **Async execution** and **On hold music**. For each parameter, choose **AI extraction** (the agent collects it) or a fixed value or variable, or **Disable** it to leave it out of the call: the agent isn't asked for it and it isn't sent. You can disable a header the same way. You can also add **Custom parameters** and **Custom headers** that the tool doesn't define.

Basic authentication can't be changed here: "Basic Authentication must be configured in the tool definition."

## Async execution

With **Async execution** on, the agent starts the request and carries on without waiting.

* **Single prompt agents** are told the task started in the background. They never get the result, so use async only for requests whose answer the caller doesn't need, such as logging a lead.
* **Flow agents**: switching a step to async replaces **On success** and **On failure** with a single **Move to** transition, and the app asks you to confirm because existing connections are removed. The flow moves on at once. When the response arrives, the step's extracted variables are still set from it, but no transition follows from the result.

## How it works on a call

**Single prompt agents** pass the result to the model, which uses it to answer the caller:

| Result | What the agent is told |
| - | - |
| Success (2xx) | The full response body. |
| Your API answers with an error status | The first 400 characters of the response, with an instruction to explain it to the caller in plain words. Return a readable reason, such as "This slot is already booked", so the agent can pass it on. |
| Timeout or network error | That the request couldn't be completed, to offer to try again or help another way, and not to mention technical details. |

**Flow agents** don't show the response to the model. A 2xx answer takes **On success**; anything else, including a timeout, takes **On failure**. To use data from the response in later steps, extract it into variables on the step. See [API request step](https://docs.tryhamsa.com/agents/flow/steps/api-request.md).

## Good to know

* Name tools in lowercase words joined by underscores, such as `get_order_status`. Single prompt agents show the name to the model in lowercase, with spaces and symbols turned into `_`.
* Each save creates a new version. Agents keep their version until you click **Sync to latest** on the agent's tool.
* You can't delete a tool while an agent uses it.

## Related

> [card] [API request step](https://docs.tryhamsa.com/agents/flow/steps/api-request.md)
>
> Call an API from a flow, with processing messages and extracted variables.

> [card] [Secrets](https://docs.tryhamsa.com/agents/tools/secrets.md)
>
> Store API keys and reference them in tools.

> [card] [Variables](https://docs.tryhamsa.com/agents/variables/overview.md)
>
> Values you can send in a request.

> [card] [APIs & MCPs](https://docs.tryhamsa.com/agents/tools/overview.md)
>
> How agents use tools on a call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.