Voice AI Calling API

Overview

The Nutaan Calling API lets you build conversational AI phone agents that speak naturally, understand your business, and handle real calls — outbound and inbound. Everything you can do in the dashboard (agents, calls, batch campaigns, numbers, voices) is available over a clean REST API, authenticated with the same API key.

Base URL

https://nutaan.com/api

All requests use JSON. Send Content-Type: application/json on every POST/PATCH.

Authentication

Authenticate with your Nutaan API key. Generate one in the dashboard under Settings → API keys. Pass it in the X-API-Key header (or as a Bearer token). Keep it server-side — never expose it in a browser.

curl https://nutaan.com/api/voice/agents \
  -H "X-API-Key: nut-XXXXXXXXXXXXXXXXXXXX"

The same key also works as a Bearer token:

-H "Authorization: Bearer nut-XXXXXXXXXXXXXXXXXXXX"

MCP — drive Nutaan from Claude, ChatGPT or Cursor

Nutaan hosts an MCP server, so an AI assistant can work the account directly: build an agent from a website, dial a whole list of contacts, then read the transcripts and the leads that come out. Nothing to install — you paste one URL.

https://nutaan.com/api/mcp/YOUR_API_KEY

Take the key from Settings → API keys (it starts with nut-) and paste that whole URL wherever your client asks for a custom connector or a remote MCP server:

