Create Tool | Speechify API

curl -X POST https://api.speechify.ai/v1/agents/tool-definitions \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "lookup_order",
  "description": "Fetch order details by order ID.",
  "kind": "webhook",
  "config": {
    "url": "https://api.your-app.com/webhooks/lookup-order",
    "method": "POST",
    "timeout_ms": 5000,
    "headers": {
      "X-Org-ID": "acme"
    },
    "params": [
      {
        "name": "order_id",
        "type": "string",
        "description": "Order ID",
        "required": true
      }
    ]
  }
}'

{
  "id": "tool_01kb9kefcacry5t3662gfsgtzj",
  "name": "lookup_order",
  "description": "Fetch order details by order ID.",
  "kind": "webhook",
  "config": {
    "url": "https://api.your-app.com/webhooks/lookup-order",
    "method": "POST",
    "timeout_ms": 5000,
    "headers": {
      "X-Org-ID": "acme"
    },
    "params": [
      {
        "name": "order_id",
        "type": "string",
        "description": "Order ID",
        "required": true
      }
    ]
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "webhook_secret": "wh_sec_3f9a2b7c8d1e4f5a6b7c8d9e0f1a2b3c"
}

Create a tool. For webhook tools, the response includes the HMAC webhook_secret exactly once — store it immediately; subsequent reads return a masked placeholder.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Request

This endpoint expects an object.

namestringRequired

descriptionstringRequired

kindenumRequired

What kind of tool this is, and where it executes.

builtin: a worker-resident platform capability (e.g. end_call, play_audio), configured per-agent
webhook: worker signs a payload and POSTs it to your URL
client: worker dispatches to the caller’s browser/SDK via data channel
mcp: worker connects to a customer-hosted MCP server and proxies tool calls

configobjectRequired

Response

The created tool.

idstring

Prefixed wire identifier (tool_<26 char Crockford base32>).

namestring

descriptionstring

kindenum

What kind of tool this is, and where it executes.

builtin: a worker-resident platform capability (e.g. end_call, play_audio), configured per-agent
webhook: worker signs a payload and POSTs it to your URL
client: worker dispatches to the caller’s browser/SDK via data channel
mcp: worker connects to a customer-hosted MCP server and proxies tool calls

configobject

One of WebhookToolConfig, ClientToolConfig, or MCPToolConfig depending on kind.

created_atdatetime

updated_atdatetime

webhook_secretstring

HMAC signing secret for kind=webhook. Returned in full only on the create response; all subsequent reads return a masked placeholder. Store it on first create — there is no way to retrieve it later.

Errors

400

Bad Request Error

401

Unauthorized Error