Core resources

Tools

Tools are functions the assistant can call mid-conversation (function calling) — look up an order, book a slot, hit your API, or search a knowledge base. Define a tool with a name, description, JSON-schema parameters and a type-specific config, then attach it to an assistant.

Tool types

The type field selects how the tool runs, and the config object is shaped per type:
• http_api — call any REST endpoint. config: { url, method, headers, staticBody, auth, timeoutMs, messages }.
• query — retrieve grounded answers from knowledge bases. config: { knowledgeBases: [...], topKPerKb, timeoutMs, messages }.
• transfer — hand a voice call to a human. config: { destinations: [{ kind, label, number }], playDialtone }.
• webhook — POST the arguments to a URL. config: { url, secretRef }.
• custom_code — run a small JS snippet. config: { runtime: "js", code, timeoutMs }.
• database — run a saved query. config: { queryId }.

parameters is a JSON Schema describing the arguments the model must supply. For query tools it defaults to a { queries: string[] } schema. Secrets in http_api auth are encrypted and never returned — responses show hasSecret: true instead.

Filler messages (query + http_api): add config.messages so the assistant keeps the caller company while the tool runs — requestStart: { contents: string[] } (spoken immediately; one line picked at random), requestDelayed: { contents: string[], delayMs, minGapMs } (a 'still working' line spoken if the tool runs past delayMs OR the caller speaks during it; minGapMs is the minimum gap between such lines so the timer and the caller-triggered one never stack), and requestFailed (guidance the assistant voices, in its own language, when nothing is found).

GET/tools tools:read

List tools

List tools in the workspace.

bash

curl https://api.bolchoai.in/v1/tools -H "Authorization: Bearer $BOLCHO_API_KEY"

POST/tools tools:write

Create tool

Define a function-calling tool.

Body

name*	string	Function name (max 64).
description*	string	What it does — guides the LLM on when to call it (max 500).
type*	enum	http_api \| webhook \| database \| custom_code \| query \| transfer.
parameters	object	JSON Schema of the arguments the model must produce.
config	object	Type-specific configuration (see Tool types above).

bash

curl -X POST https://api.bolchoai.in/v1/tools -H "Authorization: Bearer $BOLCHO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "get_order",
    "description": "Look up an order by its id.",
    "type": "http_api",
    "parameters": { "type": "object", "properties": { "orderId": { "type": "string" } }, "required": ["orderId"] },
    "config": { "url": "https://api.example.com/orders/{orderId}", "method": "GET" }
  }'

Response

json

{ "id": "…", "name": "get_order", "type": "http_api", "enabled": true, "config": { "url": "https://api.example.com/orders/{orderId}", "method": "GET" } }

PATCH/tools/{id} tools:write

Update tool

Update a tool's description, parameters, config, or enabled flag. (name and type can't be changed.)

Path parameters

id*

uuid

Tool id.

Body

description	string	New description.
parameters	object	New arguments schema.
config	object	New type-specific config.
enabled	boolean	Enable/disable the tool.

bash

curl -X PATCH https://api.bolchoai.in/v1/tools/$ID \
  -H "Authorization: Bearer $BOLCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "string",
  "parameters": {},
  "config": {},
  "enabled": true
}'

POST/tools/{id}/invoke tools:write

Test invoke

Invoke the tool with sample arguments to test the handler.

Path parameters

id*

uuid

Tool id.

Body

args*	object	The arguments to pass to the tool.
callId	string	Optional call id for context.

bash

curl -X POST https://api.bolchoai.in/v1/tools/$ID/invoke \
  -H "Authorization: Bearer $BOLCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "args": {},
  "callId": "string"
}'

DELETE/tools/{id} tools:write

Delete tool

Delete a tool.

Path parameters

id*

uuid

Tool id.

bash

curl -X DELETE https://api.bolchoai.in/v1/tools/$ID \
  -H "Authorization: Bearer $BOLCHO_API_KEY"