Claude Code, Gemini CLI — one command in your terminal (the dashboard's Developers → MCP tab gives it to you with your key already in it):

claude mcp add --transport http nutaan https://nutaan.com/api/mcp/YOUR_API_KEY
gemini mcp add --transport http nutaan https://nutaan.com/api/mcp/YOUR_API_KEY

Claude (web or desktop) — Settings → Connectors → Add custom connector. Name it Nutaan, paste the URL into the address field, leave the OAuth boxes empty, press Add.

ChatGPT — Settings → Connectors → Add, same URL.

Cursor, Windsurf, VS Code — put it in the MCP config:

{
  "mcpServers": {
    "nutaan": { "url": "https://nutaan.com/api/mcp/YOUR_API_KEY" }
  }
}

The key rides in the URL because those dialogs take a URL and nothing else — there is no field for a header. So treat the URL like a password: anyone holding it can act on your account, and you rotate it by rotating the key. Clients that can send headers should use the bare https://nutaan.com/api/mcp endpoint with Authorization: Bearer nut-… or X-API-Key instead.

Approvals, and turning them off

By default the assistant checks with you before it spends credit or rings anyone. If those confirmations get in the way — you are running campaigns and being asked to approve each one — use the autonomous URL instead:

https://nutaan.com/api/mcp/auto/YOUR_API_KEY

On that URL the tools drop their "ask first" instructions entirely rather than being told to both ask and not ask, and the assistant is told it is pre-authorised, so it carries out the work and reports afterwards — and can run independent steps at the same time instead of one approval at a time. It still stops if a request is ambiguous, if a contact list looks wrong, or if something failed partway.

Which mode you are in is fixed by the URL you pasted, so nothing the assistant later reads — a web page, a document, a tool result — can switch autonomy on. To change it, paste the other URL. Connect Tools has a checkbox that produces both.

It speaks Streamable HTTP over JSON-RPC, so anything MCP-compatible works. For a client that can only launch a local process, the repo also ships mcp-server/ — a stdio bridge onto this same endpoint, holding no tools of its own so it cannot drift.

Where this gets useful

A whole outbound campaign becomes one conversation. Research the list in your assistant, have it build the right agent, and let it dial — without opening the dashboard:

You:  Find 100 dental clinics in Pune with phone numbers.
      (your assistant researches them)

You:  Read smilecare.in and build an outbound agent that books
      consultations - warm female voice, Hindi.
      -> nutaan_discover_business, then nutaan_create_agent

You:  Call all 100 with that agent.
      -> nutaan_create_batch   (it confirms the list size first)

You:  How is it going?
      -> nutaan_batch_status   43/100 called, 18 answered

You:  Which ones are worth following up?
      -> nutaan_list_leads     number, what they wanted, next step

The 18 tools

nutaan_list_agents         your agents, with language, voice and number
nutaan_get_agent           one agent in full, including its prompt
nutaan_discover_business   read a website, report what an agent would know
nutaan_create_agent        build an agent, with a number and a link to test it
nutaan_update_agent        FIX an existing agent - prompt, language, voice, KB
nutaan_list_voices         voices for a language + this account's premium access
nutaan_prompt_guide        how to write a prompt that works on a phone call
nutaan_place_call          place one real call
nutaan_create_batch        create a campaign and dial a whole list
nutaan_list_batches        campaigns and their progress
nutaan_batch_status        one campaign, with per-call outcomes
nutaan_list_calls          recent calls with status and duration
nutaan_get_call            one call with its transcript
nutaan_list_leads          qualified leads - number, intent, next step
nutaan_analyze_calls       extract contacts and intent from new calls
nutaan_create_knowledge_base  crawl a site so agents can answer from it
nutaan_list_knowledge_bases   knowledge bases and their crawl status
nutaan_share_agent         create a public link anyone can talk to

Two of these exist to stop an assistant guessing. nutaan_list_voicesreports which voices cover a language and whether this account may use the premium ones — ask for a premium voice without access, or one that does not cover the language, and you get an agent nobody can hear. nutaan_prompt_guidecarries the rules for phone prompts: a hand-written one is nearly always too short, and a short prompt makes the agent improvise prices and opening hours. Better still, let nutaan_create_agent write it from the website and add your own rules on top with appendToPrompt.

nutaan_update_agent matters more than it looks: without it an assistant that finds a fault in an agent can only build a second one, leaving the broken agent live and stranding its number and call history. Correcting an agent in place is the normal path — creating is for agents that do not exist yet.

Five of them change something real — creating an agent, placing a call, starting a campaign, sharing an agent publicly, and running analysis. Each says so in its own description, so a well-behaved client asks you first. Nothing in the set deletes anything, and every tool runs through this same REST API under your key's scopes, so MCP can never reach further than your own integrations can.

Voice agents

A voice agent is the AI persona that answers and speaks on a call — its instructions, language, LLM, and voice. Create one, then reference its _id when you place calls.

curl https://nutaan.com/api/voice/agents \
  -H "X-API-Key: nut-XXXX"

{
  "agents": [
    {
      "_id": "6a2d751adf5ec7876a0099e7",
      "name": "Support Agent",
      "stt": { "provider": "deepgram", "model": "nova-3", "language": "en-GB" },
      "tts": { "provider": "deepgram", "voiceName": "aura-asteria-en", "speed": 1 },
      "llm": { "provider": "openai", "model": "gpt-4.1", "temperature": 0.7, "maxTokens": 300 }
    }
  ]
}

curl -X POST https://nutaan.com/api/voice/agents \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "systemPrompt": "You are a friendly support agent for Acme. Keep replies under 2 sentences.",
    "languageMode": "multilingual",
    "voiceEngine": "azure-voicelive",
    "realtimeModel": "gpt-realtime",
    "realtimeVoice": "en-IN-NeerjaNeural",
    "llm": { "provider": "openai", "model": "gpt-4.1-nano" }
  }'

{
  "_id": "6a2d751adf5ec7876a0099e7",
  "name": "Support Agent",
  "voiceEngine": "azure-voicelive",
  "realtimeModel": "gpt-realtime",
  "realtimeVoice": "en-IN-NeerjaNeural",
  "llm": { "provider": "openai", "model": "gpt-4.1-nano" }
}

Agent templates

Ready-made, vertical-specific agent presets (real estate, healthcare, lending, e-commerce…). List them, inspect one, or create an agent from one by passing template_id — the template fills the prompt, welcome message, extraction fields, dispositions and voice preset for any value you leave blank (your own values always win). You can also generate a brand-new custom template from a plain-English brief.

