Create a tool

POST /api/v1/tools

Create a reusable tool. The returned tool_uuid is what agents reference under agent.tools[].

Request body

Field	Type	Required	Notes
`name`	string (≤ 255)	✓	Display name. The LLM sees it as a function name: lowercased, with every run of other characters turned into `_` (`"Book Slot"` → `book_slot`). A name with no English letters or digits, or longer than 64 characters, gets a short unique suffix (`"स्टोर खोजें"` → `tool_41ac1a6b`).
`description`	string	—	Helps the LLM decide when to call this tool. Surfaced in the function spec.
`category`	enum	—	One of `function`, `endCall`, `transferCall`, `calculator`, `query`, `native`, `integration`. Defaults to `function`. For typed tools, set `category` to match `definition.type` (e.g., `category: "endCall"` with `definition.type: "endCall"`) — this is what the UI does and what `GET /tools?category=endCall` filters on. `native` and `integration` are reserved for future built-in / third-party tools.
`icon`	string (≤ 50)	—	Lucide icon name. Defaults to `"globe"`.
`icon_color`	string (≤ 7)	—	Hex color. Defaults to `"#3B82F6"`.
`definition`	discriminated object	✓	The tool's behavior — see below.

`definition` shape

definition.type discriminates. Five shapes are supported:

`type`	Purpose	Page
`"function"`	HTTP API call	Tool types → HTTP
`"endCall"`	End the call with an optional goodbye	Tool types → endCall
`"transferCall"`	Warm/cold transfer to PSTN or SIP	Tool types → transferCall
`"calculator"`	Built-in math tool, no config	Tool types → calculator
`"query"`	Knowledge-base retrieval	Tool types → query

Full sub-config field tables for each type live on the Tool types page.

Response

200 OK. Same shape as a list item from GET /tools.

Examples

HTTP function tool

curl -X POST https://dashboard.zoxa.ai/api/v1/tools \
  -H "X-API-Key: zsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lookup order status",
    "description": "Fetches order status from internal API.",
    "category": "function",
    "icon": "package",
    "definition": {
      "schema_version": 1,
      "type": "function",
      "config": {
        "method": "GET",
        "url": "https://api.acme.com/orders/{orderId}",
        "timeout_ms": 5000,
        "parameters": [
          { "name": "orderId", "type": "string", "description": "Order ID", "required": true }
        ]
      }
    }
  }'

const tool = await fetch("https://dashboard.zoxa.ai/api/v1/tools", {
  method: "POST",
  headers: { "X-API-Key": "zsk_...", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Lookup order status",
    description: "Fetches order status from internal API.",
    category: "function",
    icon: "package",
    definition: {
      schema_version: 1,
      type: "function",
      config: {
        method: "GET",
        url: "https://api.acme.com/orders/{orderId}",
        timeout_ms: 5000,
        parameters: [
          { name: "orderId", type: "string", description: "Order ID", required: true },
        ],
      },
    },
  }),
}).then((r) => r.json());

console.log("Reference in agent.tools[]:", tool.tool_uuid);

import httpx
tool = httpx.post(
    "https://dashboard.zoxa.ai/api/v1/tools",
    headers={"X-API-Key": "zsk_..."},
    json={
        "name": "Lookup order status",
        "description": "Fetches order status from internal API.",
        "category": "function",
        "icon": "package",
        "definition": {
            "schema_version": 1,
            "type": "function",
            "config": {
                "method": "GET",
                "url": "https://api.acme.com/orders/{orderId}",
                "timeout_ms": 5000,
                "parameters": [{"name": "orderId", "type": "string", "description": "Order ID", "required": True}],
            },
        },
    },
).json()

Errors

Status	`detail`	When
`400`	`"No organization selected for the user"`	Auth missing org.
`400`	`"Invalid category '...'. Must be one of: ..."`	Unknown category.
`422`	array	Discriminated `definition.type` doesn't match a known shape, or sub-config fails validation.

Tool types — full sub-config schemas
PUT /tools/{tool_uuid}
Agent config — tools — how to reference a tool from an agent

Request body

definition shape

Response

Examples

HTTP function tool

Errors

Related

On this page

`definition` shape