> ## Documentation Index > Fetch the complete documentation index at: https://docs.voice.wixzel.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a tool > Requires `tools:write`. ## OpenAPI ````yaml /openapi.json post /v1/tools openapi: 3.1.0 info: title: Wixzel Voice API version: '2026-09-01' description: >- APIs for agentic telephony. One API key, one balance, every voice engine. ## Authentication Send your key as `Authorization: Bearer wv_live_...`. Keys are scoped: grant only what an integration needs. There is no admin scope. ## Versioning The `/v1` prefix covers additive changes. Behavioural changes ship behind a dated `Wixzel-Version` header, and existing keys keep the behaviour they were created with. ## Money Amounts are integer **micro-USD** (1,000,000 = $1.00). Voice usage is billed per second, per token and per character, so a float dollar figure cannot represent it without disagreeing with the ledger. ## Errors Every error carries a stable `code` and a `request_id`. Match on `code`; the `message` is for humans and may change. contact: name: Wixzel Voice url: https://voice.wixzel.com servers: - url: https://api.voice.wixzel.com description: Production security: [] tags: - name: Calls description: Place calls and read what happened on them. - name: Realtime description: Talk to an agent from a browser or app, with no phone line. - name: Agents description: >- The prompt, voice and behaviour of a caller, and its mascot: the animated face people see on your share link, your website and in your apps. - name: Leads description: People to call, and data to merge into prompts. - name: Campaigns description: Call a list of leads with one agent. - name: Knowledge bases description: Facts an agent can draw on mid-call. - name: Phone numbers description: Numbers on your SIP trunks. - name: SIP trunks description: Your carrier connections. - name: Appointments description: Bookings, including ones agents make on calls. - name: Usage description: Itemised billing lines. - name: Billing description: Balance, ledger and top-ups. - name: API keys description: Create, scope and rotate keys. - name: Engines description: What the platform can serve, and what it costs. - name: Voices description: Cloned voices, made from your own recordings, for your agents to speak in. - name: Callers description: Who called your agents, where from and on what, and the blocklist. - name: Webhooks description: Where events are sent, and what happened when they got there. - name: MCP servers description: Other apps’ tools, for agents to use while they are on a call. - name: Tools description: >- Your own tools, for agents to use while they are on a call: a webhook to your server, or an action in the caller’s app. - name: WhatsApp description: >- WhatsApp business numbers, the agents that answer their chats, and messages agents send. - name: Meetings description: >- Agents in Zoom, Google Meet and Teams meetings, through your own Attendee account. paths: /v1/tools: post: tags: - Tools summary: Create a tool description: Requires `tools:write`. requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTool' responses: '201': description: The created a tool content: application/json: schema: $ref: '#/components/schemas/Tool' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Key lacks the required scope content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited. Retry after the interval in `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: CreateTool: oneOf: - type: object properties: name: type: string pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$ description: What the agent calls it. Unique in the account. example: check_order_status description: type: string minLength: 1 maxLength: 1000 description: Tells the agent what the tool does and when to use it. example: >- Look up where an order is. Use it when the caller asks about a delivery. parameters: $ref: '#/components/schemas/ToolParameters' type: type: string enum: - webhook webhook: type: object properties: url: type: string maxLength: 2048 format: uri description: Public https (or http) on port 443 or 80. example: https://api.example.com/orders/status method: type: string enum: - GET - POST - PUT - PATCH - DELETE default: POST description: >- The arguments are the JSON body, or query parameters for GET and DELETE. headers: type: array items: $ref: '#/components/schemas/ToolHeader' maxItems: 20 description: >- Sent with every request, such as an API key. Replaced as a whole when sent. timeout_ms: type: integer minimum: 1000 maximum: 30000 default: 10000 description: >- How long the agent waits for the answer. The caller hears silence meanwhile, so keep it short. required: - url required: - name - description - type - webhook - type: object properties: name: type: string pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$ description: What the agent calls it. Unique in the account. example: check_order_status description: type: string minLength: 1 maxLength: 1000 description: Tells the agent what the tool does and when to use it. example: >- Look up where an order is. Use it when the caller asks about a delivery. parameters: $ref: '#/components/schemas/ToolParameters' type: type: string enum: - client client: type: object properties: wait_for_result: type: boolean default: true description: >- Wait for the app to answer (it can return data to the agent), or tell the agent it is done at once, for actions such as opening a page. timeout_ms: type: integer minimum: 1000 maximum: 30000 default: 10000 required: - name - description - type description: >- `webhook` calls your endpoint and works on every call. `client` asks the caller's app or website to do something, over the realtime session; it is never offered on phone calls. Tool: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e object: type: string enum: - tool name: type: string description: type: string type: type: string enum: - webhook - client parameters: type: object additionalProperties: {} webhook: type: - object - 'null' properties: url: type: string method: type: string enum: - GET - POST - PUT - PATCH - DELETE header_names: type: array items: type: string description: >- The names of the stored headers. Their values are never returned. timeout_ms: type: integer required: - url - method - header_names - timeout_ms client: type: - object - 'null' properties: wait_for_result: type: boolean timeout_ms: type: integer required: - wait_for_result - timeout_ms created_at: type: string format: date-time description: ISO 8601, always UTC. example: '2026-09-01T12:00:00.000Z' updated_at: type: string format: date-time description: ISO 8601, always UTC. example: '2026-09-01T12:00:00.000Z' required: - id - object - name - description - type - parameters - webhook - client - created_at - updated_at Error: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - insufficient_credits - not_found_error - conflict_error - api_error code: type: string description: Stable machine-readable code. example: agent_not_found message: type: string description: >- Human-readable explanation. Do not match on this — match on code. param: type: string description: Which field caused the failure, when applicable. doc_url: type: string request_id: type: string description: Quote this when asking for help. example: req_01HXYZ... required: - type - code - message - request_id required: - error ToolParameters: type: object properties: type: type: string enum: - object properties: type: object additionalProperties: type: object properties: type: type: string enum: - string - number - integer - boolean - array - object description: type: string maxLength: 500 enum: type: array items: anyOf: - type: string maxLength: 200 - type: number maxItems: 50 items: type: object additionalProperties: {} description: 'For `array`: the schema of each item.' properties: type: object additionalProperties: {} description: >- For `object`: its own properties, at most three levels deep in all. required: type: array items: type: string required: - type default: {} required: type: array items: type: string maxItems: 30 required: - type description: >- What the agent passes when it calls the tool, as a JSON Schema object. Describe every property: the agent reads the descriptions to decide what to fill in. At most 30 properties, three levels deep. example: type: object properties: order_id: type: string description: The order number the caller reads out required: - order_id ToolHeader: type: object properties: name: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,63}$ example: Authorization value: type: string minLength: 1 maxLength: 4096 description: >- Write-only, encrypted at rest, never returned. Required on create. On update, omit it to keep the value stored under this name. example: Bearer sk_live_… required: - name securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Wixzel Voice API key: `Authorization: Bearer wv_live_...`. Keys are scoped; grant only what the integration needs. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.