Get Tool

Beta

GET

https://api.speechify.ai/v1/agents/tool-definitions/:tool_definition_id

GET

/v1/agents/tool-definitions/:tool_definition_id

$ curl https://api.speechify.ai/v1/agents/tool-definitions/tool_01jqr8x9zg5k2m3n4p5q6r7s8t \
>      -H "Authorization: Bearer <token>"

1 {
2   "id": "tool_01kb9kefcacry5t3662gfsgtzj",
3   "name": "Example name",
4   "description": "Example description.",
5   "kind": "builtin",
6   "config": {
7     "fire_and_forget": false,
8     "headers": {
9       "key": "example"
10     },
11     "method": "POST",
12     "params": [
13       {
14         "description": "Example description.",
15         "name": "Example name",
16         "required": true,
17         "type": "string"
18       }
19     ],
20     "timeout_ms": 5000,
21     "url": "https://example.com/webhook"
22   },
23   "created_at": "2026-06-24T18:03:11Z",
24   "updated_at": "2026-06-24T18:03:11Z",
25   "webhook_secret": "whsec_01jqr8x9zg5k2m3n4p5q6r7s8t"
26 }

Retrieve a tool by ID. Webhook secrets are always masked here.

Authentication

AuthorizationBearer

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

Path parameters

tool_definition_idstringRequired

Tool definition id (prefixed external id, tool_...).

Response headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

The requested tool.

idstringformat: "^tool_[0-9a-hjkmnp-tv-z]{26}$"

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

401

Unauthorized Error

404

Not Found Error

Authentication

Path parameters

Headers

Response headers

Response

Errors