API reference

Function tools

Helpers for building an agent's function tools - the catalog, validation, generating a function from a cURL command, and a test run.

Function tools let an agent call an API, transfer the call, end the call or text the caller during a conversation. Tools are saved as part of an agent under tools_config.api_tools. The endpoints on this page do not save anything: they help you build a tool, check it, and try its HTTP request before you put it on an agent. The function tools guide covers the tool format in full.

Operation	Method and path	Minimum role
Get the tool catalog	`GET /tools/catalog`	viewer
Validate a function	`POST /tools/validate`	member
Create a function from cURL	`POST /tools/from-curl`	member
Test a function	`POST /tools/test`	member

Two forms of a function

A function can be written in two equivalent forms.

Editor form: one object, with the HTTP request under value. This is what POST /tools/from-curl returns and what you send as function.
API form: the tool definition (name, key, description, parameters, ...) goes in api_tools.tools, and its request goes in api_tools.tools_params under the tool's name. This is what an agent stores.

POST /tools/validate converts the editor form to the API form.

In the request, param values use %(name)s placeholders that are filled from the arguments the model supplies (%(name)i for an integer, %(name)f for a number). For GET and DELETE, param becomes the query string; for other methods it becomes the JSON body. api_token is sent as the Authorization header exactly as written.

Get the tool catalog

GET /tools/catalog

Returns the built-in tool templates, the tool keys and the HTTP methods the platform accepts.

Auth: API key or session token. Role: viewer and up.

Request

bash

curl https://api.sevennadi.si/tools/catalog \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK (templates shortened)

json

{
  "tools": [
    {
      "key": "transfer_call",
      "title": "Transfer Call",
      "summary": "Route call to human",
      "template": {
        "name": "transfer_call",
        "key": "transfer_call",
        "description": "Use this tool to transfer the call when the caller asks to speak with a human.",
        "pre_call_message": "Sure, I'll transfer the call for you. Please wait a moment.",
        "parameters": {
          "type": "object",
          "properties": {"call_sid": {"type": "string", "description": "unique call id"}},
          "required": ["call_sid"]
        },
        "value": {"method": "POST", "url": null, "api_token": null, "param": {"call_transfer_number": "", "call_sid": "%(call_sid)s"}}
      }
    }
  ],
  "extra_tools": [
    {"key": "send_sms", "title": "Send SMS", "summary": "Text the caller a message", "template": {"name": "send_sms", "key": "send_sms"}}
  ],
  "keys": ["custom_task", "check_availability_of_slots", "book_appointment", "transfer_call", "end_call", "send_sms"],
  "methods": ["GET", "POST", "PUT", "PATCH", "DELETE"]
}

tools holds five templates, in this order: check_availability_of_slots, book_appointment, transfer_call, end_call, custom_task. extra_tools holds send_sms, which texts the person on the call once the compliance checks pass. Each template is in the editor form and is meant to be copied and filled in.

Note: The two calendar templates point at a third-party calendar API. They are ordinary HTTP templates that need your own account and token with that service; the platform has no built-in calendar integration.

Validate a function

POST /tools/validate

Checks one function, or a whole api_tools object, with the same rules used when an agent is saved. For one function it also returns both forms.

Auth: API key or session token. Role: member and up.

Send exactly one of these shapes:

Parameter	In	Type	Required	Description
`function`	body	object	one of	A function in the editor form. `key` defaults to `custom_task`.
`tool` and `tool_params`	body	object, object	one of	A function in the API form: the tool definition and its request.
`api_tools`	body	object	one of	A whole `{"tools": [...], "tools_params": {...}}` object.

Request

bash

curl -X POST https://api.sevennadi.si/tools/validate \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "function": {
      "name": "check_order_status",
      "key": "custom_task",
      "description": "Use this function when the customer asks about their order status or tracking.",
      "pre_call_message": "Let me check the status of your order.",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string", "description": "The order ID, e.g. ORD-78234"}},
        "required": ["order_id"]
      },
      "value": {"method": "GET", "url": "https://api.example.test/orders", "param": {"order_id": "%(order_id)s"}}
    }
  }'

Response 200 OK

json

{
  "valid": true,
  "tool": {
    "name": "check_order_status",
    "key": "custom_task",
    "description": "Use this function when the customer asks about their order status or tracking.",
    "pre_call_message": "Let me check the status of your order.",
    "parameters": {
      "type": "object",
      "properties": {"order_id": {"type": "string", "description": "The order ID, e.g. ORD-78234"}},
      "required": ["order_id"]
    }
  },
  "tool_params": {"method": "GET", "url": "https://api.example.test/orders", "param": {"order_id": "%(order_id)s"}},
  "function": {"name": "check_order_status", "key": "custom_task", "value": {"method": "GET", "url": "https://api.example.test/orders", "param": {"order_id": "%(order_id)s"}}}
}

