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

# Test an agent with a script

> Tests the agent without a phone: your customer's `lines` are typed to it one at a time in its text test chat, and you get back, per line, what the agent replied, the tools that ran and how long the reply took, then the post-call analysis of the whole conversation on `call`.

`lines` is required: 1–30 customer lines, each at most 2000 characters. Optional: `variables`, `call_settings`, `allowed_tools` and `metadata` as on [Place a call](/api-reference/calls/place-a-call), and `analysis` (default `true`; `false` skips the analysis and its wait).

It is a real test call on the text channel, billed by LLM tokens like the console's chat, and tools run against your real endpoints. One run per agent at a time, at most 3 per workspace.



## OpenAPI

````yaml /api-reference/openapi.json post /v2/agents/{agent_id}/test_script
openapi: 3.1.0
info:
  title: Voice Infra API
  version: 2026-10-20.turn-taking
  description: >-
    The v2 API for voice agents, calls, campaigns, phone numbers and speech.
    Every request carries `Authorization: Bearer sk_live_…`. Generated from the
    API's own contract and its Postman collection.
servers:
  - url: https://sandbox.voice.miraiminds.co
    description: 'Sandbox: trial workspaces, before your company goes live'
  - url: https://prod.voice.miraiminds.co
    description: 'Production: workspaces that have gone live'
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: >-
      An agent is what a call runs: its prompt (or a node flow, see the Flows
      section), voice, language and limits. Write it once and dial it as often
      as you like; each call fills in its own `variables`.


      Every save creates a new revision. You can read old revisions, roll back
      to one, and publish a draft when it is ready. None of the requests here
      place a call or charge your wallet.
  - name: Calls
    description: >-
      Place a call, follow it while it runs, then read what happened: the
      transcript, the recording, the post-call analysis.


      `POST /v2/calls` answers before the phone rings, with an id. Everything
      after that is about that id. Every call has a live event stream, phone
      calls included, so your own dashboard can show a call as it happens. Live
      control works on every voice call too: phone, browser and realtime. Your
      backend can tell the agent something new, have it say a line word for
      word, play an audio clip to the caller, or end the call.
  - name: Flows
    description: >-
      A node-based agent runs the call as a graph of steps. Each node has its
      own instructions, and the agent moves to the next node when a transition's
      condition is met, so a call with branches (wrong person, not now,
      reschedule) stays easy to follow and to change.


      The usual path: draft a graph from a brief or from recordings of your real
      calls, check it, test it with simulated calls, then save it on an agent.
      Drafting, transcribing and testing use AI models and charge your wallet;
      checking, saving and reading are free.


      Full guide: https://docs.miraiminds.co/v2/node-agents
  - name: Tools and secrets
    description: >-
      Connect your own APIs to an agent. A tool runs at one of three moments:


      * `pre_call`, before dialling: fetch context for the greeting, or skip the
      call.

      * `on_call`, when the agent decides to use it mid-conversation: look
      something up, book something.

      * `post_call`, after the call has settled: send the outcome to your CRM,
      schedule a call back.


      The order here is the order you'd use them in: see what's available, store
      your credential as a secret, add a tool, test it against your endpoint,
      then read each call's tool runs. Tools themselves cost nothing extra.


      Tool definitions use Mirai's own templates, like `{{ args.date }}` and `{{
      secrets.crm_key }}`.


      A definition that doesn't validate comes back as a list, so you can fix
      everything at once: `{"error": "invalid_tools", "details": [{"path",
      "message"}]}`. Everything else uses the usual `{"error": {"code",
      "message"}}`.
  - name: Campaigns
    description: >-
      Call a whole list with one agent. Upload contacts, say which days and
      hours the campaign may ring, and start it. From then on it dials by
      itself: it paces itself, waits overnight, retries calls that didn't
      connect, skips numbers on your do-not-call list, and pauses itself when
      its budget or your wallet runs out, or when as many calls have connected
      as you asked for.


      Campaign calls are ordinary calls. They show up in `GET /v2/calls`, send
      the same `call.*` webhooks and bill the same per-minute rate. In a sandbox
      workspace every campaign runs and bills at T5 (₹5 a minute), whatever tier
      you ask for.


      Money on a campaign is in **paise**: `"budget_paise": 50000` is ₹500.


      The requests run top to bottom: create saves `campaign_id`, and the rest
      use it. Starting a campaign rings every contact on it, so put numbers
      you're allowed to call in the bodies first.
  - name: Do-not-call list
    description: >-
      Numbers your workspace will never call. The list stops every outbound
      call: `POST /v2/calls` answers 422 `do_not_call`, a scheduled callback
      isn't placed, and every campaign skips the number, including campaigns
      that are already running. A skipped contact stays in its campaign as
      `suppressed` and costs nothing.


      Numbers get here three ways, and each entry's `source` says which:


      - `manual`: you added it.

      - `caller_request`: the person asked on a call not to be called again. We
      check every connected phone call for this and add the number on our own;
      `call_id` is the call and `note` is what they said.

      - `complaint`: the person filed a TRAI UCC complaint about one of your
      calls. `note` is the complaint's reference. These stay on for good, and no
      workspace on the platform can call the number.


      It's your own list, not the national DND register, and adding a number
      here doesn't meet your DND obligations.
  - name: Phone numbers
    description: >-
      The numbers your agents answer. Each one comes from the **Telephony**
      section:


      * **Rented from Mirai.** Once the rental is active, the number shows up
      here by itself (`ownership: managed`).

      * **From your own Plivo account.** Connect the account in Telephony, list
      its numbers, then bring one here with [Import a Plivo
      number](/api-reference/phone-numbers/import-a-plivo-number) (`ownership:
      customer`). Plivo keeps billing you for it.

      * **On your own SIP trunk.** Connect the trunk in Telephony, then add each
      of its numbers with *Add a number on your SIP trunk* (`provider: sip`). It
      arrives `ready`: assign an agent and it answers.


      After that it's two steps, in this order: [Assign an
      agent](/api-reference/phone-numbers/assign-an-agent) (who answers), then
      [Turn on incoming
      calls](/api-reference/phone-numbers/turn-on-incoming-calls). `state` is
      `imported` until calls are on and `ready` after; `error` means the last
      attempt to turn calls on failed, and `setup_error` says why.


      Every change sends the number's current `version`, and each change raises
      it by one. If you're not sure what it is, read the number first; a stale
      version is a 409 `conflict` and changes nothing.


      To call out from one of your numbers, place a call with `phone_number_id`
      set to its id once it is `ready` (Indian destinations only). Calls on your
      numbers are billed like any other call.


      Every number also says how it is doing in `health`: `state` is `active`,
      `warming` (its first week, at half its pool's pace), `resting`, `cooling`
      (rested three times in a day; waits for you) or `retired`, with this
      hour's attempts and seven days of answers. You can rest, resume and retire
      your own numbers; a resting or retired number still answers calls to it.
  - name: Phone pools
    description: >-
      A pool is a group of your own phone numbers that a campaign, an agent or a
      single call can ring from. Each call takes the number best placed for it:
      a number a contact has already been rung from stays theirs on a retry,
      numbers in the contact's own circle come first, and the pool's pace
      (`max_per_hour`, per number) is held across every campaign and API call at
      once. A number whose answers drop well below its pool-mates' rests on its
      own for 45 minutes.


      Point a campaign at a pool with `pool_id` on [Create a
      campaign](/api-reference/campaigns/create-a-campaign), an agent with
      `calls_from: {"pool_id": …}`, or one call with `pool_id` on [Place a
      call](/api-reference/calls/place-a-call). `pool_id` and `phone_number_id`
      never go together. With nothing chosen, calls come from the agent's
      setting, then the pool marked `default_for_campaigns`, then the Mirai
      shared line. A call's `calls_from_source` is `pool` (with `pool_id`) when
      a pool picked its number.


      A single call on a pool whose numbers are all resting or at their pace
      this hour answers 409 `pool_busy` with `Retry-After`; one with no number
      that can call, 409 `pool_unavailable`. A campaign doesn't fail: it waits
      and carries on.


      `purpose` is what the calls are for: `outreach` (promotional),
      `reminders`, `support` or `other`. It sets the starting pace: 40 an hour
      for support, 60 otherwise. Pools are free; numbers are billed as numbers.
  - name: Telephony
    description: >-
      Getting a phone number for your agent. There are two ways, and a workspace
      can use both.


      **1. Rent a number from Mirai.** ₹500 a month, paid as ₹1,500 from your
      wallet every three months, renewing until you turn it off. Indian numbers
      need a business verification that Plivo approves once: read the
      requirements, submit your details and documents, then refresh until it's
      `accepted`. After that: search, quote, rent. The rented number appears in
      **Phone numbers** by itself.


      Where [Get number options](/api-reference/telephony/get-number-options)
      lists `mobile` in `catalog`, you can also rent a mobile number at the same
      price, with nothing to verify first: *Search mobile numbers*, *Quote a
      mobile number* and rent. Mirai switches mobile numbers on per workspace;
      elsewhere those requests answer 409 `number_type_unavailable`.


      **2. Connect your own Plivo account.** Plivo keeps billing you directly.
      Connect it with your Auth ID and Auth Token, list the numbers it owns, and
      bring one over with [Import a Plivo
      number](/api-reference/phone-numbers/import-a-plivo-number). A Plivo main
      account can also rent new numbers through the same search → quote → rent
      requests, with its connection id as `account`.


      **3. Connect your own SIP trunk**, where [Get number
      options](/api-reference/telephony/get-number-options) lists `sip` for your
      workspace. Your carrier keeps billing you for the trunk. Tell us the
      carrier's address and the IP addresses it calls from, give your carrier
      the details in `sip` from [Get number
      options](/api-reference/telephony/get-number-options), then add the
      trunk's numbers by number with *Phone numbers → Add a number on your SIP
      trunk*.


      Either way you finish in **Phone numbers**: assign the agent that answers,
      then turn on incoming calls.


      The last two requests verify your own phone, so the workspace can ring it
      from Mirai's shared test number (test calls are placed from the Numbers
      page in the console).


      Indian (+91) numbers only for now. If phone numbers aren't available on
      the host you're calling, every request here answers 503
      `telephony_unavailable`.
  - name: Transcriptions
    description: >-
      Turn a recorded call (or any recording) into a transcript with speakers
      and timestamps. Hindi, English, Gujarati and mixed speech are written the
      way they were spoken, never translated. ₹18 per hour of audio; failed and
      degraded jobs are free.
  - name: Speech to text
    description: >-
      Speech to text in ten languages, two ways: send one recording and get its
      text back in the same request ([Transcribe a
      recording](/api-reference/speech-to-text/transcribe-a-recording)), or
      stream live audio over one WebSocket per call and read partial transcripts
      while people speak, then one final transcript per utterance. Language
      codes: hi-IN, en-IN, gu-IN, mr-IN, pa-IN, bn-IN, ta-IN, te-IN, kn-IN or
      ml-IN.


      `wss://sandbox.voice.miraiminds.co/v1/audio/transcriptions/stream?language_code=hi-IN&encoding=mulaw&sample_rate=8000&endpointing=manual`


      (`wss://prod.voice.miraiminds.co` once your company has gone live), with
      the header `Authorization: Bearer sk_live_YOUR_API_KEY`. 8 or 16 kHz,
      16-bit PCM, μ-law or A-law. A browser uses `?token=` from [Mint stream
      tokens](/api-reference/speech-to-text/mint-stream-tokens) instead, because
      it cannot set headers on a WebSocket.


      Send JSON text frames: `{"event": "speech_start"}`, then `{"event":
      "audio_input", "audio": "<base64 audio>"}` as the audio arrives, then
      `{"event": "speech_end"}`; `{"event": "end"}` closes the session. You
      receive `session.begin` first, `transcript.partial` while an utterance is
      open, exactly one `transcript.final` per utterance, and `session.end` with
      `audio_seconds_billed` and `cost_paise`.


      Every event, both endpointing modes, limits and errors:
      https://docs.miraiminds.co/v2/stt-quickstart
  - name: Text to speech
    description: >-
      Turn text into speech in one request, and read back what each request
      cost.
  - name: Wallet
    description: >-
      Your prepaid balance and every line that moved it. Calls, text to speech,
      flow drafts, transcriptions and number rentals all debit the same wallet.
  - name: Webhooks
    description: >-
      Get call events at your own HTTPS URL, signed, retried and kept for 30
      days.


      1. [Create a destination](/api-reference/webhooks/create-a-destination)
      with your URL. Save the `signing_secret` from that answer: it is shown
      once.

      2. [Subscribe a destination to
      events](/api-reference/webhooks/subscribe-a-destination-to-events), for
      one agent or the whole workspace. `call.completed` arrives when a call
      ends; `call.processing.completed` when the recording, transcript, results
      and post-call tools have all settled.

      3. [Send a test event](/api-reference/webhooks/send-a-test-event). It is a
      real POST to your URL with made-up call data and `test: true`. No call is
      placed.


      Rented numbers have events too: `phone_number.renewal_upcoming` (7 days
      and 24 hours before a renewal, with `wallet_covers`, `short_by_paise`, and
      `reserved` / `reserved_inr` / `reserved_paise`, the amount already set
      aside for this renewal when the renewal reserve is on),
      `phone_number.renewed`, `phone_number.released` (`reason`
      `insufficient_balance` or `cancelled`), `phone_number.purchase_failed` and
      `phone_number.verification_updated`. `data.workspace_id` names the
      workspace that holds the number; for a sub-workspace your account's own
      subscriptions get them as well.


      A sub-workspace with a spending limit sends
      `workspace.spend_limit.warning` (80% of the limit used) and
      `workspace.spend_limit.reached` (100% used, or the first call refused for
      the limit), each once per period per limit setting, to the brand's
      subscriptions and your account's. The envelope's `workspace_id` is the
      workspace receiving that copy; `data.workspace_id` is always the brand and
      `data.parent_id` your account. `data` also carries `workspace_name`,
      `spend` (the brand's spend, as [Get a sub-workspace's
      spend](/api-reference/sub-workspaces/get-a-sub-workspaces-spend) returns
      it) and, when a refused call triggered it, `call.id`. Email destinations
      can take them.


      Every request carries `X-Mirai-Signature: t=<unix>,v1=<hex>`, an
      HMAC-SHA256 of `<unix>.<raw body>`, and `X-Mirai-Signed-With`, which names
      the secret that signed it. A destination's requests are signed with its
      own Destination secret; the `webhook_url` you pass when creating a call is
      signed with your Call webhook secret, the one shown with your API keys. A
      URL that is both gets each event once, with one secret. Delivery is at
      least once, so keep each event `id` and skip ones you've already handled.


      Changes send the resource's current `revision` (`if_revision`); a stale
      one is a 409 and changes nothing. Until the webhook release reaches your
      workspace these routes answer 404. The same settings are in the console
      under Webhooks, and on each agent in Agent Studio.
  - name: Human takeover
    description: >-
      A person from your team takes over a live call. The agent stops speaking,
      the person talks to the caller, and when the person hangs up the call ends
      (`ended_reason: transferred`). If nobody joins, the caller carries on with
      the agent.


      Two ways to bring the person in, picked with `connect.type`:


      * `dial_in` (the default): the person dials the call's own number
      (`connect.dial`) from the handoff number before `expires_at`. Made for an
      owner who taps *take over* in your app and calls in.

      * `dial_out`: Mirai rings the number in `connect.to` from the call's own
      number (`connect.from`, the caller ID they see) and joins them when they
      pick up. Made for bringing a colleague in. Only when you send it.


      Works on phone calls on your own numbers (rented from Mirai, from your own
      telco account, a SIP trunk or a managed carrier) and on web calls
      (browser, test links). A web call has no number to dial in to, so the
      person is always rung (`dial_out`, the default there; `dial_in` is `400
      unsupported_connect`), from the agent's `calls_from` number, else a Mirai
      number. Not on the Mirai shared line, WhatsApp or realtime sessions (`400
      unsupported_channel`). On a sub-workspace's call, only the parent's key
      with the `Mirai-Workspace` header may use these routes (`403
      parent_account_required`).


      The agent can start the same `dial_out` takeover itself with the
      `transfer_call` tool (see Tools): the handoff then has `initiator: agent`.
  - name: WhatsApp numbers
    description: >-
      Let an agent answer WhatsApp voice calls on your WhatsApp Business number.
      Whether WhatsApp calling is open for your workspace depends on how it was
      set up with us: where it isn't, these answer `503 whatsapp_unavailable`
      and change nothing.
  - name: Recordings
    description: >-
      Upload a recording of a conversation, a phone call between two people or
      any recording, and get back what a call with your agent gets: a transcript
      with speakers, a summary and your agent's post-call analysis. Name an
      agent to get the summary and analysis; leave it out for a transcript only.


      ₹0.30 per minute of audio for the transcript and ₹0.20 per minute for the
      summary and analysis (₹0.50 together), billed per second. Each part is
      charged only when it succeeds.
  - name: Sub-workspaces
    description: >-
      For partners who run calls for many brands. Each brand gets its own
      sub-workspace under your account, with its own agents, campaigns, calls,
      phone numbers, knowledge bases, tool secrets and do-not-call list. Money
      stays in one place: every brand spends from your account's wallet at your
      account's rates, and you get one invoice.


      **Acting as a brand.** Use your account's API key on any request in this
      collection and add one header:


      ```

      Mirai-Workspace: ws_6f1c0a9e2b7d4c3a8e5f9b10

      ```


      The value is the sub-workspace's `id` or the `external_id` you gave it.
      Without the header, or with your account's own id in it, the request acts
      on your account as it always has. `X-Workspace` and `Workspace` work too,
      so an integration that already sends v1's `workspace` header keeps working
      once your brands are set up here with their v1 workspace ids as
      `external_id`. If your account has no sub-workspaces, those two are
      ignored.


      A value that names none of your brands is `404 workspace_not_found`; an
      archived brand is `403 workspace_archived`. The header only looks among
      your own brands, so it can never reach someone else's workspace.


      Call webhooks and campaign webhooks from every brand are signed with your
      account's webhook secret, and requests for all your brands share your
      key's rate limit. `GET /v2/wallet` with the header shows the shared
      account balance, plus that brand's `spend` against its spending limit.


      **Spending limits.** Cap what one brand's calls can spend from your wallet
      with `spend_limit` on *Create* or [Update a
      sub-workspace](/api-reference/sub-workspaces/update-a-sub-workspace): an
      amount in rupees (`amount_inr`) or paise (`amount_paise`), every month
      (`monthly`, from the 1st in the brand's timezone) or in total
      (`lifetime`). Only call charges count (voice minutes, managed telephony,
      post-call insights, on every channel); number rentals, speech,
      transcription and model APIs don't. Before a call starts, its worst case
      is held against the limit, so a call already running always finishes and
      can't take the brand past it. Once the limit can't cover a minute, new
      calls get `402 spend_limit_reached`, a call that can't be held ends
      `failed` with `ended_reason: spend_limit_reached` (nothing rings, nothing
      is charged), and the brand's campaigns pause with `pause_reason:
      spend_limit_reached`. They don't resume on their own: resume them once you
      raise the limit or a new month starts. `workspace.spend_limit.warning`
      (80% used) and `workspace.spend_limit.reached` webhooks go to the brand's
      subscriptions and your account's.


      **Managing brands.** The requests below act on your account, so send them
      without the header: with one they answer `400`. Sub-workspaces are
      switched on per account with a limit. Ask us to turn them on for yours.
  - name: Status
    description: >-
      Incidents and planned maintenance that concern your workspace, written by
      our team as they happen.


      [List incidents](/api-reference/status/list-incidents) returns the
      platform incidents on the public status page and the ones that touched
      your workspace: each open one, and each that ended in the last 30 days,
      newest first, with its latest update. `workspace_impact` is what it did to
      your workspace alone: the agents with failed calls, `calls_failed`, and
      `billed`, whether those calls were charged. It is `null` until we have
      counted.


      To be told as it happens, subscribe a webhook destination (an HTTPS URL or
      email addresses) to the `status` events: `incident.opened`,
      `incident.updated`, `incident.resolved`, `maintenance.scheduled`,
      `maintenance.started` and `maintenance.completed`. Your account's owners
      also get each update by email; `PATCH /v2/webhooks/settings` with
      `status_email: false` turns that off for a workspace. The console shows
      the same list under Status.


      Without a key, `GET /v2/status/public` returns the incidents on the public
      status page (no workspace data) and `GET /v2/status/platform` whether each
      part works right now.
  - name: Reference
    description: The voice catalogue, and the API contract as a machine-readable document.
paths:
  /v2/agents/{agent_id}/test_script:
    post:
      tags:
        - Agents
      summary: Test an agent with a script
      description: >-
        Tests the agent without a phone: your customer's `lines` are typed to it
        one at a time in its text test chat, and you get back, per line, what
        the agent replied, the tools that ran and how long the reply took, then
        the post-call analysis of the whole conversation on `call`.


        `lines` is required: 1–30 customer lines, each at most 2000 characters.
        Optional: `variables`, `call_settings`, `allowed_tools` and `metadata`
        as on [Place a call](/api-reference/calls/place-a-call), and `analysis`
        (default `true`; `false` skips the analysis and its wait).


        It is a real test call on the text channel, billed by LLM tokens like
        the console's chat, and tools run against your real endpoints. One run
        per agent at a time, at most 3 per workspace.
      operationId: test_agent_script
      parameters:
        - name: agent_id
          in: path
          required: true
          description: The agent's id (`agt_…`).
          schema:
            type: string
          example: agt_01K2M4P7QRSTVWXYZ0A1B2C3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                allowed_tools:
                  items:
                    type: string
                  type: array
                analysis:
                  type: boolean
                call_settings:
                  additionalProperties: false
                  description: >-
                    The voice and languages for this call only, over the
                    agent's. Every key is optional; a key left out keeps the
                    agent's value (or, on a campaign contact, the request's).
                    The same object is accepted on POST /v2/calls, on a campaign
                    contact and in a pre_call tool's result. An unknown key or a
                    value that fails these rules is 400 invalid_request naming
                    it.
                  properties:
                    language:
                      description: >-
                        The main language speech recognition listens for on this
                        call, as an agent's language (for example hi, gu or
                        en-IN).
                      maxLength: 35
                      minLength: 1
                      type: string
                    secondary_languages:
                      description: >-
                        Other languages callers may speak on this call. Base
                        codes (gu-IN is read as gu; or as od); duplicates and
                        the main language are dropped; at most 4. [] listens for
                        the main language only.
                      items:
                        enum:
                          - hi
                          - en
                          - gu
                          - mr
                          - bn
                          - ta
                          - te
                          - kn
                          - ml
                          - pa
                          - od
                        type: string
                      maxItems: 4
                      type: array
                    voice_id:
                      description: >-
                        The voice the agent speaks in on this call: one of the
                        voices an agent's voice.voice_id accepts, including your
                        own custom voices (cv_...) except on channel realtime
                        (422 voice_not_supported). Same as the older
                        voice.voice_id; both with different values is 400.
                      minLength: 1
                      type: string
                  type: object
                lines:
                  items:
                    type: string
                  type: array
                metadata:
                  additionalProperties:
                    type: string
                  type: object
                variables:
                  additionalProperties: {}
                  type: object
              required:
                - lines
              type: object
            examples:
              Test an agent with a script:
                summary: Test an agent with a script
                value:
                  lines:
                    - हाँ, बोलिए
                    - 18 तारीख को सुबह 10 बजे ठीक है
                    - धन्यवाद
                  variables:
                    name: राहुल
                    vehicle: स्विफ्ट
                    due_date: 18 अक्टूबर
      responses:
        '200':
          description: The conversation and its analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestScript'
              examples:
                The conversation and its analysis:
                  summary: 200 — the conversation and its analysis
                  value:
                    object: test_script
                    call_id: call_01K7S2T4V6X8Z0B2D4F6H8J0L2
                    agent_id: agt_01K2M4P7QRSTVWXYZ0A1B2C3
                    status: completed
                    greeting:
                      - नमस्ते, आशु बोल रहा हूं. सर्विस की बात करनी थी.
                    turns:
                      - line: हाँ, बोलिए
                        status: answered
                        replies:
                          - >-
                            राहुल जी, आपकी स्विफ्ट की सर्विस 18 अक्टूबर को ड्यू
                            है. कौन सा समय ठीक रहेगा?
                        reply_ms: 1840
                      - line: 18 तारीख को सुबह 10 बजे ठीक है
                        status: answered
                        replies:
                          - बढ़िया, 18 अक्टूबर सुबह 10 बजे बुक कर दिया है.
                        tool_runs:
                          - name: create_booking
                            status: success
                            duration_ms: 412
                            tool_run_id: tr_01K7S2V1C3E5G7J9L1N3Q5S7U9
                        reply_ms: 2310
                      - line: धन्यवाद
                        status: answered
                        replies:
                          - धन्यवाद राहुल जी, आपका दिन शुभ हो.
                        reply_ms: 1290
                    ended_reason: assistant-ended-call
                    call:
                      id: call_01K7S2T4V6X8Z0B2D4F6H8J0L2
                      object: call
                      agent_id: agt_01K2M4P7QRSTVWXYZ0A1B2C3
                      channel: text
                      test: true
                      status: completed
                      cost:
                        amount_inr: 0.04
                        amount_paise: 4
                        per_min_inr: 0
                        per_min_paise: 0
                      analysis:
                        status: done
                        state: completed
                        summary: ग्राहक ने 18 अक्टूबर सुबह 10 बजे की सर्विस बुक की.
                        success: true
        '402':
          description: The wallet is empty
          content:
            application/json:
              examples:
                The wallet is empty:
                  summary: 402 — the wallet is empty
                  value:
                    error:
                      code: insufficient_balance
                      message: wallet balance is 0.00 INR
        '404':
          description: Not yours, deleted, or never existed
          content:
            application/json:
              examples:
                Not yours, deleted, or never existed:
                  summary: 404 — not yours, deleted, or never existed
                  value:
                    error:
                      code: not_found
                      message: no agent agt_01K2M4P7QRSTVWXYZ0A1B2C3
        '409':
          description: A run is already going for this agent
          content:
            application/json:
              examples:
                A run is already going for this agent:
                  summary: 409 — a run is already going for this agent
                  value:
                    error:
                      code: test_script_running
                      message: >-
                        a scripted test of agent agt_01K2M4P7QRSTVWXYZ0A1B2C3 is
                        already running; wait for it to finish
components:
  schemas:
    TestScript:
      description: >-
        A scripted test's answer (POST /v2/agents/{id}/test_script): the
        conversation line by line, then the test call as GET /v2/calls/{id}
        shows it once settled.
      properties:
        agent_id:
          description: The agent tested.
          type: string
        call:
          description: >-
            The test call once settled: status, cost (billed by LLM tokens),
            analysis and outcome. analysis is still pending when it did not
            finish in time; read GET /v2/calls/{id} later.
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Call'
        call_id:
          description: >-
            The test call (channel text, test true): readable with GET
            /v2/calls/{id}, its transcript and analysis.
          type: string
        ended_reason:
          description: >-
            How the conversation ended on the agent's side: customer-ended-call
            when the script hung up, assistant-ended-call when the agent did.
          type: string
        greeting:
          description: >-
            The agent's opening line(s), before the first customer line; empty
            when it waits for the customer.
          items:
            type: string
          type: array
        object:
          const: test_script
          description: Always test_script.
        status:
          description: >-
            completed: every line was sent; ended_early: the agent ended the
            conversation before the last line (see ended_reason); timed_out: the
            time budget ran out and the rest were not sent; failed: the
            conversation could not be continued.
          enum:
            - completed
            - ended_early
            - timed_out
            - failed
          type: string
        turns:
          description: One per customer line, in order.
          items:
            properties:
              error:
                description: Why the turn failed (status error).
                type: string
              line:
                description: The customer line, as sent (trimmed).
                type: string
              replies:
                description: Every agent line said before the next customer line.
                items:
                  type: string
                type: array
              reply_ms:
                description: From sending the line to the agent's first line back.
                type: integer
              status:
                description: >-
                  answered: the agent replied; no_reply: nothing came back in
                  time; error: the turn failed (error says why, e.g.
                  llm_unavailable); not_sent: the conversation had ended or time
                  ran out.
                enum:
                  - answered
                  - no_reply
                  - error
                  - not_sent
                type: string
              tool_runs:
                description: >-
                  The on-call tools that ran for this line: names and timings
                  only.
                items:
                  properties:
                    duration_ms:
                      description: How long the endpoint took.
                      type: integer
                    name:
                      description: The tool.
                      type: string
                    status:
                      description: >-
                        Its outcome as the call's tool receipts name it (ok,
                        error, timeout, ...), or running if it had not finished.
                      type: string
                    tool_run_id:
                      description: The receipt, in GET /v2/calls/{id}/tool_runs.
                      type: string
                  type: object
                type: array
            required:
              - line
              - status
              - replies
            type: object
          type: array
      required:
        - object
        - call_id
        - agent_id
        - status
        - greeting
        - turns
        - call
      type: object
    Call:
      description: >-
        Partial call response schema documenting additive fields; other existing
        call fields are retained.
      properties:
        allowed_tools:
          description: >-
            The allowed_tools the call was created with, as sent: the only tools
            of its agent that could run on it (the builtin end_call always stays
            as the agent configured it). Present on GET, list and the webhooks
            built from the stored call only when the call was created with it;
            absent otherwise.
          items:
            type: string
          type: array
        analysis:
          $ref: '#/components/schemas/CallAnalysisValue'
        call_settings:
          $ref: '#/components/schemas/CallSettingsEffective'
        calls_from_source:
          description: >-
            How an outbound phone call's number was chosen: request (the call's
            own phone_number_id, or its campaign's), agent (the agent's
            calls_from), pool (a phone pool picked it), own (nothing chose one,
            so the workspace's own number), shared (the Mirai shared line, only
            for a workspace with no number that can place calls; shared with
            other customers and showing as Mirai) or trunk (a Mirai line: one
            from a campaign's caller_ids, or the caller ID Mirai set up for your
            workspace's shared-line calls). Absent on inbound, web and WhatsApp
            calls.
          enum:
            - request
            - agent
            - pool
            - own
            - shared
            - trunk
          type: string
        campaign_id:
          description: >-
            The campaign that placed the call. Present on every view and event
            of a campaign call; absent on every other call.
          type: string
        channel:
          description: >-
            How the call was held: phone (dialled out, answered inbound, or a
            WhatsApp call), web (a browser session), text (the console's typed
            test chat) or realtime (a Realtime API session). The same vocabulary
            as GET /v2/calls/summary's by_channel. Present wherever created_at
            is.
          enum:
            - phone
            - web
            - text
            - realtime
          type: string
        contact_id:
          description: >-
            The campaign contact the call was to: the id you sent with the
            contact, or the one minted for it. Present wherever campaign_id is.
          type: string
        cost:
          description: >-
            The call's money. Each amount is in rupees (*_inr) and, beside it,
            the same amount in integer paise (*_paise), present exactly when its
            rupee twin is: amount and per_min always, the voice, insights and
            telco rates when the call was quoted split rates. A text chat,
            billed by tokens, has per_min 0.
          properties:
            ai_secs:
              description: >-
                Seconds the agent served the caller. Present only on a call a
                person took over.
              minimum: 0
              type: integer
            amount_inr:
              minimum: 0
              type: number
            amount_paise:
              minimum: 0
              type: integer
            billing_block_secs:
              type: integer
            human_per_min_inr:
              description: >-
                The per-minute rate of the time a person held the call: the
                call's own rate.
              minimum: 0
              type: number
            human_per_min_paise:
              minimum: 0
              type: integer
            human_secs:
              description: >-
                Seconds a person who took the call over served the caller.
                Present only on such a call.
              minimum: 0
              type: integer
            insights_per_min_inr:
              type: number
            insights_per_min_paise:
              type: integer
            legs:
              description: >-
                The inbound phone legs of the people who took the call over,
                each at the call's line rate and billing block (zero on your own
                telephony or trunk).
              items:
                properties:
                  amount_inr:
                    minimum: 0
                    type: number
                  amount_paise:
                    minimum: 0
                    type: integer
                  handoff_id:
                    type: string
                  telco_per_min_inr:
                    minimum: 0
                    type: number
                  telco_per_min_paise:
                    minimum: 0
                    type: integer
                  telco_secs:
                    minimum: 0
                    type: integer
                required:
                  - handoff_id
                  - telco_secs
                  - telco_per_min_inr
                  - telco_per_min_paise
                  - amount_inr
                  - amount_paise
                type: object
              type: array
            per_min_inr:
              minimum: 0
              type: number
            per_min_paise:
              minimum: 0
              type: integer
            telco_billing_block_secs:
              type: integer
            telco_per_min_inr:
              type: number
            telco_per_min_paise:
              type: integer
            telco_provider:
              type: string
            voice_per_min_inr:
              type: number
            voice_per_min_paise:
              type: integer
          required:
            - amount_inr
            - amount_paise
            - per_min_inr
            - per_min_paise
          type: object
        cost_inr:
          description: >-
            The charge in rupees, the same amount as cost.amount_inr; null while
            nothing was charged. Present on GET, the list and every event.
          type:
            - number
            - 'null'
        created_at:
          description: >-
            When the call was accepted (RFC 3339, UTC): the time GET /v2/calls
            orders by and its from/to filter on. Present on GET and list, and in
            data.call of the ending event (call.completed, call.failed,
            call.voicemail, call.aborted) and call.processed; not on call.queued
            or call.started. Absent only on a call stored without one.
          format: date-time
          type: string
        direction:
          description: >-
            inbound for a call somebody rang in on; outbound for every other
            call, including web, text and realtime sessions. Present on every
            call, GET and list alike; GET /v2/calls/summary counts by_direction
            with the same rule.
          enum:
            - inbound
            - outbound
          type: string
        flow:
          $ref: '#/components/schemas/CallFlow'
        forwarded_from:
          description: >-
            Incoming phone calls only: the number of the phone that forwarded
            this call to your number (carrier call forwarding on busy, no
            answer, unreachable or always), as the carrier reported it (SIP
            Diversion / History-Info). Not the caller (from) and not your number
            (to). E.164. Absent when the call was not forwarded or the carrier
            did not send it. In a tool or prompt template it is {{
            call.forwarded_from }} or {{ vars.forwarded_from }}, which are ""
            (empty) in that case.
          type: string
        from:
          description: >-
            Phone calls only. The number the call rang from: your phone number
            (phone_number_id), the campaign's caller ID, or the shared line the
            call was dialled through. Present once the call has been dialled,
            and on every event from call.started on; absent on web and realtime
            calls.
          type: string
        handling:
          description: >-
            Who served the caller last: human once a person took the call over.
            Present only on calls a takeover was armed on.
          enum:
            - ai
            - human
          type: string
        handoffs:
          description: >-
            Every live human takeover armed on the call, oldest first. Present
            only when there was one.
          items:
            properties:
              connect:
                properties:
                  dial:
                    description: >-
                      dial_in only. The number the person dials: the call's own
                      number.
                    type: string
                  from:
                    description: >-
                      dial_out only. The number the person was rung from: the
                      call's own number.
                    type: string
                  to:
                    type: string
                  type:
                    enum:
                      - dial_in
                      - dial_out
                    type: string
                required:
                  - type
                  - to
                type: object
              created_at:
                format: date-time
                type: string
              duration_secs:
                minimum: 0
                type: integer
              ended_at:
                format: date-time
                type: string
              id:
                type: string
              joined_at:
                format: date-time
                type: string
              mode:
                enum:
                  - talk
                type: string
              outcome:
                enum:
                  - completed
                  - failed
                  - cancelled
                  - expired
                type: string
              reason:
                type: string
              state:
                enum:
                  - armed
                  - connecting
                  - active
                  - ended
                type: string
            required:
              - id
              - mode
              - connect
              - state
              - created_at
            type: object
          type: array
        id:
          type: string
        metadata:
          additionalProperties:
            maxLength: 256
            type: string
          description: >-
            The metadata sent when the call was created — or, for a campaign
            call, the contact's metadata — echoed unchanged here and in every
            webhook's data.call. Never given to the agent. Absent when the call
            has none.
          maxProperties: 16
          propertyNames:
            pattern: ^[A-Za-z0-9_][A-Za-z0-9_.:-]{0,39}$
          type: object
        outcome:
          description: >-
            The call's outcome: the name the post-call analysis chose from its
            agent's analysis.outcomes, the same as analysis.outcome. null when
            the agent has no outcomes, when the analysis has not completed (yet)
            or did not run, and when none of the outcomes fits. On every call
            object: GET /v2/calls/{id}, list_calls (filter with outcome=) and
            every webhook's data.call. Events sent before the analysis
            (call.queued, call.started, call.completed and the other endings)
            say null; read it from call.analysis.completed, call.processed or
            GET. Not the agent home's own outcome (success, callback, talked,
            not_reached, ...), which classifies how any call ended.
          type:
            - string
            - 'null'
        phone_number_id:
          description: >-
            The id of your phone number the call rang from or was answered on.
            Absent when it rang from the shared line.
          type: string
        recording_available:
          description: >-
            The call's audio was stored: GET /v2/calls/{id}/recording answers
            it. Always present.
          type: boolean
        segments:
          description: >-
            Who held the floor when, in milliseconds from the start of the
            conversation. Present only on a call a person took over.
          items:
            properties:
              end_ms:
                minimum: 0
                type: integer
              handled_by:
                enum:
                  - ai
                  - human
                type: string
              handoff_id:
                type: string
              start_ms:
                minimum: 0
                type: integer
            required:
              - handled_by
              - start_ms
              - end_ms
            type: object
          type: array
        source:
          description: >-
            upload on the call object an uploaded recording's analysis is
            delivered with (POST /v2/recordings): its id is the recording's
            (rec_...), and it never was a call. Absent on every call.
          enum:
            - upload
          type: string
        tier:
          description: >-
            The price tier the call ran at (t1, t3 or t5). Present on GET, the
            list and every event.
          type: string
        transcript_available:
          description: >-
            A non-empty transcript was stored: GET /v2/calls/{id}/transcript
            answers it. Always present; transcript_status says why not.
          type: boolean
        transcript_status:
          description: >-
            pending until the call has ended and its transcript is settled;
            ready when GET /v2/calls/{id}/transcript returns turns; empty when
            nobody spoke or media never started; failed when the transcript was
            lost. Present on GET and list.
          enum:
            - pending
            - ready
            - empty
            - failed
          type: string
        updated_at:
          description: >-
            When anything GET /v2/calls/{id} returns for the call last changed
            (RFC 3339, UTC, milliseconds): its end and status, transcript,
            analysis, post-call processing, recording, flow outcome or a
            takeover. GET /v2/calls?updated_from= lists calls by it, oldest
            change first. The live status between queued and the end (dialing,
            in_progress) does not move it. A call last changed before it existed
            (November 2026) carries the latest time its record holds. Present on
            GET and list.
          format: date-time
          type: string
      type: object
    CallAnalysisValue:
      description: >-
        Analysis embedded on a call and in result/processed events. status
        preserves the legacy processing state; durable extraction adds state,
        generation and agent_revision when available. success is explicitly null
        when unknown.
      properties:
        agent_revision:
          type: integer
        completed_at:
          format: date-time
          type: string
        data:
          additionalProperties: true
          type: object
        error:
          properties:
            code:
              type: string
            message:
              type: string
          type: object
        generation:
          minimum: 1
          type: integer
        outcome:
          description: >-
            The name the analysis chose from the agent revision's
            analysis.outcomes. Present only on a completed analysis that chose
            one; the call object's top-level outcome carries the same name (null
            when there is none).
          type: string
        state:
          enum:
            - waiting_for_call
            - pending
            - processing
            - completed
            - failed
            - skipped
            - unavailable
          type: string
        status:
          description: >-
            Legacy processing status, preserved alongside durable extraction
            state.
          type: string
        success:
          type:
            - boolean
            - 'null'
        summary:
          type: string
        template:
          $ref: '#/components/schemas/AnalysisTemplateResult'
      required:
        - status
        - success
      type: object
    CallSettingsEffective:
      description: >-
        The voice and languages this call ran with, and who chose each. Present
        on every call admitted since per-call settings existed (GET, list and
        every webhook); absent on older calls.
      properties:
        language:
          type: string
        secondary_languages:
          items:
            type: string
          type: array
        sources:
          description: >-
            Where each value came from: agent (the agent's own), request (POST
            /v2/calls call_settings or voice.voice_id), campaign (the campaign
            contact) or pre_call:<tool name> (that pre_call tool's result).
          properties:
            language:
              examples:
                - agent
                - request
                - campaign
                - pre_call:crm_lookup
              type: string
            secondary_languages:
              examples:
                - agent
                - request
                - campaign
                - pre_call:crm_lookup
              type: string
            voice_id:
              examples:
                - agent
                - request
                - campaign
                - pre_call:crm_lookup
              type: string
          required:
            - voice_id
            - language
            - secondary_languages
          type: object
        voice_id:
          type: string
      required:
        - voice_id
        - language
        - secondary_languages
        - sources
      type: object
    CallFlow:
      description: >-
        A flow agent's call outcome. Present on GET /v2/calls/{id}, GET
        /v2/calls and call.processed data.call once the call's flow report has
        arrived (normally within seconds of the call ending); absent before that
        and on every prompt agent's call.
      properties:
        final_node:
          description: >-
            Id of the node the call ended on. Absent when the flow never entered
            a node (for example, the call failed before media).
          type: string
        nodes_visited:
          description: Node names in the order each was first entered; [] when none.
          items:
            type: string
          maxItems: 100
          type: array
        status:
          description: >-
            How the flow ended: end_call (an endCall node was reached),
            user_hangup, user_idle_max_duration_exceeded,
            call_duration_exceeded, pipeline_error, voicemail_detected or
            system_cancelled. A value outside this list is passed through as
            sent; treat it as an ending you do not recognise. Absent while only
            a partial report has arrived.
          examples:
            - end_call
            - user_hangup
            - user_idle_max_duration_exceeded
            - call_duration_exceeded
            - pipeline_error
            - voicemail_detected
            - system_cancelled
          type: string
        tags:
          description: >-
            Call tags the flow recorded (the disposition, user_speech, tag_*
            extractions). Absent when there are none.
          items:
            type: string
          maxItems: 100
          type: array
        variables:
          additionalProperties: true
          description: >-
            Values the nodes' extraction_variables captured, by variable name,
            as the model extracted them; {} when none.
          maxProperties: 256
          type: object
      required:
        - nodes_visited
        - variables
      type: object
    AnalysisTemplateResult:
      description: >-
        The template the analysis chose. Present only when the call's agent
        revision had analysis.templates.
      properties:
        error:
          properties:
            code:
              enum:
                - catalog_unavailable
                - catalog_empty
                - invalid_choice
                - model_failed
              type: string
            message:
              type: string
          type: object
        language:
          type: string
        missing:
          description: 'selected only, always present: declared keys left unfilled.'
          items:
            type: string
          type: array
        name:
          type: string
        reason:
          maxLength: 500
          type: string
        status:
          enum:
            - selected
            - none
            - failed
          type: string
        variables:
          additionalProperties:
            maxLength: 1000
            type: string
          description: >-
            selected only, always present: the declared keys the conversation
            established.
          type: object
      required:
        - status
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your workspace secret key, `sk_live_` followed by 32 hex characters.
        Create one in the console under **Developers**.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.