curl https://nutaan.com/api/voice/agents/templates -H "X-API-Key: nut-XXXX"

{
  "categories": [ { "id": "real_estate", "label": "Real Estate" }, … ],
  "templates": [
    { "id": "realestate_sitevisit_in", "vertical": "real_estate",
      "label": "Real Estate — Site-Visit Booking (India)",
      "config": { "systemPrompt": "…", "welcomeMessage": "…",
                  "extractionFields": [ … ], "bookingEnabled": true } }
  ]
}

curl -X POST https://nutaan.com/api/voice/agents \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{ "template_id": "realestate_sitevisit_in",
        "name": "My Property Agent",
        "telephonyProvider": "plivo", "phoneNumberId": "+912269985921" }'

{ "_id": "6a…", "name": "My Property Agent", "systemPrompt": "…(from template)…" }

Call behaviour

These per-agent fields control how a call sounds, when the bot lets the caller interrupt, how it ends, and what happens afterwards. Set them on POST /voice/agents or PATCH /voice/agents/:id. They apply to every transport — phone calls and the browser widget.

When a call ends, your postCallWebhookUrl receives the transcript plus an outcome(completed | rejected | meeting_booked | no_response | natural_end) and, if postCallAnalysisis on, an analysis object (summary, disposition, sentiment,extractedData, suggestedFollowUp). Every call is also recorded two-sided (caller + AI) and the WAV appears as recordingUrl — nothing to configure.

curl -X PATCH https://nutaan.com/api/voice/agents/AGENT_ID \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{
    "interruptionMode": "words", "interruptionThreshold": 2,
    "autoEndOnGoodbye": true, "autoEndOnRejection": true,
    "bookingEnabled": true, "postCallAnalysis": true,
    "postCallWebhookUrl": "https://your-backend.com/api/call-ended"
  }'

Voice engines

The voiceEngine field on an agent decides how speech is produced — the single biggest lever on latency and language support. There are two families: a flexible pipeline(speech-to-text → LLM → text-to-speech, fully mix-and-match) and native speech-to-speech (S2S)engines that skip the middle steps for much lower latency.

Which should I use?

• Hindi, Hinglish or any Indian language → pipeline. It is the only family that handles them well. Pair it with TTS smallest (streams over WebSocket, first audio ~500ms) or sarvam.
• English, lowest latency & most natural → deepgram-agent (a.k.a. Turbo) — under 300ms speech-to-speech.
• English, cheapest low-latency → azure-voicelive (Voice Live) — sub-second speech-to-speech.

How to enable. Set voiceEngine on the agent (create or PATCH). A pipelineagent also takes stt and tts; the S2S engines take optional engine-specific fields (dgAgentSpeakModel/dgAgentThinkModel for Turbo, realtimeVoice/realtimeModelfor Voice Live) and otherwise use sensible defaults.

# Fastest English agent (sub-300ms speech-to-speech)
curl -X PATCH https://nutaan.com/api/voice/agents/AGENT_ID \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{ "voiceEngine": "deepgram-agent", "dgAgentSpeakModel": "aura-2-thalia-en" }'

# Hindi agent (pipeline + streaming Indian TTS)
curl -X PATCH https://nutaan.com/api/voice/agents/AGENT_ID \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{ "voiceEngine": "pipeline",
        "stt": { "provider": "azure", "language": "hi-IN" },
        "tts": { "provider": "smallest", "voiceName": "niharika", "language": "hi" } }'

The engine (and its fields) come back on the agent object:

{
  "_id": "6a2d751adf5ec7876a0099e7",
  "name": "English Sales — Turbo",
  "voiceEngine": "deepgram-agent",
  "dgAgentSpeakModel": "aura-2-thalia-en",
  "dgAgentThinkModel": "gpt-4o-mini"
}

