Agents

Manage AI voice agents. Agents define how your AI sounds, behaves, and responds on calls. They are the core entity in Truedy — assigned phone numbers, equipped with tools and knowledge bases, and deployed on outbound or inbound calls. For UUID / phone / datetime formats used below, see Data formats.

List Agents

List all agents for your organization.

Parameters

Query parameters:

Parameter	Type	Description
`status`	string	Filter by status: `active`, `draft`, `creating`, `failed`
`name`	string	Filter by name (substring match)
`limit`	integer	1–100. Default `50`
`offset`	integer	Pagination offset. Default `0`

Each agent in the response includes inbound_phone_numbers and outbound_phone_numbers (arrays of { id, phone_number }) matching the dashboard view.

Response

{
  "data": [
    {
      "id": "1f4baf16-1540-4d91-9696-7f34b2f2cb77",
      "name": "Customer Support Agent",
      "description": "Handles customer support calls",
      "voice_id": "a7f2ec82-f533-4f41-a8de-0e4351bd2ec5",
      "system_prompt": "You are a helpful support agent...",
      "model": "ultravox-v0.7",
      "status": "active",
      "inbound_phone_numbers": [{"id": "d0845d54-d96d-4cb8-8cc3-eac55f94c2c0", "phone_number": "+14155550123"}],
      "outbound_phone_numbers": [],
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false },
  "meta": { "request_id": "f98eb11f-9f34-4d13-9075-0e29f106f37d", "ts": "2024-01-01T00:00:00Z" }
}

cURL

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

Get Agent

Get details for a specific agent including assigned phone numbers.

curl "https://api.truedy.ai/api/public/v1/agents/1f4baf16-1540-4d91-9696-7f34b2f2cb77" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Agent

Create a new voice agent. The agent is automatically synced to Ultravox on creation. Only name, voice_id, and system_prompt are required; all other fields are optional.

Request Body

Core fields:

Field	Type	Required	Default	Description
`name`	string	Yes	—	Agent display name (1–100 characters)
`voice_id`	UUID	Yes	—	Voice to use for this agent
`system_prompt`	string	Yes	—	Instructions that define the agent’s behavior and persona
`description`	string	No	—	Internal description (not used during calls)
`model`	string	No	`ultravox-v0.7`	AI model. Use `ultravox-v0.7` for best performance.
`tools`	UUID[]	No	`[]`	List of tool IDs to enable for this agent
`knowledge_bases`	UUID[]	No	`[]`	List of knowledge base IDs (maximum 1)
`temperature`	float	No	`0.3`	Response creativity, 0–1. Lower = more consistent.
`recording_enabled`	boolean	No	`false`	Enable call recording by default
`language_hint`	string	No	—	BCP-47 language code hint, e.g. `en-US`, `es-MX`

Call timing:

Field	Type	Default	Description
`join_timeout`	string	—	Time to wait for callee to answer, e.g. `"30s"`
`max_duration`	string	—	Maximum call length, e.g. `"3600s"` (1 hour)
`time_exceeded_message`	string	—	Text the agent speaks when `max_duration` is reached

Greeting & inactivity:

Field	Type	Description
`greeting_settings`	object	Configure the first speaker and greeting behavior. Fields: `first_speaker` (`FIRST_SPEAKER_AGENT` or `FIRST_SPEAKER_USER`), `text` (greeting text), `delay` (seconds), `uninterruptible` (boolean)
`inactivity_messages`	object[]	Messages spoken after user silence. Each item: `{ duration: "10s", message: "Are you still there?", endBehavior: "END_BEHAVIOR_HANG_UP" }`

Advanced audio:

Field	Type	Description
`vad_settings`	object	Voice activity detection tuning. Fields: `turn_endpoint_delay`, `minimum_turn_duration`, `minimum_interruption_duration`, `frame_activation_threshold`

Built-in capabilities:

Field	Type	Description
`built_in_config`	object	Enable built-in tools like call transfer, hang up, and voicemail detection. Structure: `{ transfer: { cold: bool, warm: bool }, hang_up: bool, leave_voicemail: bool }`

Post-call analysis:

Field	Type	Description
`success_criteria`	string	Prompt describing what makes a call successful. Used for outcome analysis.
`extraction_schema`	object	JSON Schema for structured data extraction from the call transcript (e.g. extract appointment date, customer name).
`crm_webhook_url`	string	URL to receive a POST with call results and extracted data after each call ends.
`crm_webhook_secret`	string	HMAC secret used to sign `crm_webhook_url` requests.

Example Request

{
  "name": "Customer Support Agent",
  "description": "Handles customer support calls",
  "voice_id": "a7f2ec82-f533-4f41-a8de-0e4351bd2ec5",
  "system_prompt": "You are a helpful customer support agent. Be friendly and professional. The customer's name is {{first_name}}.",
  "model": "ultravox-v0.7",
  "tools": ["4ee4db9b-d099-4dba-b4a8-8272a55fe25a"],
  "knowledge_bases": ["6f4af8be-0a96-49b0-ac2a-a359f46cc966"],
  "temperature": 0.3,
  "recording_enabled": true,
  "language_hint": "en-US",
  "max_duration": "900s",
  "greeting_settings": {
    "first_speaker": "FIRST_SPEAKER_AGENT",
    "text": "Hello! How can I help you today?"
  }
}

curl -X POST "https://api.truedy.ai/api/public/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 9268623c-f7ff-4871-bf80-cbaac7aa59b9" \
  -d '{
    "name": "Customer Support Agent",
    "voice_id": "a7f2ec82-f533-4f41-a8de-0e4351bd2ec5",
    "system_prompt": "You are a helpful customer support agent.",
    "model": "ultravox-v0.7"
  }'

