calls.start

Place a call with an agent, by its public id.

Use this endpoint when you want to start an agent run through an API Trigger node.

The uuid comes from the API Trigger node in your agent. Add the node to your workflow and copy its auto-generated trigger_path.

Use workflow_run_id from the response to later retrieve run details, recordings, and transcripts.

Pass initial_context to inject runtime data as template variables into the agent’s prompt. See Using initial context.

Pass telephony_configuration_id to route the call through a specific telephony configuration instead of your organization’s default. The id is shown on each row in Telephony configurations (https://app.decibyl.ai/telephony-configurations for hosted or http://localhost:3010/telephony-configurations for local).

Note

This route expects an API Trigger node UUID (trigger_path). Do not pass a workflow UUID here. If you want to execute by Agent UUID, use Trigger an outbound agent run by Agent UUID instead.

Note

Your telephony provider must be configured before outbound calls will connect. See Telephony for setup instructions.

Reference

POST/api/v1/public/agent/{uuid}

Auth

API key in X-API-Key

Content

application/json

Returns

200 · TriggerCallResponse

Initiate a phone call against the published agent. Executes the workflow's currently released definition.

Arguments

Argument	In	Type	Required	Description
uuid	path	string	required
phone_number	body	string	required
initial_context	body	object	optional
telephony_configuration_id	body	integer	optional
event_id	body	string	optional	An identifier for the event that caused this call. A second request carrying the same event_id within 24 hours returns the first call instead of placing another.

Example request

curl -X POST "https://api.decibyl.ai/api/v1/public/agent/<uuid>" \
  -H "X-API-Key: dcb_your_key" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"string","initial_context":{},"telephony_configuration_id":1,"event_id":"string"}'

Response

{
  "status": "string",
  "workflow_run_id": 1,
  "workflow_run_name": "string"
}

Errors

Status	When
404	Not found
422	Validation Error