> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usetuner.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Call

> Send call data from your voice AI platform to Tuner for analysis. This endpoint accepts call transcripts and metadata, then processes them through Tuner's evaluation pipeline.

<Info>
  This endpoint uses Tuner API key authentication.\
  Send your API key in the `Authorization` header as a Bearer token.
</Info>


## OpenAPI

````yaml POST /api/v1/public/call
openapi: 3.1.0
info:
  title: My Public API
  version: 1.0.0
servers:
  - url: https://api.usetuner.ai
security: []
paths:
  /api/v1/public/call:
    post:
      tags:
        - calls
      summary: Create Call
      description: >-
        Create a call via public API. Required query params: workspace_id,
        agent_remote_identifier.
      operationId: create_call_api_v1_public_call_post
      parameters:
        - name: workspace_id
          in: query
          required: true
          schema:
            type: integer
            title: Workspace Id
        - name: agent_remote_identifier
          in: query
          required: true
          schema:
            type: string
            description: >-
              Your Agent ID configured in Tuner. Get this value from Agent
              Settings > Agent Connection > Agent ID.
            title: Agent Remote Identifier
          description: >-
            Your Agent ID configured in Tuner. Get this value from Agent
            Settings > Agent Connection > Agent ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCallRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCallResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - Bearer: []