Response: 201 Created with data (agent object: id, name, status, voice_id, etc.) and meta. Send X-Idempotency-Key for safe retries. Agent status after creation: The agent starts as draft and becomes active once synced to Ultravox. Sync happens automatically on creation. If Ultravox sync fails, the agent status remains draft and can be retried.

Update Agent (Full)

Replace an existing agent with the provided fields. All fields from Create Agent are accepted. The agent is re-synced to Ultravox immediately after update. Returns 422 if voice_id is invalid or missing.

curl -X PUT "https://api.truedy.ai/api/public/v1/agents/1f4baf16-1540-4d91-9696-7f34b2f2cb77" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent V2",
    "voice_id": "a7f2ec82-f533-4f41-a8de-0e4351bd2ec5",
    "system_prompt": "You are a concise, helpful support agent.",
    "model": "ultravox-v0.7"
  }'

Partial Update Agent

Update only the fields you send. All other fields remain unchanged.

Patchable Fields

Any field from the Create Agent table can be partially updated. Common examples:

Field	Type	Description
`name`	string	Rename the agent
`system_prompt`	string	Update behavior instructions
`voice_id`	UUID	Change the voice
`model`	string	Change the AI model
`tools`	UUID[]	Replace tool list
`knowledge_bases`	UUID[]	Replace knowledge base list
`temperature`	float	Adjust response creativity
`recording_enabled`	boolean	Enable or disable recording
`language_hint`	string	Change language hint
`join_timeout`	string	Change answer timeout
`max_duration`	string	Change max call length
`time_exceeded_message`	string	Change timeout message
`greeting_settings`	object	Update greeting config
`inactivity_messages`	object[]	Update silence handling
`vad_settings`	object	Tune voice activity detection
`built_in_config`	object	Enable/disable built-in tools
`success_criteria`	string	Update success evaluation prompt
`extraction_schema`	object	Update post-call extraction schema
`crm_webhook_url`	string	Change CRM webhook destination
`crm_webhook_secret`	string	Rotate CRM webhook secret

curl -X PATCH "https://api.truedy.ai/api/public/v1/agents/1f4baf16-1540-4d91-9696-7f34b2f2cb77" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recording_enabled": true,
    "temperature": 0.2,
    "max_duration": "600s"
  }'

Delete Agent

Deletes the agent from Truedy and removes it from Ultravox. Phone numbers assigned to this agent will be unassigned.

curl -X DELETE "https://api.truedy.ai/api/public/v1/agents/1f4baf16-1540-4d91-9696-7f34b2f2cb77" \
  -H "Authorization: Bearer YOUR_API_KEY"

Test Call

Initiate a test call with an agent using WebRTC (browser-based, no phone number needed). Returns a join_url to connect to the call. Intended for testing agent behavior during development.

Response

{
  "data": {
    "call_id": "44ec8f61-6d9a-4553-a6ca-777f5f5ef95b",
    "join_url": "https://app.ultravox.ai/calls/...",
    "agent_id": "1f4baf16-1540-4d91-9696-7f34b2f2cb77",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

curl -X POST "https://api.truedy.ai/api/public/v1/agents/1f4baf16-1540-4d91-9696-7f34b2f2cb77/test-call" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 422 or 502 if the test call cannot be started (e.g. agent not synced, Ultravox error).

​Agents

​List Agents

​Parameters

​Response

​cURL

​Get Agent

​Create Agent

​Request Body

​Example Request

​Update Agent (Full)

​Partial Update Agent

​Patchable Fields

​Delete Agent

​Test Call

​Response

Agents

List Agents

Parameters

Response

cURL

Get Agent

Create Agent

Request Body

Example Request

Update Agent (Full)

Partial Update Agent

Patchable Fields

Delete Agent

Test Call

Response