---
title: "Create a custom mid-call tool on a voice agent (tools scope required)"
method: POST
path: "/api/v1/tools"
---

# Create a custom mid-call tool on a voice agent (tools scope required)

`POST /api/v1/tools`

## Request

- Base URL: `https://salestick-backend-647994203646.europe-central2.run.app`
- URL: `https://salestick-backend-647994203646.europe-central2.run.app/api/v1/tools`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Wires the company's OWN HTTPS API into the voice agent as a mid-call tool (e.g. order lookup, booking check). The URL host is pinned at creation; caller-supplied values only fill {param} placeholders in path/query/body. Always verify with POST /api/v1/tools/test afterwards. Grounding rules (param values must come from the caller's own words) are enforced automatically.

## Request body

- object
  - `agentId` string: Which voice agent gets the tool - required only when the team has several (ids from GET /api/v1/agents).
  - `name` string, required: snake_case tool name, 3-41 chars, e.g. check_order_status.
  - `description` string, required: For the voice AI: when to call this tool and what it returns.
  - `params` object[]: Values the voice AI extracts from the caller's words.
    - `name` string, required
    - `type` 'string' | 'number' | 'boolean', required
    - `description` string, required
    - `required` boolean
  - `method` 'GET' | 'POST', required
  - `url` string, required: HTTPS endpoint; {param} placeholders allowed in path/query, never in the host. Host must be publicly reachable (no private/internal addresses).
  - `headers` object: Static headers, e.g. an Authorization header. Stored server-side, masked in listings.
  - `body` object: POST only: JSON body template; string values may contain {param} placeholders.
  - `responseFields` string[]: Allowlist of response fields (dot paths) the voice AI is shown. Strongly recommended.
  - `timeoutMs` integer

## Response `201`

Tool created (live on new calls immediately)

## Other responses

- `400`: Invalid tool spec, unresolvable/private host, agentId needed, or tool limit reached
- `403`: Key lacks the tools scope
- `409`: A tool with that name already exists on the agent

---

[API](https://skmtc.dev/canarics/apis/canarics-api-for-ai-agents.md) · [All operations](https://skmtc.dev/canarics/apis/canarics-api-for-ai-agents/llms.txt) · [OpenAPI document](https://skmtc.dev/canarics/apis/canarics-api-for-ai-agents/revisions/e89711c2f1ba?raw)