Tools

Manage external tools that agents can use during calls. Tools let agents perform HTTP requests (API lookups, CRM writes, appointment booking, etc.) in real-time while on a call. For UUID / phone / datetime formats used below, see Data formats.

List Tools

Parameters

Query parameters:

Parameter	Type	Default	Description
`name`	string	—	Filter by name (case-insensitive substring match)
`limit`	integer	`50`	1–100
`offset`	integer	`0`	Pagination offset

Returns data (array of tool objects), pagination (total, limit, offset, has_more), and meta.

cURL

curl "https://api.truedy.ai/api/public/v1/tools" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Tool

curl "https://api.truedy.ai/api/public/v1/tools/4ee4db9b-d099-4dba-b4a8-8272a55fe25a" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Tool

Parameters

Request body:

Field	Type	Required	Description
`name`	string	Yes*	Display name for the tool
`definition`	object	No	Full tool definition (see below). If omitted, a placeholder tool is created
`definition.modelToolName`	string	No	Snake_case identifier sent to the AI model. Auto-derived from `name` if omitted. Must match `^[a-zA-Z0-9_-]{1,64}$`
`definition.type`	string	No	Tool type. Use `"http"` for webhook/API integrations
`definition.description`	string	No	Description shown to the AI model to help it decide when to use this tool
`definition.http`	object	No	HTTP configuration: `url`, `method` (default `GET`)
`definition.dynamicParameters`	array	No	Parameters the model fills dynamically at call time
`definition.requirements`	object	No	Security options: `httpSecurityOptions` for API key auth

* name is required unless definition.modelToolName is explicitly provided. Idempotency: Send X-Idempotency-Key for safe retries.

Example — minimal

{
  "name": "Lookup Customer"
}

Example — full HTTP tool

{
  "name": "Lookup Customer",
  "definition": {
    "modelToolName": "lookup_customer",
    "description": "Look up a customer by phone number to retrieve their name and account status",
    "type": "http",
    "http": {
      "url": "https://api.example.com/customer",
      "method": "GET"
    },
    "dynamicParameters": [
      {
        "name": "phone_number",
        "location": "PARAMETER_LOCATION_QUERY",
        "schema": { "type": "string", "description": "The caller's phone number in E.164 format" },
        "required": true
      }
    ]
  }
}

cURL

curl -X POST "https://api.truedy.ai/api/public/v1/tools" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 100f451a-9f04-4d0c-8f95-87c4cb1886f4" \
  -d '{
    "name": "Lookup Customer",
    "definition": {
      "modelToolName": "lookup_customer",
      "description": "Look up a customer by phone number",
      "type": "http",
      "http": {
        "url": "https://api.example.com/customer",
        "method": "GET"
      }
    }
  }'

Response: 201 Created with data (tool object) and meta. Returns 422 if the tool definition is invalid (e.g. modelToolName contains invalid characters, provider error).

Update Tool

Update a tool’s name and/or definition. Only included fields are changed. Changes are pushed to Ultravox immediately. Request body: Any subset of name and/or definition. Returns 422 if the definition is rejected.

curl -X PATCH "https://api.truedy.ai/api/public/v1/tools/4ee4db9b-d099-4dba-b4a8-8272a55fe25a" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lookup Customer V2",
    "definition": {
      "http": {
        "url": "https://api.example.com/v2/customer",
        "method": "GET"
      }
    }
  }'

Delete Tool

Deletes the tool from Truedy and from Ultravox. Agents using this tool will no longer have access to it.

curl -X DELETE "https://api.truedy.ai/api/public/v1/tools/4ee4db9b-d099-4dba-b4a8-8272a55fe25a" \
  -H "Authorization: Bearer YOUR_API_KEY"

Tool Object

Field	Type	Description
`id`	UUID	Tool ID
`name`	string	Display name
`definition`	object	Full tool definition including `modelToolName`, `type`, `http`, `dynamicParameters`, `description`
`status`	string	`active` — synced to Ultravox and available for use
`created_at`	datetime	When the tool was created
`updated_at`	datetime	Last updated

API documentation

Endpoints

Tools

Tools

List Tools

Parameters

cURL

Get Tool

Create Tool

Parameters

Example — minimal

Example — full HTTP tool

cURL

Update Tool

Delete Tool

Tool Object

​Tools

​List Tools

​Parameters

​cURL

​Get Tool

​Create Tool

​Parameters

​Example — minimal

​Example — full HTTP tool

​cURL

​Update Tool

​Delete Tool

​Tool Object

Tools

List Tools

Parameters

cURL

Get Tool

Create Tool

Parameters

Example — minimal

Example — full HTTP tool

cURL

Update Tool

Delete Tool

Tool Object