# HTTP request tool

Use `send_http_request` to let an Assistant book appointments, look up records, or call other external APIs during a conversation.

## Overview

The tool sends an HTTP request and returns the response body to the LLM.

Set the URL, HTTP method, headers, and parameter schemas in the Tool's `configuration`. The platform merges `pathSchema`, `paramSchema`, and `bodySchema` into one flat set of LLM parameters, then routes the supplied values to the path, query string, or request body.

<Mermaid chart={`sequenceDiagram
    participant LLM
    participant Assistant
    participant ExternalAPI as External API

    LLM->>Assistant: calls register_client(clientId, names)
    Note over Assistant: Vocalise message while request runs (optional)
    Assistant->>Assistant: Separate arguments into path / query / body
    Assistant->>Assistant: Substitute :param placeholders in URL
    Assistant->>ExternalAPI: POST /clients/abc/orders { "names": ["Alice"] }
    ExternalAPI-->>Assistant: 200 OK { "created": true }
    Assistant-->>LLM: { "created": true }`} />

***

## Naming and describing the tool

Set `nameOverride` and `descriptionOverride` to describe the action your HTTP endpoint performs. The LLM sees these values in the tool schema and uses them to decide when to call the tool.

| Field                 | Type   | Required | LLM-facing | Description                                                                                 |
| --------------------- | ------ | -------- | ---------- | ------------------------------------------------------------------------------------------- |
| `nameOverride`        | string | No       | Yes        | Replaces the tool's function name as seen by the LLM. Should read like a function name.     |
| `descriptionOverride` | string | No       | Yes        | Replaces the tool's description as seen by the LLM. Should explain when and why to call it. |

### Writing effective overrides

The `nameOverride` should read like a function name: short, lowercase with underscores, and descriptive of the action (`book_appointment`, `register_client`, `check_availability`). Avoid generic names like `do_request` or `call_api`.

In `descriptionOverride`, state when to call the tool and what result to expect.

**Example:**

```json
{
  "nameOverride": "book_appointment",
  "descriptionOverride": "Book an appointment for the caller. Call this tool when the caller confirms a date and time for their appointment."
}
```

:::info{title="Where to set overrides"}

`nameOverride` and `descriptionOverride` are set at the tool-association level (alongside `assistantId`, `definitionId`, and `configuration`). They are not part of the `configuration` object itself.

:::

***

## Configuration schema

The `configuration` object you provide when attaching the tool to an Assistant accepts the following fields.

| Field            | Type                  | Required | Default | Description                                                                                                                           |
| ---------------- | --------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `url`            | string                | Yes      |         | Request URL. Use `:param` for path parameters and `{variable}` for dynamic variable resolution at config load time.                   |
| `method`         | string                | No       | `GET`   | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.                                                                              |
| `headers`        | object                | No       | `{}`    | Key-value pairs sent as request headers. Supports `{variable}` resolution.                                                            |
| `timeout`        | number                | No       | `10`    | Request timeout in seconds.                                                                                                           |
| `message`        | string                | No       |         | Text the agent vocalises while the HTTP request runs. The tool waits for both the request and playback to finish.                                 |
| `pathSchema`     | JSON Schema           | No       |         | Describes the `:param` path placeholders in the URL.                                                                                  |
| `paramSchema`    | JSON Schema           | No       |         | Describes the query parameters appended to the URL.                                                                                   |
| `bodySchema`  | JSON Schema           | No       |         | Describes the JSON request body.                                                                                                      |
| `responseSchema` | JSON Schema or string | No       |         | Describes the expected response structure. Appended to the LLM-facing tool description so the model can interpret responses reliably. |

***

## Parameter schemas

The three schema fields, `pathSchema`, `paramSchema`, and `bodySchema`, each describe a different part of the outgoing HTTP request. All three follow standard JSON Schema syntax with `type`, `properties`, and `required`.

### Path parameters (`pathSchema`)

Path parameters map to `:param` placeholders in the `url`. At call time, each placeholder is replaced with the value the LLM provides.

Given a URL of `https://api.example.com/clients/:clientId`, the following schema lets the LLM supply `clientId`:

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "description": "Unique client identifier"
    }
  },
  "required": ["clientId"]
}
```

If the LLM passes `clientId = "abc-123"`, the resolved URL becomes `https://api.example.com/clients/abc-123`.

### Query parameters (`paramSchema`)

