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

# API Requests

> Configuring external API integrations for voice agents.

You can create API request definitions in the **API Requests** tab of the Voice Wizard. Click **"Add API request"** and you will see the following input form with the fields explained below.

![API Request Configuration Form](https://mintcdn.com/miyon/k1W2EMCYe3WDkNuH/images/create-api-request-modal.png?fit=max\&auto=format\&n=k1W2EMCYe3WDkNuH\&q=85\&s=68a9015c270ef5d03621707e0fbca12e)

## Form fields explained

### API request name

A descriptive name for your API request (e.g. "Create product order")

### URL

The API endpoint URL. You can use placeholders like `{{userId}}`, which are replaced with values from your **dynamic** function parameters.

* Example: `https://api.shop.com/orders/{{userId}}`

### HTTP method

Choose the HTTP method for your request (GET, POST, PUT, DELETE, etc.)

### API key

Your authentication token. It automatically replaces all `{{api_key}}` placeholders in your URL or headers.

### Headers

HTTP headers for your request in JSON format:

```json theme={null}
{
  "Authorization": "Bearer {{api_key}}",
  "Content-Type": "application/json"
}
```

* `{{api_key}}` is replaced with your API key

### Function definition (dynamic parameters)

Define the parameters that users can pass when calling your function:

```json theme={null}
{
  "type": "function",
  "name": "place_order",
  "description": "Bestellt ein Produkt für einen Kunden",
  "parameters": {
    "type": "object",
    "properties": {
      "userId": {
        "type": "string",
        "description": "Kunden-Benutzer-ID"
      },
      "orderDetails": {
        "type": "object",
        "properties": {
          "product": {"type": "string"},
          "quantity": {"type": "number"}
        }
      }
    }
  }
}
```

These parameters will:

* Replace matching placeholders in the URL and headers
* **All dynamic parameters that do not match any placeholder are added to the request body**
* **Works with nested objects** -- e.g. the `orderDetails` object is preserved in the body

### Fixed parameters

Static values that are always included in every request:

```json theme={null}
{
  "storeId": "STORE_123",
  "paymentMethod": "credit_card",
  "currency": "USD"
}
```

These are:

* **Always added to the request body unchanged**
* They do NOT replace placeholders in headers or the URL

### Variables

**Variables** expose values from the API response as `{{tool.<tool-name>.<variable>}}` and pass them to other tools or to post-processing — server-side, so the value never passes through the AI. This lets you chain several API requests together.

Example: the `kunde_suchen` tool returns an `id`, and the `bestellungen_abrufen` tool then uses it to fetch the customer's orders.

**1. Define variables**

Expand the **"Variablen"** section in the tool and fill in, per row:

* **Variable** – the name you reference the value by (e.g. `id`).
* **Response path** – the path to the value in the response in dot notation, starting with `response.` (e.g. `response.id` or `response.data.id`).
* **Default value** (optional) – sent when the value is missing from the response.

  ![The "Variablen" section with defined variables](https://mintcdn.com/miyon/XnCGtL5z66Wx0Hp8/images/api-tool/variables-extracted.jpg?fit=max\&auto=format\&n=XnCGtL5z66Wx0Hp8\&q=85\&s=a1c3b72714f8d8ab18cb6327ce9946ce)

Reference the variable as `{{tool.<tool-name>.<variable>}}`, e.g. `{{tool.kunde_suchen.id}}`.

**2. Capture fields from the test response (optional)**

Instead of typing the path manually, click **"Variablen extrahieren"**: the API is tested once and you capture fields directly from the real response. Use the search to find the right field quickly.

![Capture fields from the test response](https://mintcdn.com/miyon/XnCGtL5z66Wx0Hp8/images/api-tool/variables-picked-from-response.jpg?fit=max\&auto=format\&n=XnCGtL5z66Wx0Hp8\&q=85\&s=fb39b6f8948f691a65ae24891c3540a0)

A **green check** means the path was found as a single value in the last test response:

![Path found in the test response](https://mintcdn.com/miyon/XnCGtL5z66Wx0Hp8/images/api-tool/picked-vars-found-in-response.jpg?fit=max\&auto=format\&n=XnCGtL5z66Wx0Hp8\&q=85\&s=ce73416abc34c3db6afc8b8044bdbe01)

An **amber icon** means it wasn't found there as a single value (e.g. a typo or a wrong path):

![Path not found in the test response](https://mintcdn.com/miyon/XnCGtL5z66Wx0Hp8/images/api-tool/picked-var-not-found-in-response.jpg?fit=max\&auto=format\&n=XnCGtL5z66Wx0Hp8\&q=85\&s=3c36bbdc7de8fd49efe1953b32ec7241)

**3. Use the variable in another tool**

Use the variable in another API tool's **URL**, **headers** or **fixed parameters** (request body). As soon as you type `{{`, a dropdown appears to pick the variable.

![Variable dropdown when typing two curly braces](https://mintcdn.com/miyon/XnCGtL5z66Wx0Hp8/images/api-tool/vars-dropdown.jpg?fit=max\&auto=format\&n=XnCGtL5z66Wx0Hp8\&q=85\&s=bfbda17627c129845fca3850da2b0b7f)

**4. Test a chained request**

If a request uses variables from other tools, enter a sample value under **"Testwerte für Variablen"** when testing, so you can test the request on its own — without a real call.

![Test values for variables in the test dialog](https://mintcdn.com/miyon/XnCGtL5z66Wx0Hp8/images/api-tool/customer-orders-search-with-var.jpg?fit=max\&auto=format\&n=XnCGtL5z66Wx0Hp8\&q=85\&s=fe02bd160b2e024099e80cafd2eecffa)

> [!NOTE]
>
> Variables are resolved **server-side** and inserted directly into the outgoing request — the value never passes through the AI. This is reliable and also safe for sensitive values such as tokens, which the AI might otherwise corrupt.

**Where you can use variables:** in the **URL**, **headers** and **fixed parameters** (request body), and in **post-processing** (email/SMS templates) — typing `{{` opens a dropdown everywhere. **Not yet available** in call forwarding or the prompt/greeting, since those are resolved before any tool runs.

**When a value is unavailable:** if the source tool hasn't run yet in the conversation, the variable is sent empty (or the default value, if set). The conversation view shows, on the relevant tool call, that a variable was unavailable.

![Conversation view note: a variable was unavailable](https://mintcdn.com/miyon/XnCGtL5z66Wx0Hp8/images/api-tool/var-not-extracted-conversations.jpg?fit=max\&auto=format\&n=XnCGtL5z66Wx0Hp8\&q=85\&s=300f549aadc85f619b3ce1dfc3748ce8)

### Say before

An optional message the AI assistant says to the user before the API request is executed. For example: "Ich erstelle jetzt Ihre Bestellung..." or "Einen Moment, ich rufe die Produktinformationen ab..."

## Example: GET request without dynamic parameters

Some API calls don't need any parameters from the AI -- for example "Get all products". In this case, a function definition is still required so that the AI triggers the API request.

![API Request Configuration for GET without parameters](https://mintcdn.com/miyon/k1W2EMCYe3WDkNuH/images/create-api-request-modal-empty-request.png?fit=max\&auto=format\&n=k1W2EMCYe3WDkNuH\&q=85\&s=5175f465f9581a6cb5c7d242cc668abe)

### Configuration for "Get all products"

* **API request name**: "Get all products"
* **URL**: `https://example.proxy.beeceptor.com/products` (example test endpoint)
* **HTTP method**: GET
* **API key**: (empty or your API key)
* **Headers**: Standard GET headers

### Function definition without parameters

Click **"No dynamic parameters"** to get a template:

```json theme={null}
{
  "type": "function",
  "name": "listProducts",
  "description": "Get all available products from the catalog",
  "parameters": {
    "type": "object",
    "properties": {}
  }
}
```

**Important:**

* A meaningful **function name** and **description** are crucial, because the AI needs to understand when to call the function
* Add explicit instructions in the **user prompt** if the AI has trouble
* The empty `properties: {}` is required for a valid function definition

### Resulting HTTP request

Based on the configuration above, the following HTTP request is created:

```
GET https://example.proxy.beeceptor.com/products
Content-Type: application/json
```

**Explanation:**

* **URL**: Direct URL without placeholder substitutions
* **Headers**: GET headers with Bearer API token
* **Parameters**: No dynamic parameters required

## How the final request is built

1. **URL**: Placeholders are replaced with dynamic function parameters
2. **Headers**: `{{api_key}}` is replaced with the API key, other placeholders with dynamic parameter values
3. **Body**: Combination of fixed parameters + dynamic parameters that don't match any placeholder

### Example of the final HTTP request

Based on the parameters above, the following HTTP request is created:

```
POST https://api.shop.com/orders/user123
Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

{
  "storeId": "STORE_123",
  "paymentMethod": "credit_card",
  "currency": "USD",
  "orderDetails": {
    "product": "Wireless Headphones",
    "quantity": 2
  }
}
```

**Explanation:**

* **URL**: `{{userId}}` was replaced with "user123"
* **Headers**: `{{api_key}}` was replaced with your actual API key
* **Body**: Contains both fixed parameters (storeId, paymentMethod, currency) and dynamic parameters (orderDetails)


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