Skip to main content

​
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:
ParameterTypeDefaultDescription
namestring—Filter by name (case-insensitive substring match)
limitinteger501–100
offsetinteger0Pagination 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:
FieldTypeRequiredDescription
namestringYes*Display name for the tool
definitionobjectNoFull tool definition (see below). If omitted, a placeholder tool is created
definition.modelToolNamestringNoSnake_case identifier sent to the AI model. Auto-derived from name if omitted. Must match ^[a-zA-Z0-9_-]{1,64}$
definition.typestringNoTool type. Use "http" for webhook/API integrations
definition.descriptionstringNoDescription shown to the AI model to help it decide when to use this tool
definition.httpobjectNoHTTP configuration: url, method (default GET)
definition.dynamicParametersarrayNoParameters the model fills dynamically at call time
definition.requirementsobjectNoSecurity 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

FieldTypeDescription
idUUIDTool ID
namestringDisplay name
definitionobjectFull tool definition including modelToolName, type, http, dynamicParameters, description
statusstringactive — synced to Ultravox and available for use
created_atdatetimeWhen the tool was created
updated_atdatetimeLast updated