API tools for AI assistants
Connect an AI assistant to an authorized HTTP service, such as an order lookup or booking workflow. Define the tool, enable it for the character and check the service response.
A tool is an HTTP endpoint the character is allowed to call mid-conversation. It decides for itself when the conversation calls for it, fills in the parameters from what the person said, calls your API, and works the result into its answer.
Tools are defined once for the workspace in the top bar's Knowledge › Tool Registry ("APIs and actions your characters can call"). The page lists every tool with its category badge and its method and endpoint, and has two buttons: Execution Log and New tool. Each character then gets its own switch per tool on the editor's Behavior › Tool Registry tab.
Start from a template
New tool opens the New Tool form with five Ready-Made Templates. Click one and the whole form fills in; a message then lists what you still have to fill in — usually just the URL and the key.
| Template | What it does | You provide |
|---|---|---|
| Weather (Open-Meteo) | Current weather for a latitude and longitude | Nothing — it needs no key. The best first test. |
| Banking (n8n webhook) | Routes transfers, balance inquiries and similar requests to an n8n workflow; identity verification required | n8n webhook URL + webhook secret key (header) |
| TC ID Verification (NFC + Face) | Verifies the TC ID read from the chip, with a live face match | Identity server URL + bearer token |
| Noise Reduction (DeepFilterNet) | Cleans the microphone recording before transcription | DeepFilterNet server URL |
| IBAN Spelling Correction | Normalizes IBAN and TC numbers in the transcription to the standard format | Server URL (optional) |
Defining your own
| Field | What to enter |
|---|---|
| Name (the LLM will see this) | Lower case letters, digits and underscores, starting with a letter or underscore — send_email, check_order. Each name is used once per workspace. |
| Category | Banking, Assistant, External API or Custom. Labelling only; it sets the badge in the lists. |
| Description (the LLM reads this — it knows when to call it) | The most important field. Write the trigger, not the mechanics: "Use this when the customer asks about the status of an existing order." This sentence is the basis on which the character decides to call it. |
| Endpoint and Method | Your URL, reachable from the public internet, and GET, POST, PUT, PATCH or DELETE (POST by default). |
| Auth Type | None · Bearer Token · Basic Auth · API Key (header) · API Key (query). |
| Timeout (ms) | How long to wait before giving up — 5,000 by default, at most 30,000. Keep it short for anything in a live conversation; nobody waits half a minute mid-sentence. |
| Parameter Schema (JSON Schema) | The inputs. Give every parameter a plain-language description — that is what the model reads when filling it in. |
| Identity must be verified (under Security) | Blocks the call unless the person has been verified with their TC ID over NFC and a face match. Turn it on for anything touching money or personal records. |
What your endpoint receives
- GET and DELETE — the parameters arrive in the query string, for example
?latitude=41.0&longitude=29.0. A DELETE request also carries them in a JSON body with the_metaobject described below. - POST, PUT and PATCH — the parameters arrive as a JSON body, together with a
_metaobject holdingtenant_idandsession_id. - The answer — return JSON (anything else is passed on as text). A non-2xx status, a redirect or a timeout is reported to the character as an error, so it can tell the person the request did not go through.
Attaching it to a character
Defining a tool does not give any character permission to use it. Open the character's Behavior › Tool Registry tab and switch it on there ("Enable …"). Tools that require identity show an Identity required badge. The same banking tool can be available to your verified-customer character and invisible to the one on your public website.
Security
- Your endpoint must be publicly reachable. Addresses that resolve to your local network,
localhostor other private ranges are refused on purpose — otherwise a character could be talked into probing private infrastructure from inside our servers. Redirects are refused for the same reason. Self-hosted automation needs a public address or a tunnel. - Secrets stay on the server. The character knows only the tool's name, description and parameters — never its URL secrets or keys. When you open a saved tool, its token, password and key value fields appear empty — the studio does not load them back — and leaving them empty keeps the saved value.
- Identity gating is enforced server-side. A tool marked Identity must be verified is refused even if the character decides to call it. TC ID verification is a plan feature, set up on the character's FaceID tab.
- Design for a confused caller. The character is talking to a human who may be wrong. Your endpoint should validate everything and fail with a clear message the character can read out.
The execution log
Execution Log on the Tool Registry page opens the Tool Execution Log: the audit trail of every tool the AI has called. Totals at the top show Total calls, Successful, Failed and Distinct tools. Under Filters you can search by tool name, character, speaker or arguments, pick one tool, and choose a date range of the last 1, 7, 30 or 90 days. Each call, newest first, shows ok or error, the character, the speaker, the Arguments, the Result or Error, and a View session link to the conversation that triggered it.
Editing and removing
Edit on a tool (or the edit icon on a character's Tool Registry tab) reopens the same form as Edit Tool. Changes apply to conversations that start after the save. The trash icon asks for confirmation, then removes the tool from the workspace and from every character it was enabled for.