Query parameters are appended to the URL as a standard query string. They are useful for filtering, pagination, or any parameter that belongs in the URL rather than the body.

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["pending", "confirmed", "cancelled"],
      "description": "Filter orders by status"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of results to return"
    }
  }
}
```

### Request body (`bodySchema`)

The body schema describes the JSON payload sent in the request body. This is typically used with `POST`, `PUT`, and `PATCH` methods.

```json
{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "Customer first name"
    },
    "lastName": {
      "type": "string",
      "description": "Customer last name"
    },
    "email": {
      "type": "string",
      "description": "Customer email address"
    }
  },
  "required": ["firstName", "lastName"]
}
```

***

## Response schema (`responseSchema`)

Set `responseSchema` to describe the response fields the LLM should expect. The platform appends it to the tool description under "Response format:". Without it, the model receives the response body without a description of its structure.

**Example:**

```json
{
  "responseSchema": {
    "type": "object",
    "properties": {
      "status": {
        "type": "string",
        "description": "Appointment status"
      },
      "id": {
        "type": "string",
        "description": "Unique appointment identifier"
      },
      "date": {
        "type": "string",
        "description": "Confirmed date in YYYY-MM-DD format"
      },
      "time": {
        "type": "string",
        "description": "Confirmed time in HH:MM format"
      }
    }
  }
}
```

:::info{title="Description only"}

`responseSchema` describes the response but does not validate or transform it. The tool returns the response text, truncated after 5,000 characters when necessary.

:::

### Schema merging

The LLM does not see three separate schemas. When the tool is built, all properties from `pathSchema`, `paramSchema`, and `bodySchema` are merged into a single flat `parameters` object. The `required` arrays are combined with duplicate names removed.

For a tool named `register_client` with path parameter `clientId`, query parameter `category`, and body parameter `names`, the LLM-facing schema becomes:

```json
{
  "name": "register_client",
  "description": "Registers a list of client names under an existing client account.",
  "parameters": {
    "type": "object",
    "properties": {
      "clientId": {
        "type": "string",
        "description": "The client ID"
      },
      "category": {
        "enum": ["prospect", "client", "churned"]
      },
      "names": {
        "type": "array",
        "description": "Client names collected during the conversation.",
        "items": {
          "type": "string"
        }
      }
    },
    "required": ["clientId", "names"],
    "additionalProperties": false
  }
}
```

:::warning{title="Property name collisions"}

If the same property name appears in more than one schema, the last one wins following the merge order: `pathSchema` → `paramSchema` → `bodySchema`. A warning is logged, but the tool still builds. Avoid reusing property names across schemas. A parameter declared in `pathSchema` is also substituted into the URL even when its definition is overwritten by a query or body schema.

:::

***

## Dynamic variables

Use `{variable}` placeholders in string values anywhere in `configuration`. The platform resolves them from [variables](/docs/variables) and [injected data](/docs/data-injection) when loading the configuration, before building the tool.

For example, if you have:

* a Project-scoped variable with key `api_token`
* injected data with key `foo`

You can reference them in `configuration.headers`:

```json
{
  "headers": {
    "Authorization": "Bearer {api_token}",
    "X-Foo": "{foo}"
  }
}
```

:::info{title="Unresolved variables"}

An unresolved `{variable}` placeholder becomes an empty string. The tool still attempts the request, even if the resulting header or URL is incomplete.

:::

***

## Limitations

| Constraint                   | Limit                                                              |
| ---------------------------- | ------------------------------------------------------------------ |
| Response body size           | Truncated at 5 000 characters.                                     |
| Default timeout              | 10 seconds. Configurable via the `timeout` field.                  |
| Request body format          | JSON only. No form-data or file uploads.                           |
| Streaming responses          | Not supported. The full response is awaited before returning.      |
| Property name collisions     | Last schema wins (`bodySchema` > `paramSchema` > `pathSchema`). |
| Unresolved path placeholders | Left as literal `:param` in the URL, likely causing a 404.         |

***

## Full example

Attach an appointment-booking tool to an Assistant. Fetch the `send_http_request` definition with `GET /data_next/ai/toolDefinitions?where={"name":"send_http_request"}` and use its `id` as `definitionId`. Replace the example Assistant ID and token with your own, and define the `scheduling_api_key` variable before testing.

```http
POST https://newprd.reecall.io/data_next/ai/tools
Authorization: Bearer {token}
Content-Type: application/json
```

```json
{
  "definitionId": "a1b2c3d4-5678-4def-9abc-def012345678",
  "assistantId": "<your-assistantId>",
  "nameOverride": "book_appointment",
  "descriptionOverride": "Book an appointment for the caller. Use this tool when the caller confirms a date and time for their appointment.",
  "configuration": {
    "url": "https://scheduling.example.com/api/v1/appointments",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {scheduling_api_key}",
      "Content-Type": "application/json"
    },
    "timeout": 8,
    "message": "I'm booking that appointment for you now.",
    "bodySchema": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string",
          "description": "Appointment date in YYYY-MM-DD format"
        },
        "time": {
          "type": "string",
          "description": "Appointment time in HH:MM format (24h)"
        },
        "customerName": {
          "type": "string",
          "description": "Full name of the customer"
        },
        "reason": {
          "type": "string",
          "description": "Brief description of the appointment reason"
        }
      },
      "required": ["date", "time", "customerName"]
    },
    "responseSchema": {
      "type": "object",
      "properties": {
        "id": { "type": "string", "description": "Unique appointment identifier" },
        "status": { "type": "string", "description": "Booking status (e.g. confirmed, pending)" },
        "date": { "type": "string", "description": "Confirmed date in YYYY-MM-DD format" },
        "time": { "type": "string", "description": "Confirmed time in HH:MM format" },
        "customerName": { "type": "string", "description": "Customer name as recorded" }
      }
    }
  }
}
```