Voices

List the available voices and providers to pick a voiceId for your agent, or preview one.

curl https://nutaan.com/api/voice/voices \
  -H "X-API-Key: nut-XXXX"

{
  "tts": {
    "deepgram": {
      "note": "English-only voices.",
      "voices": [
        {
          "id": "aura-asteria-en",
          "name": "Asteria",
          "language": "en-US",
          "gender": "female",
          "recommended": true,
          "description": "Friendly, conversational"
        }
      ]
    }
  }
}

Phone numbers

Search and buy a dedicated number so your AI can make and receive calls. Numbers are valid one month from purchase.

curl https://nutaan.com/api/voice/numbers -H "X-API-Key: nut-XXXX"

{ "numbers": [], "total": 0 }

curl -X POST https://nutaan.com/api/voice/numbers/buy \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{ "provider": "telnyx", "number": "+15551234567" }'

{
  "success": true,
  "number": "+15551234567",
  "sid": "PNxxxxxxxx",
  "valid_till": "13 July 2026"
}

Languages & voices

Every agent speaks one primary language, set differently depending on the engine (see the table above). Match the field to the engine: azure-voicelive takes a realtimeVoice(an Azure neural voice whose name starts with the language code, e.g. hi-IN-SwaraNeural);pipeline takes stt.language + tts.language; elevenlabs-agenttakes tts.voiceId (Hindi & English only).

Inbound calls (activate)

To have callers reach an agent when they dial its number, create or update the agent with activate_inbound: true and set phoneNumberId to a number you own. The rule is simple: the dialled number must equal the agent's phoneNumberId → that agent answers.

curl -X PATCH https://nutaan.com/api/voice/agents/AGENT_ID \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{ "telephonyProvider": "plivo", "phoneNumberId": "+912269985921", "activate_inbound": true }'

{
  "_id": "AGENT_ID",
  "inbound": { "provider": "plivo", "auto_configured": true, "number": "+912269985921" }
}

Send activate_inbound: false to turn it off — we unpin the number from the agent (so it stops answering there). Omit the field to leave inbound unchanged. Inbound isn't available on the free trial number (outbound-only). India transfers/bridging need a Plivo number.

Outbound calls

Place a single AI call. Give it an agentId and the destination number; the agent dials and converses.

curl -X POST https://nutaan.com/api/voice/calls/outbound \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{
    "agentId": "6a2d751adf5ec7876a0099e7",
    "to": "+15557654321",
    "from": "+15551234567"
  }'

{
  "callId": "43742d21-53b1-4599-9529-3cec00f5c2e1",
  "status": "queued",
  "agentId": "6a2d751adf5ec7876a0099e7",
  "to": "+15557654321"
}

Poll the returned callId for status, transcript and outcome:

curl https://nutaan.com/api/voice/calls/43742d21-... \
  -H "X-API-Key: nut-XXXX"

{
  "id": "6a2d87aedf5ec7876a009a22",
  "call_id": "43742d21-53b1-4599-9529-3cec00f5c2e1",
  "agent_id": "6a2d751adf5ec7876a0099e7",
  "direction": "outbound",
  "status": "completed",
  "from_number": "+15551234567",
  "to_number": "+15557654321",
  "duration": 170,
  "recording_url": "https://.../calls/43742d21-....wav",
  "has_recording": true,
  "booking": {
    "appointmentTime": "2026-07-31T20:00:00+05:30",
    "timezone": "Asia/Kolkata",
    "durationMinutes": 30,
    "notes": "Site visit — 2BHK"
  },
  "outcome": "booked",
  "analysis": { "sentiment": "positive", "disposition": "interested", "summary": "..." },
  "created_at": "2026-06-13T16:39:10.910Z",
  "started_at": "2026-06-13T16:39:10.910Z",
  "ended_at":   "2026-06-13T16:42:00.100Z",
  "transcript": [ { "role": "assistant", "text": "Hi! How can I help?" } ]
}

