Headless API · v1

Bring your voice
agents to your stack.

Trigger TaskVocal calls from your own product, pass your customer context, and receive signed lifecycle events on your server.

Get API credentials

API Base URL:

Base URL

localhost:8000

Authentication

Bearer API key

Content type

application/json

Before you begin

Authenticate safely

API keys identify your integration and are sent as a Bearer token in the Authorization header. Create keys from the TaskVocal workspace sign-in flow, keep them on your server, and never embed live credentials in browser code or mobile apps.

Request header

Authorization: Bearer YOUR_API_KEY

Use the complete API key as issued by the portal. Treat it like a password and rotate it immediately if exposed.

Keep keys off the client

Proxy API requests through your backend. Do not expose keys in source control, analytics, browser storage, or frontend bundles.

First request

Queue your first call

Use the agent ID for an agent already configured in TaskVocal. The request is asynchronous: a successful response gives you a call ID to track through call lifecycle webhooks.

POST/v1/calls

curl --request POST 'http://localhost:8000/v1/calls' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-123-call' \
  --data '{  "to_number": "+919876543210",  "agent_id": "ASSISTANT_ID",  "lead_name": "Raj",  "call_reason": "User has remaining EMI of 6 months",  "variables": {    "case_id": "CRM-123"  }}'

Request fields

to_number

string · required

Destination phone number in E.164 format.

agent_id

string · required

ID of the configured TaskVocal agent.

lead_name

string · optional

Contact name made available to the agent.

variables

object · optional

Additional integration context passed to the agent.

scheduled_at

ISO 8601 · optional

Timezone-aware future timestamp for a one-time call schedule.

API playground

http://localhost:8000Live API

Endpoint

API key

Stored locally in your browser for seamless playground testing.

JSON body

I understand this live POST request will reach the configured API. Call requests may initiate a real phone call; create requests add resources.Need a key? Sign in to your workspace

Live operation: sending a call request can place a real outbound call and may incur usage charges. Use a number you control and verify your agent and workspace before sending.

Endpoint reference

API reference

The workflow is agents → campaigns → calls. Call creation returns as soon as the request is accepted for processing; use the returned call_sid for follow-up actions and receive final state via webhooks. Health can be checked with GET /healthz.

Queue a call to a phone number using an existing TaskVocal agent.

Request fields

to_number

string · required

Destination phone number in E.164 format.

agent_id

string · required

ID of the configured TaskVocal assistant.

scheduled_at

ISO 8601 · optional

Timezone-aware future timestamp for a one-time scheduled call.

lead_name

string · optional

Contact name made available to the agent.

call_reason

string · optional

Context fed into the system prompt.

variables

object · optional

Additional context echoed back on webhooks.

tts_voice_id / voice_gender

string · optional

Per-call voice overrides.

Idempotency-Key

header · recommended

Reuse this unique key on retries to prevent duplicate calls.

curl --request POST 'http://localhost:8000/v1/calls' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-123-call' \
  --data '{  "to_number": "+919876543210",  "agent_id": "ASSISTANT_ID",  "lead_name": "Raj",  "call_reason": "User has remaining EMI of 6 months",  "variables": {    "case_id": "CRM-123"  }}'

Successful response

{
  "call_sid": "CALL_SID",
  "status": "queued"
}

The call is queued; completion is asynchronous.

Idempotency

Idempotency-Key: <unique-request-id>

Reuse the same key when retrying a request to avoid duplicate call dispatch.

Complete endpoint reference

Manage assistants, campaigns, calls, and webhooks with these scoped API routes. All routes are scoped to your API client and require server-side authentication. Bearer Every documented endpoint requires an API key; keep credentials off browser clients.

Assistants

Voice agent configurations (voice, language, prompt, provider/model).

POST

/v1/assistants

Create an assistant.

GET

/v1/assistants

List assistants.

GET

/v1/assistants/{agent_id}

Get assistant details.

PATCH

/v1/assistants/{agent_id}

Update an assistant.

DELETE

/v1/assistants/{agent_id}

Delete an assistant.

Campaigns

Outbound batch dialing campaigns with CSV upload and retry logic.

POST

/v1/campaigns

Create a campaign.

GET

/v1/campaigns

List campaigns.

GET

/v1/campaigns/{campaign_id}

Get campaign details.

PATCH

/v1/campaigns/{campaign_id}

Update campaign status.

DELETE

/v1/campaigns/{campaign_id}

Delete a campaign.

Calls

Outbound call triggering, stopping, status monitoring, and real-time logs.

