Skip to main content
POST
/
api
/
v1
/
public
/
call
Create Call
curl --request POST \
  --url https://api.usetuner.ai/api/v1/public/call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "call_id": "<string>",
  "call_type": "<string>",
  "transcript_with_tool_calls": [
    {
      "role": "node_transition",
      "text": "<string>",
      "words": [
        {
          "word": "<string>",
          "start_ms": 123,
          "end_ms": 123,
          "confidence": 123
        }
      ],
      "start_ms": 123,
      "end_ms": 123,
      "duration_ms": 123,
      "node": {
        "from": "<string>",
        "to": "<string>",
        "reason": "<string>"
      },
      "tool": {
        "name": "<string>",
        "request_id": "<string>",
        "params": {},
        "result": {},
        "is_error": true,
        "error": "<string>",
        "start_ms": 123
      },
      "metadata": {
        "e2e_latency": 123,
        "interrupted": true,
        "llm_node_ttft": 123,
        "tts_node_ttfb": 123,
        "transcript_confidence": 123,
        "stt_node_ttfb": 123
      }
    }
  ],
  "start_timestamp": 123,
  "end_timestamp": 123,
  "recording_url": "<string>",
  "agent_version": 1,
  "transcript": "<string>",
  "duration_ms": 123,
  "call_status": "<string>",
  "disconnection_reason": "<string>",
  "caller_phone_number": "<string>",
  "call_successful": true,
  "user_sentiment": "<string>",
  "in_voicemail": true,
  "collected_dynamic_variables": {},
  "call_cost": 123,
  "call_analysis": {},
  "metadata": {
    "ai_models": {
      "asr_model": "<string>",
      "llm_model": "<string>",
      "tts_model": "<string>"
    },
    "usage_token": {
      "stt_duration_seconds": 123,
      "llm_token": 123,
      "tts_characters_count": 123
    }
  },
  "general_meta_data_raw": {},
  "recording_multi_channel_url": "<string>"
}
'
{
  "id": 123,
  "provider_call_id": "<string>",
  "is_new": true
}
This endpoint uses Tuner API key authentication.
Send your API key in the Authorization header as a Bearer token.

Authorizations

Authorization
string
header
required

Use Tuner API key (tr_api_...) or user session token. Find your API key in Workspace Settings > API Keys.

Query Parameters

workspace_id
integer
required
agent_remote_identifier
string
required

Your Agent ID configured in Tuner. Get this value from Agent Settings > Agent Connection > Agent ID.

Body

application/json

Request schema for public call creation.

call_id
string
required

Unique call identifier from your provider (used for idempotency).

Required string length: 1 - 200
call_type
string
required

Call channel/type from your provider (e.g., 'phone_call', 'web_call').

Required string length: 1 - 100
transcript_with_tool_calls
PublicTranscriptSegment · object[]
required

Unified call timeline. Each item represents either a user message, agent message, node transition, or a tool event. Include timing either as word-level ("words") or segment-level ("start_ms + end_ms" or "duration_ms")

Minimum array length: 1
start_timestamp
integer
required

Call start time as Unix epoch. Accepts either seconds or milliseconds.

end_timestamp
integer
required

Call end time as Unix epoch. Accepts either seconds or milliseconds. Must be greater than or equal to start_timestamp.

recording_url
string
required

Publicly reachable recording URL (audio file or provider recording link).

Required string length: 1 - 1024
agent_version
integer | null

The version of the agent that handled this call (e.g. 3).

Required range: x >= 0
transcript
string | null

Diarized plain-text transcript (fallback for display/search). If omitted, we derive it from transcript_with_tool_calls when possible.

duration_ms
integer | null

Call duration in milliseconds. If omitted, we compute it from start_timestamp and end_timestamp.

call_status
string | null

Provider call status at ingest time. Preferred values: 'call_ended'.

Maximum string length: 100
disconnection_reason
string | null

Why the call ended (e.g. user_hangup, agent_hangup).

Maximum string length: 100
caller_phone_number
string | null

Caller phone number in E.164 format when available (e.g., '+14155550123').

Maximum string length: 50
call_successful
boolean | null

Whether the call was successful

user_sentiment
string | null

User sentiment label. Must be one of [positive, neutral, negative, unknown]

Maximum string length: 50
in_voicemail
boolean | null

Whether the call reached voicemail

collected_dynamic_variables
Collected Dynamic Variables · object

Dynamic variables collected during the call (free-form JSON)

call_cost
number | null

Total call cost in cents (e.g. 125 for $1.25). Client sends cents; frontend converts from dollars for UX.

call_analysis
Call Analysis · object

Provider-native analysis payload (free-form JSON; stored as-is)

metadata
CallMetadata · object

Call-level metadata (e.g. context, custom attributes). Supports structured ai_models and usage_token fields; extra keys are also accepted. Merged into general_meta_data_raw for storage. If both are sent, keys are merged; general_meta_data_raw keys win on collision.

general_meta_data_raw
General Meta Data Raw · object

Use to store any extra metadata payload as a JSON object

recording_multi_channel_url
string | null

Multi-channel recording URL (separate speaker channels), if available.

Maximum string length: 1024

Response

Successful Response

Response schema for public call creation.

id
integer
required

Internal Tuner call ID

provider_call_id
string
required

Echo of the provider call ID you sent (call_id).

is_new
boolean
required

Whether the call was newly created (false means it already existed)