Call object — every field (returned by GET /voice/calls and GET /voice/calls/:id):

Batch calling

Run a campaign: one agent calls a list of contacts in parallel. Pass per-contact variables to personalise each conversation (name, order id, appointment time…).

curl -X POST https://nutaan.com/api/voice/batch \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{
    "name": "October reminders",
    "agentId": "6a2d751adf5ec7876a0099e7",
    "from": "+15551234567",
    "contacts": [
      { "name": "Asha", "number": "+15557654321", "variables": { "order": "A-1029" } },
      { "name": "Ravi", "number": "+15557654322", "variables": { "order": "A-1030" } }
    ]
  }'

{
  "_id": "6a2e01...batch",
  "name": "October reminders",
  "status": "queued",
  "total": 2,
  "completed": 0
}

SMS & DLT

Send SMS from your numbers and read message history. India (A2P) requires a DLT-registeredsender — register your Entity ID, Sender ID and Template once, verify it with a real test message, then send. The sender number must be SMS-enabled on the provider (voice-only numbers can’t send SMS). All endpoints are scoped to numbers/agents your key owns.

curl -X POST https://nutaan.com/api/voice/messages/dlt \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{
    "number": "912269985921",
    "provider": "plivo",
    "entityId": "1101359117054321987",
    "senderId": "TRBNPK",
    "templates": [{ "templateId": "1107167762198765432", "name": "site-visit",
                    "text": "Thanks {#var#}, your visit is booked for {#var#}." }]
  }'

{ "dlt": { "number": "912269985921", "status": "pending" },
  "note": "Saved. Call /messages/dlt/verify to confirm." }

curl -X POST https://nutaan.com/api/voice/messages/send \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{ "agentId": "6a51f...", "to": "919999999999", "text": "Hi from Nutaan!" }'

{ "messageId": "...", "status": "sent", "from": "912269985921", "to": "919999999999" }

India destinations automatically attach the sender’s stored dlt_entity_id / dlt_template_id; pass dltTemplateId to override. Inbound SMS is stored and forwarded to the agent’s post-call webhook as { type: "sms.received", … }.

Knowledge base

Give your AI your business content. Create a knowledge base from a website — it crawls and indexes automatically — and your agents and chat widget answer only from it, never inventing facts. Creating a KB also mints a widget_key you use to embed the chat widget.

curl -X POST https://nutaan.com/api/kb \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{ "website_url": "https://yoursite.com" }'

{
  "record_id": "6a55c45d161af636f39c0657",
  "namespace": "86714560-f4a1-4bd2-a6a2-d0e7c9b9e87f",
  "widget_key": "nutaan-09f51da3ca2f270e",
  "status": "processing"
}

curl -X POST https://nutaan.com/api/kb/test/query \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{ "kb_id": "6a55c45d...", "query": "What do you sell?" }'

{ "answer": "…grounded answer…", "sources": [ { "url": "…", "score": 0.82 } ] }

Chat widget

Embed the same Nutaan widget on any website with one script tag from our CDN — it is fully white-label: your branding, your knowledge, your keys. Or drive the entire live chat through the API and build your own UI. The CDN script is identical for every customer; your x-api-key and widget_keymake it yours.

Drop-in embed — paste before </body> on your site:

<script src="https://cdn.nutaan.com/chatbot-widget.js"
        x-api-key="nut-XXXX"
        Authorization="Bearer nutaan-XXXX"></script>

Or build your own chat UI with the widget API. Every widget endpoint takes two headers — your X-API-Key and Authorization: Bearer <widget_key>.

curl -X POST https://nutaan.com/api/widget/conversation \
  -H "X-API-Key: nut-XXXX" -H "Authorization: Bearer nutaan-XXXX" \
  -H "Content-Type: application/json" \
  -d '{ "visitor_id": "visitor-123" }'