POST

/v1/calls

Queue a call or persist schedule.

GET

/v1/calls

List call records.

GET

/v1/calls/{call_sid}

Get call details.

POST

/v1/calls/{call_sid}/stop

Hang up an in-progress call.

GET

/v1/calls/{call_sid}/logs

Get live/completed logs.

Webhooks & System

Signed HMAC-SHA256 delivery configuration and health status.

POST

/v1/webhooks

GET

/v1/webhooks

List webhook endpoints.

DELETE

/v1/webhooks/{webhook_id}

Remove a webhook.

GET

/healthz

Headless API health check.

Event delivery

Webhooks keep you in sync

Configure an HTTPS webhook endpoint in your TaskVocal workspace to receive call lifecycle events. Verify the signature before processing the payload and make your handler safe to retry.

Available event types

call.ringingThe call has started dialing.

call.answeredThe call has been answered.

call.completedThe call has completed.

call.failedThe call could not be completed.

Signature verification

Webhook deliveries include an HMAC-SHA256 signature in the X-TaskVocal-Signature header. Verify the raw request body using your endpoint signing secret before trusting the event.

HMAC-SHA256(raw_body, signing_secret)

Do not log or return signing secrets. Handle duplicate deliveries idempotently.

Delivery resilience

Webhooks are delivered asynchronously and retried with exponential backoff after failures. Respond promptly with a 2xx status, enqueue any longer work in your own system, and use event identifiers or call IDs to prevent duplicate processing.

Trigger calls safely from websites and chatbots

Send a server-to-server POST /v1/webhooks/trigger with your API key and the normal call request body. Never call this endpoint directly from browser JavaScript or expose the API key; have your website or chatbot call your backend, which validates the user action and forwards the request. For later calls, pass a timezone-aware future scheduled_at timestamp.

Operational guidance

Errors, retries & limits

Treat non-success responses as actionable and avoid retry storms. Keep retries bounded, use a unique idempotency key for each logical call request, and monitor your integration for repeated failures.

HTTP statusWhat to do

422

Check the request body, required fields, and phone number format.

401

Check that the API key is active and sent in the Authorization header.

404

Confirm the endpoint path and referenced resource ID.

409

Check whether a prior request with the same idempotency key was already processed.

429

Apply exponential backoff and review your client’s configured rate limit.

5xx

Retry with bounded exponential backoff and contact support if the error persists.

Rate limits are configured per API client. Exact quotas and response details are determined by your account configuration and the API response.

Bring your voice
agents to your stack.

Trigger TaskVocal calls from your own product, pass your customer context, and receive signed lifecycle events on your server.

API Base URL:

curl --request POST 'http://localhost:8000/v1/calls' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-123-call' \ --data '{ "to_number": "+919876543210", "agent_id": "ASSISTANT_ID", "lead_name": "Raj", "call_reason": "User has remaining EMI of 6 months", "variables": { "case_id": "CRM-123" }}'

Bring your voice
agents to your stack.

Authenticate

Make a request

Handle events

Authenticate safely

Queue your first call

Request fields

API reference

Request fields

Successful response

Idempotency

Complete endpoint reference

Assistants

Campaigns

Calls

Webhooks & System

Webhooks keep you in sync

Delivery resilience

Trigger calls safely from websites and chatbots

Errors, retries & limits

Bring your voice
agents to your stack.

Authenticate

Make a request

Handle events

Authenticate safely

Queue your first call

Request fields

API reference

Request fields

Successful response

Idempotency

Complete endpoint reference

Assistants

Campaigns

Calls

Webhooks & System

Webhooks keep you in sync

Delivery resilience

Trigger calls safely from websites and chatbots

Errors, retries & limits

Bring your voice agents to your stack.

Authenticate

Make a request

Handle events

Authenticate safely

Queue your first call

Request fields

API reference

Request fields

Successful response

Idempotency

Complete endpoint reference

Assistants

Campaigns

Calls

Webhooks & System

Webhooks keep you in sync

Delivery resilience

Trigger calls safely from websites and chatbots

Errors, retries & limits

Bring your voice agents to your stack.

Authenticate

Make a request

Handle events

Authenticate safely

Queue your first call

Request fields

API reference

Request fields

Successful response

Idempotency

Complete endpoint reference

Assistants

Campaigns

Calls

Webhooks & System

Webhooks keep you in sync

Delivery resilience

Trigger calls safely from websites and chatbots

Errors, retries & limits

Bring your voice
agents to your stack.

Bring your voice
agents to your stack.