Skip to main content
POST
/
call-prompt
Call with Prompt
curl --request POST \
  --url https://www.callcow.ai/api/call-prompt \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "Book a reservation at Friday 7pm for Josh for 2",
  "recipient_phone": "+14155552671",
  "callback_url": "https://agent.example.com/results",
  "callback_secret": "my-secret-token",
  "idempotency_key": "agent-task-12345"
}
'
{
  "success": true,
  "workflow_id": "b8f40b44-3b7a-425b-a2ae-1327471b0410",
  "call_id": "c9e50c55-4c8b-536c-b3bf-2438582c1521"
}

​
Overview

Create and trigger an AI phone call from a natural language prompt in a single request. The system generates a workflow from your prompt, initiates the call, and optionally delivers results to a callback URL. This is ideal for agent-to-agent orchestration, where external agents can make calls without pre-creating workflows.

​
Callback

If you provide a callback_url, the API will POST call results to that URL when the call completes or fails (including not picked up, busy, voicemail). Callback delivery is best-effort (single attempt, 30-second timeout). For guaranteed delivery, poll the call status as a fallback.

​
Callback payload

{
  "call_id": "abc-123",
  "workflow_id": "def-456",
  "call_status": "success",
  "provider_status": "completed",
  "call_summary": "Customer booked a reservation for Friday 7pm, party of 2.",
  "messages": [],
  "context": null,
  "form_fills": [],
  "created_at": "2026-03-30T12:00:00.000Z"
}
If you provided a callback_secret, the callback request includes an Authorization: Bearer <your_secret> header.

​
Terminal statuses

call_statusprovider_statusMeaning
successcompletedCall completed normally
not_picked_upno-answerNo one answered
not_picked_upbusyLine was busy
not_picked_upfailedCall failed (bad number, carrier error)
not_picked_upcanceledCall was canceled
voicemailcompletedWent to voicemail

​
Idempotency

To prevent duplicate calls from retries, pass an optional idempotency_key. If the same key is sent within a 5-minute window, the API returns the cached response without creating a new call. 
{
  "prompt": "Book a reservation at Friday 7pm for Josh for 2",
  "recipient_phone": "+14155552671",
  "idempotency_key": "agent-task-12345"
}

Authorizations

​
Authorization
string
header
required

API key generated from Settings → API Keys. Format: ck_live_...

Body

application/json
​
prompt
string
required

Natural language description of the call task. The system generates an AI workflow from this prompt.

Example:

"Book a reservation at Friday 7pm for Josh for 2"

​
recipient_phone
string
required

Phone number of the call recipient in E.164 format

Example:

"+14155552671"

​
callback_url
string<uri>

HTTPS URL to receive call results when the call completes or fails. Must not point to private/reserved IP ranges.

Example:

"https://agent.example.com/results"

​
callback_secret
string

Optional bearer token included in the Authorization header of callback requests

Example:

"my-secret-token"

​
idempotency_key
string

Optional unique key to prevent duplicate calls on retries. Scoped to your organization with a 5-minute TTL.

Example:

"agent-task-12345"

Response

Call successfully created and triggered

​
success
boolean
Example:

true

​
workflow_id
string

ID of the generated workflow

Example:

"b8f40b44-3b7a-425b-a2ae-1327471b0410"

​
call_id
string | null

ID of the initiated call, if available

Example:

"c9e50c55-4c8b-536c-b3bf-2438582c1521"