Create Tool
Creates a shared webhook or client tool that can be attached to agents
Authorizations
Cartesia API key (sk_car_...). Get one at play.cartesia.ai/keys.
Headers
API version header.
2026-08-14 "2026-08-14"
Body
- Webhook tool
- Client tool
What the tool does and when the agent should use it.
1 - 2000Controls how the tool runs relative to the conversation. immediate runs in the current turn and can be interrupted by the caller, while async lets the turn finish while the tool runs.
immediate, async Name the agent uses to call the tool. Names are case-sensitive.
^[a-zA-Z][a-zA-Z0-9_-]{0,63}$Controls whether the agent speaks before using the tool. auto lets the agent decide, while force asks the agent to speak first.
auto, force Runs an HTTP request from Cartesia's servers.
webhook Maximum time to wait for the endpoint to respond. Defaults to 20 seconds.
1 <= x <= 120Response
Create a tool
- Webhook tool
- Client tool
An RFC 3339 / ISO 8601 date-time string with timezone (e.g. 2025-04-16T12:34:56.789Z).
What the tool does and when the agent should use it.
1 - 2000Controls how the tool runs relative to the conversation. immediate runs in the current turn and can be interrupted by the caller, while async lets the turn finish while the tool runs.
immediate, async Unique identifier for the tool.
1Name the agent uses to call the tool. Names are case-sensitive.
^[a-zA-Z][a-zA-Z0-9_-]{0,63}$Controls whether the agent speaks before using the tool. auto lets the agent decide, while force asks the agent to speak first.
auto, force Maximum time to wait for the endpoint to respond. Defaults to 20 seconds.
1 <= x <= 120Runs an HTTP request from Cartesia's servers.
webhook An RFC 3339 / ISO 8601 date-time string with timezone (e.g. 2025-04-16T12:34:56.789Z).
Agents that currently use this tool. Included when expand[]=agents is requested.