Create Agent Tool | Speechify API

curl -X POST https://api.speechify.ai/v1/agents/id/tools \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "kind": "builtin",
  "name": "Play Audio",
  "config": {}
}'

{
  "id": "tool_01kb9kefcacry5t3662gfsgtzj",
  "kind": "builtin",
  "name": "Play Audio",
  "description": "Plays an audio asset during the call",
  "enabled": true,
  "definition_id": "null",
  "config": {
    "builtin": "play_audio",
    "params": [
      {
        "name": "audio_asset_id",
        "type": "string",
        "description": "Identifier of the audio asset to play",
        "required": true,
        "enum": []
      }
    ],
    "builtin_config": {}
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "webhook_secret": ""
}

Add a tool to the agent. With kind=builtin this creates a per-agent built-in instance (e.g. end_call, play_audio); the builtin capability name comes from config.builtin. With kind=webhook, client, or mcp this atomically creates a workspace tool definition AND attaches it to the agent in one call. To attach a definition that already exists, use PUT /v1/agents/{id}/tools/{toolId} instead.

Add a tool to the agent. With `kind=builtin` this creates a per-agent built-in instance (e.g. `end_call`, `play_audio`); the `builtin` capability name comes from `config.builtin`. With `kind=webhook`, `client`, or `mcp` this atomically creates a workspace tool definition AND attaches it to the agent in one call. To attach a definition that already exists, use `PUT /v1/agents/{id}/tools/{toolId}` instead.

Authentication

AuthorizationBearer

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

Path parameters

idstringRequired

Request

This endpoint expects an object.

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

namestringRequired

configobjectRequired

descriptionstringOptional

enabledbooleanOptional

Defaults to true on the server when omitted.

Response

The created tool.

idstring

Prefixed wire identifier (tool_<26 char Crockford base32>), stable across kinds.

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

namestring

descriptionstring

enabledboolean

When false the tool is configured but skipped at dispatch.

definition_idstring or null

Provenance: the backing workspace tool definition id for shared kinds (webhook/client/mcp), or null for a built-in. Non-null ⟺ the tool’s config is shared and edited at /v1/agents/tool-definitions/{id}.

configobject

Resolved config - BuiltinToolConfig, WebhookToolConfig, ClientToolConfig, or MCPToolConfig depending on kind.

created_atdatetime

updated_atdatetime

webhook_secretstring

HMAC signing secret for a webhook tool. Returned in full only on the create response; subsequent reads return a masked placeholder.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error