{ "thread_id": "97b65c22-2af2-46d7-8cb1-01e1e2ab2edc", "is_new": true }

curl -X POST https://nutaan.com/api/widget/chat \
  -H "X-API-Key: nut-XXXX" -H "Authorization: Bearer nutaan-XXXX" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Do you ship to Mumbai?", "visitor_id": "visitor-123" }'

{
  "response": "Yes — we ship pan-India in 3–5 days.",
  "thread_id": "97b65c22-...",
  "context_used": 3,
  "intelligence": { "intent": "browse", "sentiment": "neutral" },
  "products": [],
  "needs_human": false
}

Widget branding & config

Manage the widget’s look and copy over the API — logo, colours, greeting, header title — so a white-label reseller can brand each client from code. Set it globally, or per knowledge base.

curl -X POST https://nutaan.com/api/preferences \
  -H "X-API-Key: nut-XXXX" -H "Content-Type: application/json" \
  -d '{
    "theme": { "primaryStart": "#111111", "primaryEnd": "#555555" },
    "texts": {
      "botName": "Keizer Assistant",
      "headerTitle": "How can we help?",
      "greetingText": "Hi! Ask us anything.",
      "profileLogoUrl": "https://yourcdn.com/logo.png",
      "showProfileLogo": true
    }
  }'

{ "success": true }

WhatsApp

Link a WhatsApp number by scanning a QR once. After that, post-call follow-ups, booking confirmations and reminders are delivered on WhatsApp automatically — the same built-in flow, no per-message calls. Configure exactly what sends via settings.

curl -X POST https://nutaan.com/api/integrations/whatsapp/connect \
  -H "X-API-Key: nut-XXXX"

{ "status": "qr", "qr": "data:image/png;base64,iVBORw0K…" }

Poll status until the QR is scanned, then send a test:

curl https://nutaan.com/api/integrations/whatsapp/status -H "X-API-Key: nut-XXXX"

{ "connected": true, "status": "connected", "phone": "9198…", "connected_at": "2026-07-14T…" }

Credits & balance

Your account runs on a single prepaid INR balance shared by the dashboard and the API. Every call minute and chat message draws it down. Check it any time with your API key:

curl https://nutaan.com/api/payment/balance \
  -H "X-API-Key: nut-XXXX"

{
  "balance": 900,
  "currency": "INR",
  "has_subscription": false,
  "pricing": { "call_per_minute": 6, "chat_per_message": 2 }
}

When the balance can’t cover an action, the API returns 402 with the current balance — top up and retry:

{ "error": "Insufficient credits. Calls cost ₹6/min — top up to continue.", "balance": 12 }

Low-balance alert. When your balance drops below ₹20, Nutaan automatically emails the account owner a top-up reminder — so a running integration never silently stops mid-campaign. Add credits from the dashboard (Payment); paid credits never expire. Poll /payment/balance before large batches, or watch for 402 and back off.

Errors, billing & performance

Every error returns a JSON body of the shape { "error": "message" } (some add context like balance). Use the HTTP status to branch:

Example — placing a call with no balance:

{ "error": "Insufficient credits. Calls cost ₹6/min — top up to continue.", "balance": 0 }

Billing is per account in INR: calls from ₹6/min, dropping to ₹4/minabove 1,000 minutes and as low as ₹3/min (~$0.036) above 5,000 minutes a month. A paid key with balance and a free key are billed identically — the only difference is the available balance. See pricing.

Performance & concurrency. Read endpoints (agents, voices, calls, batches) typically respond in ~0.3–0.9s. The API is concurrency-safe — parallel requests on the same key all succeed; under heavy fan-out, individual latency can rise to ~2s as calls proxy to the telephony layer. Call placement is asynchronous: /voice/calls/outbound returns immediately with a callId you poll, rather than blocking for the call. For campaigns, prefer a single /voice/batch over many individual calls — it parallelises and rate-paces for you.

Frequently asked questions