function in the response is the full editor form (shortened above). When you send api_tools, the response is only {"valid": true}.

Errors

Every problem is a 400 whose message says what is wrong and where. Examples:

Status	Message
400	`function.value.method is required: one of GET, POST, PUT, PATCH, DELETE`
400	`function must be an object`
400	`function.value must be an object`
400	`Send the function under 'function' (with its request under 'value')`

Create a function from cURL

POST /tools/from-curl

Turns a cURL command into a function in the editor form. It reads the method, URL, headers and the JSON or form body. Query and body fields become parameters with placeholders, an Authorization header becomes api_token, and other headers (except Content-Type) are kept. Nothing is sent to the URL.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`curl`	body	string	yes	A command that starts with `curl` and has an `http` or `https` URL.

Request

bash

curl -X POST https://api.sevennadi.si/tools/from-curl \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d "{\"curl\": \"curl --location 'https://api.example.test/v1/appointments?clinic=7' --header 'Authorization: Bearer EXAMPLE_TOKEN' --header 'X-Team: ops' --data '{\\\"patient_name\\\": \\\"Priya\\\", \\\"slots\\\": 2}'\"}"

Response 200 OK

json

{
  "function": {
    "name": "post_appointments",
    "description": "Use this function to call POST /v1/appointments on api.example.test. Describe when to call it.",
    "pre_call_message": "One moment please.",
    "parameters": {
      "type": "object",
      "properties": {
        "clinic": {"type": "string", "description": "clinic"},
        "patient_name": {"type": "string", "description": "patient name"},
        "slots": {"type": "integer", "description": "slots"}
      },
      "required": ["clinic", "patient_name", "slots"]
    },
    "key": "custom_task",
    "value": {
      "method": "POST",
      "param": {"clinic": "%(clinic)s", "patient_name": "%(patient_name)s", "slots": "%(slots)i"},
      "url": "https://api.example.test/v1/appointments",
      "api_token": "Bearer EXAMPLE_TOKEN",
      "headers": {"X-Team": "ops"}
    }
  }
}

The generated name and description are starting points. Rewrite the description so the model knows when to call the function. The method defaults to POST when the command has a body and GET otherwise.

Errors

Status	Message
400	`curl is required: paste a cURL command`
400	`The command must start with curl`
400	`The cURL command has no http(s) URL`
400	`Unsupported method TRACE`
400	`Could not parse the cURL command: No closing quotation`

Test a function

POST /tools/test

Runs a function's HTTP request once with sample arguments and returns what came back. The request really goes out from the platform to the function's URL. It has a 10-second timeout and does not follow redirects.

You can test a function you are still building (send it as in Validate a function), or one already saved on an agent (send agent_id and name). A saved function runs with its stored token.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`function`	body	object	one of	A function in the editor form. `tool` + `tool_params` works too.
`agent_id`	body	string (UUID)	one of	Test a tool saved on this agent.
`name`	body	string	with `agent_id`	The saved tool's name.
`arguments`	body	object	no	Values for the function's parameters, as the model would supply them.
`context`	body	object	no	Extra values for placeholders, such as call variables. `arguments` win on a clash.

Only tools that make an HTTP request can be tested: custom_task, check_availability_of_slots and book_appointment.

Request

bash

curl -X POST https://api.sevennadi.si/tools/test \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "3c9d2f8e-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "name": "check_order_status", "arguments": {"order_id": "ORD-1"}}'

Response 200 OK

json

{
  "ok": true,
  "status_code": 200,
  "body": {"status": "delivered"},
  "error": null,
  "duration_ms": 184,
  "request": {
    "method": "GET",
    "url": "https://api.example.test/orders?order_id=ORD-1",
    "headers": {"Content-Type": "application/json", "Authorization": "**********"},
    "body": null
  }
}

The endpoint answers 200 even when the function's own API fails. In that case ok is false and error says why, for example HTTP 404 or a connection error. request shows what was sent, with credential headers masked. A non-JSON response body is returned as text, cut to 5000 characters.

Errors

Status	Message
400	`arguments and context must be objects`
400	`arguments.order_id is required by this function`
400	`Only tools that call an API can be tested; transfer_call does not make a request`
400	`The function's url is not allowed: ...` (the URL points at a private or otherwise blocked address)
400	A validation message, as in Validate a function
404	`Agent not found`
404	`Tool not found on this agent`

Warning: A test run is a real request. Testing a function that books, pays or sends something will do so.