API tools¶
Status: Current | Last reviewed: 2026-06-12
An API tool calls a REST API. It comes in two flavours, chosen with the API tool type selector at the top of the tool form:
- OpenAPI specification: point TrueServe at an OpenAPI (Swagger) spec, pick the operations you want, and each becomes a callable tool.
- Manual endpoint: define a single endpoint by hand (method, URL, headers, body). Use this when there is no spec, or when you only need one call.
Both share the same authentication options.
OpenAPI specification¶
| Field | Required | Notes |
|---|---|---|
| Specification source | Yes | URL to fetch the spec from, or Inline to paste it. |
| Spec URL / Inline spec | Yes | The OpenAPI document, such as https://api.example.com/openapi.json, or pasted YAML/JSON. |
| Authentication | No | Same auth options as other tools. See Tools overview. |
| Custom headers | No | Extra HTTP headers sent on every call, as key/value pairs. |
| Selected operations | Yes | After TrueServe parses the spec, choose which operations to expose. Each selected operation becomes its own callable tool. |
Once parsed, the operation list shows everything the spec defines; select only what your agents should be able to call. Narrowing the set keeps the LLM focused and avoids exposing destructive endpoints by accident.
Manual endpoint¶
| Field | Required | Notes |
|---|---|---|
| Method | Yes | GET, POST, PUT, PATCH, or DELETE. |
| Endpoint URL | Yes | Full request URL, e.g. https://api.example.com/v1/orders/{order_id}. Supports {variable} templating (below). |
| Request headers | No | Static or templated headers. Do not set Authorization here; Authentication injects it. |
| Request body | POST/PUT/PATCH | JSON body with {variable} substitution. If it parses as JSON it's sent as the request body; otherwise it's sent as a templated string. |
| Response path | No | JSONPath-lite (e.g. $.data.results[0]) applied to the JSON response before it's returned to the model. Leave blank to return the whole response. |
| Authentication | No | Same auth options as other tools. See Tools overview. |
| Parameters | No | The arguments the model fills in. These become {variable} values and the tool's input schema. |
Variable templating¶
Anywhere in the URL, headers, or body you can write {name}. At call time {name} is replaced with:
- the parameter of that name the model supplied (your declared parameters), then
- a session variable of that name if no parameter matches, such as
{conversation_id},{ani},{dnis},{tenant_id}.
Session variables resolve when the tool runs inside a conversation or workflow; when an agent calls the tool directly with no session context, only the model-supplied parameters resolve. An unmatched {name} is left as-is.
For example, an endpoint https://api.example.com/v1/callers/{ani}/orders with a POST body of {"note": "{note}", "session": "{conversation_id}"} injects the caller's number from the live session, the model's note argument, and the conversation id.
Inline API tools on an agent¶
In an agent's Prompt tab, the Tools dropdown includes Create Inline API Tool alongside Create Inline Python Tool. An inline API tool is a single manual endpoint saved inside that agent stage only. It does not appear in the shared Tools list, and other agents cannot use it unless you recreate it there.
Inline API tools use the same Manual endpoint fields (method, URL, headers, body, response path, parameters) and the same {variable} templating described above. One difference: because an inline tool has no saved record to attach a one-off secret to, authentication is integration-backed only. Pick None, Integration, or OAuth 2.0. For an inline bearer/API-key credential, create a shared API tool instead, or store the credential on an integration and reference it.
When a tool needs more information¶
If an API tool is missing a required value, or the API says a value does not look right, the agent can ask the caller for that information in plain language and retry. For example, instead of showing a raw field name or status code, the caller may hear or see: "I need your customer ID to continue. Could you provide it?"
Use clear parameter names, labels, and descriptions when you configure the tool. Those labels are used in the caller-facing prompt. Secrets such as passwords, tokens, API keys, and credentials are never requested from the caller; those remain configuration issues for an admin to fix.