components:
  schemas:
    CreateCallRequest:
      properties:
        call_id:
          type: string
          maxLength: 200
          minLength: 1
          title: Call Id
          description: Unique call identifier from your provider (used for idempotency).
        sip_call_id:
          anyOf:
            - type: string
              maxLength: 200
              minLength: 1
            - type: 'null'
          title: Sip Call Id
          description: >-
            Optional SIP call identifier. When provided, it is used as
            provider_call_id for persistence and idempotency.
        recipient:
          anyOf:
            - type: string
              maxLength: 500
              minLength: 1
            - type: 'null'
          title: Recipient
          description: Recipient phone number (E.164) or SIP URL for outbound calls.
        call_type:
          type: string
          maxLength: 100
          minLength: 1
          title: Call Type
          description: >-
            Call channel/type from your provider (e.g., 'phone_call',
            'web_call').
        agent_version:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Agent Version
          description: The version of the agent that handled this call (e.g. 3).
        transcript_with_tool_calls:
          items:
            $ref: '#/components/schemas/PublicTranscriptSegment'
          type: array
          minItems: 1
          title: Transcript With Tool Calls
          description: >-
            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")
        start_timestamp:
          type: integer
          title: Start Timestamp
          description: ' Call start time as Unix epoch. Accepts either seconds or milliseconds.'
        end_timestamp:
          type: integer
          title: End Timestamp
          description: >-
            Call end time as Unix epoch. Accepts either seconds or milliseconds.
            Must be greater than or equal to start_timestamp.
        recording_url:
          type: string
          maxLength: 1024
          minLength: 1
          title: Recording Url
          description: >-
            Publicly reachable recording URL (audio file or provider recording
            link).
        transcript:
          anyOf:
            - type: string
            - type: 'null'
          title: Transcript
          description: >-
            Diarized plain-text transcript (fallback for display/search). If
            omitted, we derive it from transcript_with_tool_calls when possible.
        duration_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration Ms
          description: >-
            Call duration in milliseconds. If omitted, we compute it from
            start_timestamp and end_timestamp.
        call_status:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Call Status
          description: 'Provider call status at ingest time. Preferred values: ''call_ended''.'
        disconnection_reason:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Disconnection Reason
          description: Why the call ended (e.g. user_hangup, agent_hangup).
        caller_phone_number:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: Caller Phone Number
          description: >-
            Caller phone number in E.164 format when available (e.g.,
            '+14155550123').
        call_successful:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Call Successful
          description: Whether the call was successful
        user_sentiment:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: User Sentiment
          description: >-
            User sentiment label. Must be one of [positive, neutral, negative,
            unknown]
        in_voicemail:
          anyOf:
            - type: boolean
            - type: 'null'
          title: In Voicemail
          description: Whether the call reached voicemail
        collected_dynamic_variables:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Collected Dynamic Variables
          description: Dynamic variables collected during the call (free-form JSON)
        call_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Call Cost
          description: >-
            Total call cost in cents (e.g. 125 for $1.25). Client sends cents;
            frontend converts from dollars for UX.
        call_analysis:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Call Analysis
          description: Provider-native analysis payload (free-form JSON; stored as-is)
        metadata:
          anyOf:
            - $ref: '#/components/schemas/CallMetadata'
            - type: 'null'
          description: >-
            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:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: General Meta Data Raw
          description: Use to store any extra metadata payload as a JSON object
        recording_multi_channel_url:
          anyOf:
            - type: string
              maxLength: 1024
            - type: 'null'
          title: Recording Multi Channel Url
          description: >-
            Multi-channel recording URL (separate speaker channels), if
            available.
      type: object
      required:
        - call_id
        - call_type
        - transcript_with_tool_calls
        - start_timestamp
        - end_timestamp
        - recording_url
      title: CreateCallRequest
      description: Request schema for public call creation.
    CreateCallResponse:
      properties:
        id:
          type: integer
          title: Id
          description: Internal Tuner call ID
        provider_call_id:
          type: string
          title: Provider Call Id
          description: >-
            Echo of the persisted provider call ID (sip_call_id when provided,
            else call_id).
        is_new:
          type: boolean
          title: Is New
          description: Whether the call was newly created (false means it already existed)
      type: object
      required:
        - id
        - provider_call_id
        - is_new
      title: CreateCallResponse
      description: Response schema for public call creation.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PublicTranscriptSegment:
      properties:
        role:
          $ref: '#/components/schemas/PublicTranscriptRole'
          description: >-
            Defines the type of segment in the call timeline. Allowed:
            node_transition, user, agent, agent_function, agent_result
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          description: Utterance text for user or agent messages.
        words:
          anyOf:
            - items:
                $ref: '#/components/schemas/PublicTranscriptWord'
              type: array
            - type: 'null'
          title: Words
          description: Word-level timing data (recommended when available).
        start_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Start Ms
          description: >-
            Segment start time relative to call start (ms); accepts int or
            float, stored as int (ceiling).
        end_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: End Ms
          description: >-
            Segment end time relative to call start (ms); accepts int or float,
            stored as int (ceiling).
        duration_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration Ms
          description: >-
            Utterance duration (ms); accepts int or float, stored as int
            (ceiling). Should equal end_ms - start_ms if both set.
        node:
          anyOf:
            - $ref: '#/components/schemas/PublicTranscriptNode'
            - type: 'null'
          description: Workflow transition details (used for node_transition).
        tool:
          anyOf:
            - $ref: '#/components/schemas/PublicTranscriptTool'
            - type: 'null'
          description: >-
            Tool invocation or result details (used for agent_function and
            agent_result).
        metadata:
          $ref: '#/components/schemas/PublicTranscriptMetadata'
          description: Provider-specific metadata with known timing fields plus extra keys
      additionalProperties: true
      type: object
      required:
        - role
      title: PublicTranscriptSegment
      description: |-
        Single transcript segment: unified shape for all providers.

        For role in ('user', 'agent') at least one timing source is required:
        - words (non-empty with start_ms/end_ms), or
        - start_ms + end_ms, or
        - start_ms + duration_ms (end_ms is then derived).
    CallMetadata:
      properties:
        ai_models:
          anyOf:
            - $ref: '#/components/schemas/AiModels'
            - type: 'null'
          description: AI model identifiers used during the call
        usage_token:
          anyOf:
            - $ref: '#/components/schemas/UsageToken'
            - type: 'null'
          description: Token and usage metrics for the call
      additionalProperties: true
      type: object
      title: CallMetadata
      description: >-
        Call-level metadata with structured AI model and usage token
        information.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    PublicTranscriptRole:
      type: string
      enum:
        - node_transition
        - user
        - agent
        - agent_function
        - agent_result
      title: PublicTranscriptRole
    PublicTranscriptWord:
      properties:
        word:
          type: string
          title: Word
          description: The word text
        start_ms:
          type: integer
          title: Start Ms
          description: >-
            Start time relative to call start (ms); accepts int or float, stored
            as int (ceiling)
        end_ms:
          type: integer
          title: End Ms
          description: >-
            End time relative to call start (ms); accepts int or float, stored
            as int (ceiling)
        confidence:
          anyOf:
            - type: number
            - type: 'null'
          title: Confidence
          description: Optional confidence score
      type: object
      required:
        - word
        - start_ms
        - end_ms
      title: PublicTranscriptWord
      description: Word-level timing; preferred when available for accurate metrics.
    PublicTranscriptNode:
      properties:
        from:
          anyOf:
            - type: string
            - type: 'null'
          title: From
          description: Source node id; null for the initial transition
        to:
          type: string
          title: To
          description: Target node id
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
          description: Transition reason (e.g. 'workflow route')
      type: object
      required:
        - to
      title: PublicTranscriptNode
      description: Workflow node transition; only for role='node_transition'.
    PublicTranscriptTool:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Tool name
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request id
        params:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Params
          description: Tool input parameters (JSON).
        result:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Result
          description: Tool output payload (JSON).
        is_error:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Error
          description: Whether the tool execution resulted in an error.
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message returned by the tool.
        start_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Start Ms
          description: Tool invocation time relative to call start (ms).
        end_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: End Ms
          description: Tool invocation time relative to call start (ms); equals start_ms.
      type: object
      title: PublicTranscriptTool
      description: >-
        Tool call info; for role='agent_function' (params set) and
        'agent_result' (result set).
    PublicTranscriptMetadata:
      properties:
        e2e_latency:
          anyOf:
            - type: number
            - type: 'null'
          title: E2E Latency
          description: Total end-to-end latency for the segment, in milliseconds
        interrupted:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Interrupted
          description: Whether the segment was interrupted before completion
        llm_node_ttft:
          anyOf:
            - type: number
            - type: 'null'
          title: Llm Node Ttft
          description: Time from LLM input to first output token, in milliseconds
        tts_node_ttfb:
          anyOf:
            - type: number
            - type: 'null'
          title: Tts Node Ttfb
          description: Time from TTS request to first audio byte, in milliseconds
        transcript_confidence:
          anyOf:
            - type: number
            - type: 'null'
          title: Transcript Confidence
          description: Confidence score of transcript quality
        stt_node_ttfb:
          anyOf:
            - type: number
            - type: 'null'
          title: Stt Node Ttfb
          description: >-
            Time from end of user speech to transcript finalized, in
            milliseconds
        eou_delay:
          anyOf:
            - type: number
            - type: 'null'
          title: Eou Delay
          description: >-
            Time from end of user speech to end of turn detected, in
            milliseconds
      additionalProperties: true
      type: object
      title: PublicTranscriptMetadata
      description: Structured segment metadata with optional timing/confidence fields.
    AiModels:
      properties:
        asr_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Asr Model
          description: ASR (speech-to-text) model identifier
        llm_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Llm Model
          description: LLM model identifier
        tts_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Tts Model
          description: TTS (text-to-speech) model identifier
      additionalProperties: true
      type: object
      title: AiModels
      description: AI model identifiers used during the call.
    UsageToken:
      properties:
        stt_duration_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Stt Duration Seconds
          description: ASR audio duration processed (seconds)
        llm_token:
          anyOf:
            - type: integer
            - type: string
            - type: 'null'
          title: Llm Token
          description: LLM token usage
        tts_characters_count:
          anyOf:
            - type: integer
            - type: string
            - type: 'null'
          title: Tts Characters Count
          description: TTS characters count
      additionalProperties: true
      type: object
      title: UsageToken
      description: Token and usage metrics for the call.
  securitySchemes:
    Bearer:
      type: http
      description: >-
        Use Tuner API key (tr_api_...) or user session token. Find your API key
        in Workspace Settings > API Keys.
      scheme: bearer

````