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.
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:
Code
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:
Code
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.
Code
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.
Code
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:
Code
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:
Code
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 and injected data 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:
Code
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.
Code
Code