API quickstart
List an agent, place an outbound call, and retrieve its results. For every endpoint and validated request field, use the API reference.
Configure credentials
Follow API keys and authentication. Set TUNK_BASE_URL, TUNK_API_KEY and TUNK_WORKSPACE_ID in your shell. These examples use the production base URL, https://api.tunk.ai/agent/v1. Use placeholders only in shared collections.
Find an agent
curl --fail-with-body "$TUNK_BASE_URL/agents?page=1&limit=20" \
-H "X-Api-Key: $TUNK_API_KEY" \
-H "X-Workspace-Id: $TUNK_WORKSPACE_ID"List results use an outer success envelope and an inner paginated result:
{
"status": "success",
"data": {
"data": [],
"pagination": {
"page": 1,
"limit": 20,
"total": 0,
"total_pages": 1,
"has_next_page": false,
"has_prev_page": false
}
}
}Choose an agent_id from data.data. The agent must be configured for phone calling and have an available outbound number mapping. Configure numbers in the dashboard or through the phone-number and mapping endpoints.
Place a call
This request places a real call. Replace the example UUID and number with your agent and an approved recipient in international format.
curl --fail-with-body -X POST "$TUNK_BASE_URL/call" \
-H "X-Api-Key: $TUNK_API_KEY" \
-H "X-Workspace-Id: $TUNK_WORKSPACE_ID" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"agent_id": "123e4567-e89b-42d3-a456-426614174000",
"recipient_phone_number": "+14155552671",
"is_recording": true,
"call_metadata": {"customer_name": "Alex"}
}'The response's data.session_id identifies the call. The dispatch status indicates acceptance by the voice adapter; it does not confirm that the recipient answered or the call completed. from_phone_number and from_phone_number_id are optional overrides for an owned caller number.
Track the call
curl --fail-with-body "$TUNK_BASE_URL/calls?agent_id=<agent-uuid>&page=1&limit=20" \
-H "X-Api-Key: $TUNK_API_KEY" \
-H "X-Workspace-Id: $TUNK_WORKSPACE_ID"
curl --fail-with-body "$TUNK_BASE_URL/call/detail/<session-id>" \
-H "X-Api-Key: $TUNK_API_KEY" \
-H "X-Workspace-Id: $TUNK_WORKSPACE_ID"Call records and artifacts can update asynchronously. Recording and analysis may be absent. Register a signed call.completed webhook to receive a post-call snapshot rather than repeatedly polling.
Explore the API
| Resource | What you can do |
|---|---|
| Agents | Create, list, retrieve, update and delete agents |
| Calls | Dispatch a call and retrieve sessions and details |
| Batches | Create, execute, schedule and monitor batch calls |
| Phone numbers | Import supported providers, map numbers and manage DND entries |
| Knowledge base | Manage repositories, upload documents, add URL/text items, inspect ingestion and retry |
| Webhooks | Register endpoints, update subscriptions, test delivery and rotate secrets |
| Usage | Retrieve usage records and summaries |
Errors and pagination
JSON errors include status: "error" and fields such as error, message, code or statusCode, depending on the failure. Read both the HTTP status and body. Paginated endpoints default to page 1, limit 20 and accept a maximum limit of 100 unless the endpoint specifies otherwise. Phone-number listing uses its own limit and is not a page-based list.
Download the OpenAPI specification to import the Tunk API into Postman. Set credentials privately, select the production server, and add a fresh Idempotency-Key to each new POST.