> ## 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.

# Cancel a takeover

> Closes the window before the person joins (for `dial_out`, the ring stops). The caller stays with the agent. Cancelling again is harmless. After the person joined it is `409 handoff_active`: use [End a takeover](/api-reference/human-takeover/end-a-takeover).



## OpenAPI

````yaml /api-reference/openapi.json post /v2/calls/{call_id}/handoffs/{handoff_id}/cancel
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/calls/{call_id}/handoffs/{handoff_id}/cancel:
    post:
      tags:
        - Human takeover
      summary: Cancel a takeover
      description: >-
        Closes the window before the person joins (for `dial_out`, the ring
        stops). The caller stays with the agent. Cancelling again is harmless.
        After the person joined it is `409 handoff_active`: use [End a
        takeover](/api-reference/human-takeover/end-a-takeover).
      operationId: cancel_call_handoff
      parameters:
        - name: call_id
          in: path
          required: true
          description: The call's id (`call_…`), from the `202` that created it.
          schema:
            type: string
          example: call_01K2M4RB8CDEFGHJKMNPQRST
        - name: handoff_id
          in: path
          required: true
          description: ''
          schema:
            type: string
          example: hof_01K2M6A1B3C5D7E9F1G3H5J7K9
      responses:
        '200':
          description: Cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handoff'
              examples:
                Cancelled:
                  summary: 200 — cancelled
                  value:
                    id: hof_01K2M6A1B3C5D7E9F1G3H5J7K9
                    object: handoff
                    call_id: call_01K2M4RB8CDEFGHJKMNPQRST
                    mode: talk
                    ai: paused
                    initiator: api
                    connect:
                      type: dial_in
                      to: '+919812345678'
                      dial: '+918047360814'
                    state: ended
                    after_human: end_call
                    created_at: '2026-11-16T10:08:00.012Z'
                    expires_at: '2026-11-16T10:09:00.012Z'
                    metadata:
                      app_session: owner-app-7f3c
                    outcome: cancelled
                    reason: cancelled
                    ended_at: '2026-11-16T10:08:30.120Z'
        '409':
          description: The person already joined
          content:
            application/json:
              examples:
                The person already joined:
                  summary: 409 — the person already joined
                  value:
                    error:
                      code: handoff_active
                      message: the person has joined; end the takeover instead
components:
  schemas:
    Handoff:
      additionalProperties: false
      description: >-
        A live human takeover of a call in progress (a phone call, or a web call
        rung out to the person).
      properties:
        after_human:
          enum:
            - end_call
          type: string
        ai:
          enum:
            - paused
          type: string
        call_id:
          type: string
        connect:
          properties:
            dial:
              description: 'dial_in: the number the person dials: the call''s own number.'
              type: string
            from:
              description: >-
                dial_out: the number the person is rung from (the caller ID they
                see): the call's own number; on a web call the agent's
                calls_from number, else a Mirai number.
              type: string
            to:
              type: string
            type:
              description: >-
                dial_in (default on a phone call): the person dials the call's
                own number from connect.to. dial_out: we ring connect.to from
                the call's own number (on a web call, the only way: from the
                agent's calls_from number, else a Mirai number).
              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
        ended_by:
          enum:
            - human
            - caller
            - api
            - system
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          pattern: ^hof_
          type: string
        initiator:
          description: >-
            api: POST /v2/calls/{id}/handoffs. agent: the agent's transfer_call
            tool.
          enum:
            - api
            - agent
          type: string
        joined_at:
          format: date-time
          type: string
        metadata:
          type: object
        mode:
          enum:
            - talk
          type: string
        object:
          enum:
            - handoff
          type: string
        outcome:
          enum:
            - completed
            - failed
            - cancelled
            - expired
          type: string
        reason:
          enum:
            - expired
            - caller_left
            - join_failed
            - cancelled
            - human_hung_up
            - caller_hung_up
            - ended_by_api
            - max_duration
            - call_ended
            - worker_unsupported
            - no_answer
            - dial_failed
          type: string
        state:
          enum:
            - armed
            - connecting
            - active
            - ended
          type: string
      required:
        - id
        - object
        - call_id
        - mode
        - ai
        - initiator
        - connect
        - state
        - after_human
        - created_at
      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.