Vanira/Docs
v1.0

API Reference

v1.0

Multimodal voice AI for web and mobile: live audio, camera & screen vision, file uploads, and agent-driven UI presets — one WebRTC session, zero custom tool code for built-in presets.

Multimodal platform

One live call combines voice, vision (snapshot + streaming), and UI presets the agent drives.

Start in 2 minutes

Live voice demo

Try a live voice demo

Production demos with embedded Vanira voice agents — same sites shown in our , plus our on-site refund workflow at .

AgricultureKisan Support AgentKisan Seva KendraCrop damage on live camera, welfare intake, regional languages.EducationMaths Tutor AgentNumina Math TutoringWhiteboard-first tutoring — equations written before speech.Digital inclusionCitizen Services AgentClearTrip Travel (demo portal)Voice-guided navigation on a live website — type, click, confirm.

To test with your agent: open the dashboard, copy your pk_live_* key, and use the API Playground panel on the right — or paste it into a starter repo.

Template agents

Clone a pre-built agent into your account. Make your own agents public via Agent → Share to share with other developers.

Refund & Returns Agent

E-commerce
web

Live camera inspection, guided return UI, and multimodal refund confirmation.

Kisan Support Agent

Agriculture
react-native · web

Farmer-facing welfare intake — live camera, forms, regional languages.

Live demo

Maths Tutor Agent

Education
web

Board-first tutoring with screen share, camera, and upload.

Live demo

Citizen Services Agent

Citizen access
web

Voice-guided portal navigation — search, dates, and forms in regional language.

Live demo

Starter repos

vanira-starter-web

Vite + React + VaniraCallBox — voice pill and presets in minutes.

vanira-starter-rn

React Native + PresetHostProvider + createReactNativeAI.

About the SDK

#
The Vanira SDK adds multimodal voice AI to your product: live audio, camera/screen vision, file uploads, and UI presets the agent drives during a call.

What you get in one WebRTC session

LayerCapability
VoiceBidirectional audio, transcription, barge-in
VisionSnapshot upload + live camera + live screen share
UI presetsForms, calendar, navigate, click, upload, whiteboard, …
RoutingSPA navigation, page context sync, media reason tags
> Start here: — the three media flows, event routing, and preset routing map.

Two integration paths — pick one

PathWhen to use
Widget embedNo-code / marketing sites — paste a script tag, Vanira renders the UI
npm SDKDevelopers building React, Next.js, Vue, or vanilla apps with their own UI

npm integration surfaces

SurfaceImportWhat you get
VaniraCallBox@vanira/sdkVoice pill + presets + custom tool hook
Headless@vanira/sdk/headlessVaniraClient + PresetRenderer — you build the call UI

Build a Saathi-style tutor

Voice + chalkboard + LaTeX + camera on your website — dedicated guide: [/docs/saathi](/docs/saathi).

What you need

  • Agent ID from the dashboard
  • Publishable key pk_live_* for browser code (or token inside the Vanira dashboard)
  • No backend URL — the SDK uses Vanira's cloud API automatically

Read next (in order)

1. Multimodal Architecture — vision flows, events, routing
2. Widget — script-tag embed
3. SDK Installation — npm install @vanira/sdk
4. VaniraCallBox — drop-in React voice pill
5. Preset Handler — built-in UI tools (forms, calendar, navigate, live vision, …)
6. Upload Media (Vision) — snapshot photos & documents
7. Advanced Integration — DOM and server communication
8. Client-Side Events — lifecycle callbacks and session events

React Native

Mobile apps use a separate package — see React Native SDK section (starts with About the RN SDK). Same preset protocol; native modals for camera, upload, live vision.

Widget Embed

#
Use the widget embed when you want Vanira's full floating UI — chat, voice, presets — with zero npm install.
Copy the snippet from Agent → Widget → Embed in the dashboard:
Code examplehtml
1<script2  src="https://unpkg.com/@vanira/sdk@latest/dist/vanira-sdk.js"3  data-widget-id="YOUR_WIDGET_ID"4  data-pk-key="pk_live_YOUR_PUBLISHABLE_KEY"5  defer6></script>
The script bootstraps a <vanira-convai> custom element on document.body. It survives SPA route changes because it lives outside your React/Vue tree.

SPA navigation

If your agent uses the vanira_navigate preset, add a listener so in-app routing stays in-SPA.
  • *Framework apps (Next.js, Remix, etc.) cannot paste the script tag in `layout.tsx` alone — React will not run a global `vanira:navigate` listener for you. Mount the widget once from a client component** and register navigation with your framework router (useRouter in Next.js App Router). The widget custom element stays on document.body, so route changes do not tear down the call.
  • *Plain HTML / multi-page** — add once on your site:
Code examplejavascript
1// Add once on your site (same page as the Vanira widget).2// Required when your agent uses the vanira_navigate preset.3window.addEventListener('vanira:navigate', (event) => {4  const path = event.detail.path; // e.g. "/pricing" or "/docs#section"5 6  // Option A — multi-page site or simple fallback:7  window.location.assign(path);8 9  // Option B — SPA router (pick one that matches your stack):10  // router.push(path);              // React Router: useNavigate()11  // navigate(path);                 // Vue Router12  // router.push(path);              // Next.js App Router13 14  event.detail.handled = true; // required — tells the SDK navigation succeeded15});
  • *Next.js App Router** — mount the widget from a client component and wire useRouter:
Code exampletypescript
1// lib/vaniraConfig.ts2export const vaniraConfig = {3  scriptSrc: 'https://unpkg.com/@vanira/sdk@latest/dist/vanira-sdk.js',4  widgetId: process.env.NEXT_PUBLIC_VANIRA_WIDGET_ID ?? '',5  pkKey: process.env.NEXT_PUBLIC_VANIRA_PK_KEY ?? '',6};7 8export function isVaniraConfigured() {9  return Boolean(vaniraConfig.widgetId && vaniraConfig.pkKey);10}
Code exampletypescript
1"use client";2 3import { useEffect } from "react";4import { useRouter } from "next/navigation";5 6/** Listens for agent-led navigation while the widget stays mounted. */7export default function VaniraNavigateListener() {8  const router = useRouter();9 10  useEffect(() => {11    const onNavigate = (event: Event) => {12      const e = event as CustomEvent<{13        path?: string;14        url?: string;15        handled?: boolean;16      }>;17      const raw = e.detail?.path ?? e.detail?.url;18      if (!raw) return;19 20      try {21        const url = new URL(raw, window.location.origin);22        if (url.origin !== window.location.origin) return;23        router.push(`${url.pathname}${url.search}${url.hash}`);24      } catch {25        router.push(raw.startsWith("/") ? raw : `/${raw}`);26      }27 28      e.detail.handled = true;29      event.preventDefault?.();30    };31 32    window.addEventListener("vanira:navigate", onNavigate);33    return () => window.removeEventListener("vanira:navigate", onNavigate);34  }, [router]);35 36  return null;37}
Code exampletypescript
1"use client";2 3import { useEffect } from "react";4import { isVaniraConfigured, vaniraConfig } from "@/lib/vaniraConfig";5import VaniraNavigateListener from "./VaniraNavigateListener";6 7export default function VaniraWidget() {8  useEffect(() => {9    if (!isVaniraConfigured()) {10      console.warn("[Vanira] Missing NEXT_PUBLIC_VANIRA_WIDGET_ID or NEXT_PUBLIC_VANIRA_PK_KEY");11      return;12    }13 14    if (document.querySelector("vanira-convai")) return;15    if (document.querySelector("script[data-vanira-embed]")) return;16 17    const script = document.createElement("script");18    script.src = vaniraConfig.scriptSrc;19    script.defer = true;20    script.setAttribute("widget-id", vaniraConfig.widgetId);21    script.setAttribute("pk-key", vaniraConfig.pkKey);22    script.setAttribute("data-pk-key", vaniraConfig.pkKey);23    script.dataset.vaniraEmbed = "true";24    document.body.appendChild(script);25  }, []);26 27  return <VaniraNavigateListener />;28}
Code exampletypescript
1// app/layout.tsx — mount once at the root2import VaniraWidget from "@/components/VaniraWidget";3 4export default function RootLayout({ children }: { children: React.ReactNode }) {5  return (6    <html lang="en">7      <body>8        {children}9        <VaniraWidget />10      </body>11    </html>12  );13}
When the agent calls vanira_navigate, the SDK dispatches a browser event instead of forcing a full page reload:
TargetSDK behavior
Same-origin path (e.g. /pricing, /docs#faq)Fires vanira:navigate with detail.path — your site must handle it
External URL (different origin)Opens in a new tab automatically — no listener needed
  • *SPA sites (React, Vue, Next.js, etc.) must register a vanira:navigate listener** that routes with your framework and sets event.detail.handled = true. Without it, same-origin navigation fails with status: cancelled and the console shows: No SPA listener handled vanira:navigate.
  • *Framework apps (Next.js, Remix, etc.) cannot paste the script tag in `layout.tsx` alone — React will not run a global `vanira:navigate` listener for you. Mount the widget once from a client component** and register navigation with your framework router (useRouter in Next.js App Router). The widget custom element stays on document.body, so route changes do not tear down the call.
  • *Blocking tool:** the AI pauses until the SDK sends client_tool_result. Success payload: { status: 'success', navigated_to, target_url }. Server interrupt (clearAudio / client_tool_cancel): { status: 'interrupted', reason, target_url }.
  • *Multi-page sites** can use window.location.assign(event.detail.path) in the listener, or the same pattern as a fallback.

When to use npm instead

Choose VaniraCallBox or headless `VaniraClient` when you need your own call button, layout, or styling — not Vanira's floating widget chrome.

Powered by Vanira

Free-tier widget chat shows "Technology Powered by Vanira AI" in the UI — a discovery path for other developers. Paid plans can request branding removal.

SDK Installation

#
Install @vanira/sdk when you want VaniraCallBox or a headless integration with your own UI.
Code examplebash
1npm install @vanira/sdk2# or3yarn add @vanira/sdk

Imports

Use caseImport
Drop-in voice pillimport { VaniraCallBox } from '@vanira/sdk'
Your own call UIimport { VaniraClient, PresetRenderer } from '@vanira/sdk/headless'
Low-level (same class)import { VaniraClient } from '@vanira/sdk'

Requirements

  • Agent ID + publishable key pk_live_*
  • HTTPS in production (microphone access)
  • Start calls from a user click on mobile browsers
> For a no-build script-tag embed, see Widget Embed — no npm install needed.

API Keys & Configuration

#

API keys

KeyWhereUse
pk_live_*Browser, widget embed, VaniraCallBoxWeb calls only — safe for frontend
sk_live_*Your backend onlyFull API access — never expose in browser code
Pass apiKey: 'pk_live_…' in browser integrations. The SDK provisions the call and opens WebRTC — no backend URL, no manual REST calls.
For the script-tag widget, use data-pk-key. Inside the Vanira dashboard, VaniraCallBox can use token (Bearer JWT) instead of apiKey.

VaniraCallBox props

PropRequiredDescription
agentIdYesAgent UUID from dashboard
apiKeyYes*pk_live_* for external sites
tokenYes*Dashboard Bearer JWT (*one of apiKey or token)
onNavigateRecommendedSPA router hook for vanira_navigate preset
onCustomToolAs neededHandler for custom client tools (not presets)
sessionBehaviorNo'new' (default) or 'continue'
autoStartNoDefault false — tap-to-talk
onMinimize / onCloseNoHost UI callbacks

VaniraClient props

PropRequiredDescription
agentIdYesAgent UUID
apiKey or tokenYes*Auth (*unless serverUrl + callId + iceServers pre-supplied)
sessionBehaviorNo'new' or 'continue'
prospectId / callIdNoManual session resume
trackRouteContextNoDefault true — auto page-route context sync
onConnected / onDisconnected / onErrorRecommendedLifecycle callbacks
onClientToolCallAs neededAll client tool calls (presets + custom)
onTranscriptionNoUser speech-to-text stream
Use constructor callbacks or .on(event) + start() — same class, two styles.

Example

Code exampletypescript
1// Browser2const client = new VaniraClient({3  agentId: 'YOUR_AGENT_ID',4  apiKey: 'pk_live_<uuid>',5  onConnected: () => setStatus('connected'),6});7await client.connect();

VaniraCallBox

#
VaniraCallBox is the fastest npm integration — voice pill, presets, and a hook for custom tools.
Only agentId + apiKey required. Mount above your router so SPA navigation does not tear down the call.
Code exampletypescript
1import { VaniraCallBox } from '@vanira/sdk';2import { useRouter } from 'next/navigation';3 4function AppShell() {5  const router = useRouter();6 7  return (8    <>9      <YourRoutes />10      <VaniraCallBox11        agentId={process.env.NEXT_PUBLIC_VANIRA_AGENT_ID}12        apiKey={process.env.NEXT_PUBLIC_VANIRA_PK_KEY}13        onNavigate={(path) => router.push(path)}14        onCustomTool={(call, client) => {15          if (call.name === 'say_hi') {16            showGreetingPopup();17            if (call.execution_mode !== 'fire_and_forget') {18              client.sendToolResult(call.tool_call_id, { status: 'success' });19            }20          }21        }}22      />23    </>24  );25}

Rules

  • Presets (form, calendar, navigate, …) — automatic, no code
  • Custom tools — implement in onCustomTool only
  • Do not mount inside a single page behind {showCall && …} on multi-route SPAs

Custom call button (optional)

Code exampletypescript
1<VaniraCallBox agentId="..." apiKey="...">2  {({ status, startCall, endCall }) =>3    status === 'connected'4      ? <button onClick={endCall}>Hang up</button>5      : <button onClick={startCall}>Talk to us</button>6  }7</VaniraCallBox>

Build Your Own UI

#
Use the headless path when you want full control over buttons, layout, and status UI.
Import from @vanira/sdk/headless:
Code exampletypescript
1import { useRef } from 'react';2import {3  VaniraClient,4  PresetRenderer,5  type PresetRendererHandle,6} from '@vanira/sdk/headless';7 8const presetRef = useRef<PresetRendererHandle>(null);9let client: VaniraClient | null = null;10 11async function startCall() {12  client = new VaniraClient({13    agentId: 'YOUR_AGENT_ID',14    apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY',15    onConnected: () => setStatus('connected'),16    onDisconnected: () => setStatus('idle'),17    onClientToolCall: (raw) => presetRef.current?.enqueueToolCall(raw),18  });19  await client.connect();20}
Code exampletypescript
1<PresetRenderer ref={presetRef} client={client} onCustomTool={handleCustomTool} />

Callbacks or events

Code exampletypescript
1// Style A — constructor callbacks + connect()2await client.connect();3 4// Style B — .on() listeners + start()5client.on('connected', () => setStatus('connected'));6client.on('tool_call', (tc) => presetRef.current?.enqueueToolCall(tc));7await client.start();
Start from a button click. Show live UI on onConnected / connected — not on onSessionStarted (provisioning only).

Preset Handler

#
  • *Presets** are built-in client tools the SDK renders automatically — forms, calendars, uploads, navigation, DOM actions, and more.
With VaniraCallBox, presets work with zero code. With headless VaniraClient, mount PresetRenderer and enqueue tool calls via presetRef.enqueueToolCall() or onClientToolCall.
  • *Dashboard: Agent → Tools → Create tool → Client → pick a preset tile. Full `POST /tools` bodies are in the Tools → Preset Tools** doc.
Preset IDUIMode
vanira_formData Collection Formblocking
vanira_phoneMobile numberblocking
vanira_mcqMultiple Choice Questionblocking
vanira_calendarDate & Time Pickerblocking
vanira_uploadFile Uploadblocking
vanira_cameraCamera Capturefire_and_forget
vanira_navigateNavigate to Route — requires vanira:navigate listener on SPAsblocking
vanira_highlight_elementHighlight Elementblocking
vanira_click_elementClick Elementblocking
vanira_select_optionSelect Dropdown Optionblocking
vanira_set_dateSet Date Fieldblocking
vanira_type_textDOM Typing Simulationblocking
vanira_write_latex_textChalkboard LaTeX Writerblocking
vanira_erase_textWhiteboard / DOM Eraseblocking
vanira_live_visionLive Vision (Streaming Camera)fire_and_forget
vanira_close_live_cameraStop Live Camerablocking
vanira_live_screenLive Screen Sharefire_and_forget
vanira_close_live_screenStop Live Screen Shareblocking
vanira_clip_regionPage Region Clipblocking
vanira_screen_visionScreen Visionblocking
vanira_point_atPoint At Screenblocking
vanira_draw_on_screenDraw On Screenblocking
vanira_clear_screen_drawClear Screen Drawingsblocking
vanira_highlight_on_screenHighlight On Screenblocking
vanira_kyc_document_captureKYC Document Captureblocking
vanira_kyc_selfie_captureKYC Selfie Captureblocking
vanira_kyc_signature_captureKYC Signature Captureblocking
  • *Blocking presets (most): the AI waits until the SDK calls `sendToolResult()`. fire_and_forget**: vanira_camera, vanira_live_vision.
Unknown tool calls (no matching preset) go to onCustomTool.

Navigate preset — host-site setup

When the agent calls vanira_navigate, the SDK dispatches a browser event instead of forcing a full page reload:
TargetSDK behavior
Same-origin path (e.g. /pricing, /docs#faq)Fires vanira:navigate with detail.path — your site must handle it
External URL (different origin)Opens in a new tab automatically — no listener needed
  • *SPA sites (React, Vue, Next.js, etc.) must register a vanira:navigate listener** that routes with your framework and sets event.detail.handled = true. Without it, same-origin navigation fails with status: cancelled and the console shows: No SPA listener handled vanira:navigate.
  • *Framework apps (Next.js, Remix, etc.) cannot paste the script tag in `layout.tsx` alone — React will not run a global `vanira:navigate` listener for you. Mount the widget once from a client component** and register navigation with your framework router (useRouter in Next.js App Router). The widget custom element stays on document.body, so route changes do not tear down the call.
  • *Blocking tool:** the AI pauses until the SDK sends client_tool_result. Success payload: { status: 'success', navigated_to, target_url }. Server interrupt (clearAudio / client_tool_cancel): { status: 'interrupted', reason, target_url }.
  • *Multi-page sites** can use window.location.assign(event.detail.path) in the listener, or the same pattern as a fallback.

DOM presets — route field

For vanira_click_element, vanira_select_option, vanira_set_date, vanira_type_text, and vanira_erase_text, set client_fields.route to the SPA path where the target element lives (e.g. /checkout). If the user is on a different page, the SDK dispatches vanira:navigate first, waits for the route (and element when possible), then clicks/types/erases. Requires the same vanira:navigate listener as the Navigate preset on SPA sites.
> API bodies: see Tools → Preset Tools for copy-paste POST /tools JSON for every preset.

React Integration Example

Code exampletypescript
1import { useEffect, useState } from 'react';2import { VaniraClient, PresetRenderer } from '@vanira/sdk';3 4function App() {5  const [client] = useState(() => new VaniraClient({6    agentId: 'YOUR_AGENT_ID',7    apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY'8  }));9  const [activeToolCall, setActiveToolCall] = useState(null);10 11  useEffect(() => {12    client.on('tool_call', (toolCall) => {13      setActiveToolCall(toolCall);14    });15    16    client.start();17    return () => client.stop();18  }, [client]);19 20  return (21    <div>22      <MainDashboard />23 24      {/* Mount the PresetRenderer to automatically handle forms, calendars, etc. */}25      {activeToolCall && (26        <PresetRenderer27          client={client}28          toolCall={activeToolCall}29          onCustomTool={(toolCall) => {30            console.log('Handle your custom tool:', toolCall.name);31          }}32        />33      )}34    </div>35  );36}

Custom Tool Handler

#
Custom client tools are actions you implement in app code — popups, navigation side-effects, API calls from the browser. They are not SDK presets (form, calendar, navigate, etc.).
Create them in the dashboard: Agent → Tools → New tool → Client → Custom.

Two data layers (do not confuse them)

LayerDashboard sectionWho fills itWhere it lands in code
1. Agent parameters*Agent parameters*The AI extracts from the conversationTool schema only — tells the AI what to collect
2. Frontend payload*Frontend payload*You map keys → {{param}} or static valuescall.arguments in onCustomTool
  • *Agent parameters** define the conversation contract (e.g. customer_name, order_id).
  • *Frontend payload** (client_fields in the API) defines what your app receives. Use {{param_name}} for dynamic agent values or plain strings for static fields.

Dashboard example

  • *Agent parameters**
  • customer_name (string, required) — "Person's name from the conversation"
  • *Frontend payload**
Payload keyValue
name{{customer_name}}
sourcewebsite
  • *At runtime** your handler receives:
Code examplejson
1{2  "name": "Teja",3  "source": "website"4}
If you omit custom payload rows, each agent parameter is auto-mapped to the same key in call.arguments.

Execution mode

Set in the dashboard when creating the tool:
ModeAI behaviorYour code
blockingPauses until sendToolResult()Must call client.sendToolResult(tool_call_id, result)
fire_and_forgetKeeps speakingNo result required

VaniraCallBox handler

Code exampletypescript
1<VaniraCallBox2  agentId="YOUR_AGENT_ID"3  apiKey="pk_live_YOUR_PUBLISHABLE_KEY"4  onCustomTool={(call, client) => {5    const { name, arguments: args, tool_call_id, execution_mode } = call;6 7    if (name === 'greet_user') {8      openGreetingModal(args.name); // args.name from frontend payload mapping9 10      if (execution_mode !== 'fire_and_forget' && tool_call_id) {11        client.sendToolResult(tool_call_id, {12          status: 'success',13          message: 'Greeting shown',14        });15      }16    }17  }}18/>

API equivalent (POST /tools)

Code examplejson
1{2  "name": "greet_user",3  "description": "Show a personalized greeting popup when the user says hello",4  "type": "client",5  "execution_mode": "blocking",6  "channels": ["voice_web"],7  "parameters": [8    {9      "name": "customer_name",10      "type": "string",11      "description": "The person's name from the conversation",12      "required": true13    }14  ],15  "client_fields": {16    "name": "{{customer_name}}",17    "source": "website"18  }19}
Presets use client_fields.preset_id — handled automatically by PresetRenderer, not onCustomTool.

Tool call payload

FieldDescription
nameTool name or ref_code
argumentsResolved frontend payload your app reads
tool_call_idID for sendToolResult() / sendToolError()
execution_modeblocking or fire_and_forget
The SDK auto-sends client_tool_ack within ~2.3s — you do not ack manually.

On error or cancel

For blocking tools, call sendToolError(tool_call_id, message) when the operation fails so the agent can recover:
Code exampletypescript
1try {2  await bookSlot(args.date);3  client.sendToolResult(tool_call_id, { status: 'success' });4} catch (e) {5  client.sendToolError(tool_call_id, e.message || 'Booking failed');6}

Client-Side Events

#
  • *Client-side events** are callbacks the SDK fires in your browser — connection lifecycle, transcription, tool calls, and media tracks.
Use constructor callbacks (onConnected, …) or .on('connected', …) + start() — same events either way.
Event / callbackWhen it fires
onSessionStarted / session_startedSession provisioned — not live yet
onConnected / connectedWebRTC live — show your "connected" UI here
onDisconnected / disconnectedCall ended
onError / errorConnection or permission failure
onTranscription / transcriptionUser speech-to-text (isFinal flag)
onLocalStreamMicrophone stream ready
onRemoteTrackAgent audio/video track arrives
onClientToolCall / tool_callAI requested a browser action
> Common mistake: Showing "connected" on onSessionStarted. Wait for onConnected.

VaniraClient Example

Code exampletypescript
1const client = new VaniraClient({2  agentId: 'YOUR_AGENT_ID',3  apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY',4 5  onSessionStarted: ({ prospectId, callId, serverUrl }) => {6    // Phase 1 — provisioned, still connecting to worker7    console.log('Provisioned:', { prospectId, callId, serverUrl });8    setStatus('connecting');9  },10 11  onConnected: () => {12    // Phase 2 — live (Talk to Agent connected state)13    setStatus('connected');14  },15 16  onDisconnected: () => setStatus('idle'),17 18  onError: (error) => {19    console.error('Connection error:', error);20    setStatus('error');21  },22 23  onTranscription: (text, isFinal) => {24    // isFinal = true means committed utterance.25    setTranscript(text);26  },27 28  onLocalStream: (stream) => {29    localAudioDebugRef.current.srcObject = stream;30  },31 32  onRemoteTrack: (track, stream) => {33    if (track.kind === 'audio') {34      audioElement.srcObject = stream;35      audioElement.play();36    }37  },38 39  onClientToolCall: (toolCall) => {40    // See "Client Tool Calls" section for full usage41    console.log('AI wants to:', toolCall.name, toolCall.arguments);42  }43});

Session Continuity

#
### Why Session Continuity?
WebRTC connections end when a page refreshes or a component unmounts. Session continuity lets you reconnect with the same user identity and conversation context instead of creating a completely unrelated call.
The SDK stores prospectId and callId in browser storage after a call starts. With sessionBehavior: 'continue', the next connect() reuses that context.

Storage Keys

KeyMeaning
vanira_prospect_idThe user/prospect identity used across chat and voice
vanira_latest_call_idThe latest web-call session ID
Both keys are written to sessionStorage and localStorage when the SDK creates a call.

Configuration Reference

  • sessionBehavior: 'new': start a fresh call. This is the default.
  • sessionBehavior: 'continue': reuse stored or explicitly supplied prospectId and callId.
  • prospectId: pass this when you want to bind the call to your own user/contact record.
  • callId: pass this if your app stores and restores call sessions manually.
  • onSessionStarted: use this callback to persist or display the resolved prospectId, callId, and serverUrl.

React Integration Example

Below is a complete, production-ready React component handling WebRTC initialization, session continuation, and cleaning up state on component unmount.
Code exampletypescript
1import React, { useEffect, useState, useRef } from 'react';2import { VaniraClient } from '@vanira/sdk';3 4export function VoiceCallWidget() {5  const [status, setStatus] = useState<'idle' | 'connecting' | 'connected' | 'disconnected'>('idle');6  const [sessionInfo, setSessionInfo] = useState<{ callId: string; prospectId: string } | null>(null);7  const clientRef = useRef<VaniraClient | null>(null);8 9  const startCall = async () => {10    setStatus('connecting');11    12    clientRef.current = new VaniraClient({13      agentId: 'YOUR_AGENT_ID',14      apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY', // Browser-safe publishable key15      sessionBehavior: 'continue',           // Attempt to continue session on page load/refresh16      17      onSessionStarted: ({ callId, prospectId }) => {18        setSessionInfo({ callId, prospectId });19        console.log('Provisioned (Phase 1):', { callId, prospectId });20      },21      onConnected: () => {22        setStatus('connected');23      },24      onDisconnected: () => {25        setStatus('disconnected');26        setSessionInfo(null);27      },28      onError: (err) => {29        console.error('Call Error:', err);30        setStatus('idle');31      }32    });33 34    try {35      await clientRef.current.connect();36    } catch (e) {37      console.error('Failed to start call', e);38      setStatus('idle');39    }40  };41 42  const endCall = () => {43    if (clientRef.current) {44      clientRef.current.disconnect();45      clientRef.current = null;46    }47    setStatus('idle');48  };49 50  // Safe cleanup when component unmounts51  useEffect(() => {52    return () => {53      if (clientRef.current) {54        clientRef.current.disconnect();55      }56    };57  }, []);58 59  return (60    <div className="p-4 border rounded-lg bg-zinc-900 text-white">61      <p>Status: {status}</p>62      {sessionInfo && (63        <p className="text-xs text-zinc-400">Call ID: {sessionInfo.callId}</p>64      )}65      {status === 'connected' ? (66        <button onClick={endCall} className="bg-red-500 px-4 py-2 rounded">End Call</button>67      ) : (68        <button onClick={startCall} disabled={status === 'connecting'} className="bg-emerald-500 px-4 py-2 rounded">69          {status === 'connecting' ? 'Connecting...' : 'Start / Resume Call'}70        </button>71      )}72    </div>73  );74}

Advanced Integration

#
For advanced documentation regarding DOM state synchronization, live client context tracking, and custom WebRTC server-side communication triggers, please contact the Vanira engineering team directly.

Interrupt Audio Only

#

Interrupt Audio Only

Use this capability when you want to immediately cut off the AI agent's active speech *without* sending a client action event trigger.
This is extremely useful when the user is about to take an action where the SDK or another flow will notify the agent automatically (such as performing a media upload or triggering a system-level transfer), and you want to prevent the agent from talking over the user or creating double response loops.
Call interruptAudioOnly() for an audio-only interrupt.

Code Example

Code exampletypescript
1// Cut current agent audio output immediately2client.interruptAudioOnly();

Ending a Call

#
End the live session when the user hangs up, closes your call UI, or navigates away.
Call disconnect() or stop() — both release the microphone, close the data channel, close the peer connection, and emit a disconnected event.

Code Example

Code exampletypescript
1client.disconnect();2client = null;3 4// React cleanup5useEffect(() => {6  return () => {7    clientRef.current?.disconnect();8    clientRef.current = null;9  };10}, []);

Error Handling

#
Most SDK failures happen before the call is fully connected: invalid keys, blocked microphone permission, missing serverUrl, failed /calls/create (Phase 1), or WebRTC/ICE failure reaching the worker (Phase 2).
If you only see POST /calls/create in the network tab, Phase 1 succeeded but Phase 2 did not — check onError, microphone permission, and worker POST …/webrtc responses.
Always implement onError and treat it as a user-facing state. Also clean up the client when a connection attempt fails so the next retry starts from a fresh peer connection.

Common Errors

SymptomLikely causeWhat to do
Only POST /calls/create in network tabPhase 2 failed (mic, worker SDP, ICE)Check onError; call connect() from button click; allow microphone
onSessionStarted fires but never onConnectedStuck in Phase 2Check worker /webrtc POST response and ICE; see console [WebRTC] logs
serverUrl is missingNo apiKey and no manual worker URLPass apiKey, or pass serverUrl and callId from your backend
createCall failed (401/403)Invalid key, wrong scope, or origin mismatchCheck key type and origin setting
Microphone permission deniedBrowser blocked mic accessStart from a user click and show permission guidance
DataChannel not openSending too early or after disconnectWait for onConnected before calling context/actions/uploads
Audio autoplay blockedBrowser policyStart calls from a user gesture and keep audio element playback user-initiated

Retry Pattern

Code exampletypescript
1import { VaniraClient } from '@vanira/sdk';2 3let client: VaniraClient | null = null;4 5async function startCall() {6  client?.disconnect();7 8  client = new VaniraClient({9    agentId: 'YOUR_AGENT_ID',10    apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY',11    onConnected: () => setStatus('connected'),12    onDisconnected: () => setStatus('idle'),13    onError: (error) => {14      console.error('Vanira call failed:', error);15      setStatus('error');16      client?.disconnect();17      client = null;18    },19  });20 21  setStatus('connecting');22  await client.connect();23}

Best Practices

  • Disable your "Start call" button while status is connecting or connected.
  • Call disconnect() or stop() during React unmount.
  • Do not call connect() twice on the same client.
  • Do not call context, action, or upload methods before the connection is open.
  • Keep sk_live_* keys out of browser code.

Preset Session Continuity

#
### Why Preset Session Continuity?
Voice session continuity restores the call identity, but a browser refresh still clears React component state. If a form, calendar, or upload dialog is active when the page refreshes, store the active tool-call payload yourself and restore it on mount.
This pattern stores the latest preset tool call in sessionStorage. It restores the dialog shell after reload; for fully restoring half-filled form inputs, store those form values separately in your app state.

React Continuity Implementation

Use this alongside sessionBehavior: 'continue' for the voice session.
Code exampletypescript
1import { useEffect, useState } from 'react';2import { VaniraClient, PresetRenderer } from '@vanira/sdk';3 4function App() {5  const [client] = useState(() => new VaniraClient({ 6    agentId: 'YOUR_AGENT_ID',7    apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY',8    sessionBehavior: 'continue'9  }));10 11  // 1. Initialize activeToolCall from sessionStorage if it exists12  const [activeToolCall, setActiveToolCall] = useState(() => {13    const saved = sessionStorage.getItem('vanira_active_preset');14    return saved ? JSON.parse(saved) : null;15  });16 17  useEffect(() => {18    client.on('tool_call', (toolCall) => {19      // 2. Cache the active tool call in sessionStorage20      sessionStorage.setItem('vanira_active_preset', JSON.stringify(toolCall));21      setActiveToolCall(toolCall);22    });23    24    client.start();25    return () => client.stop();26  }, [client]);27 28  const clearPreset = () => {29    // 3. Clear when your flow is complete, or when the user dismisses your restored UI30    sessionStorage.removeItem('vanira_active_preset');31    setActiveToolCall(null);32  };33 34  return (35    <div>36      <MainDashboard />37 38      {activeToolCall && (39        <button onClick={clearPreset}>Clear restored preset</button>40      )}41 42      {activeToolCall && (43        <PresetRenderer44          client={client}45          toolCall={activeToolCall}46        />47      )}48    </div>49  );50}

Agent & Human Transfers

#
Vanira supports two common handoff patterns for live conversations.
### 1. Human Transfer (SIP Referral)
In telephony calls, the Human Transfer tool triggers a standard SIP REFER to your configured fallback number. The AI agent immediately disconnects once the transfer is initiated.
### 2. Agent Transfer (Context Switch)
Switch the user to a different AI agent without ending the session. This is perfect for multi-stage workflows (e.g., qualifying a lead with one agent, then switching to a "Closing" agent).
For web calls, the old WebRTC session should be treated as ended. When onDisconnected fires, create a new VaniraClient with the next agent ID returned by your transfer flow and call connect() again.

Upload Media (Vision)

#

Snapshot upload (one photo / document)

During an active voice call, users can upload an image or PDF with client.uploadMedia(). The SDK uploads via WebRTC media-bytes (web) or HTTP fallback, then sends client_media_update so the agent runs process_media.
> This is not live camera or screen share. For streaming frames see Multimodal Architecture and Preset: Live Vision.
Do not send a separate action trigger after upload. The media update is the notification the backend expects.

Parameters

ArgumentTypeRequiredDescription
file`FileBlob`YesThe file object to upload. Supported by the high-level SDK: JPEG, PNG, GIF, WEBP, BMP, and PDF up to 50 MB.
reasonstringYesCategory tag (e.g. 'kyc_document', 'error_screenshot'). Tells your backend webhook how to process this upload.
messagestringNoOptional text question or message to accompany the file (e.g. "What does this line item mean?").
interruptFirstbooleanNoAvailable on VaniraClient.uploadMedia(). Cuts current audio before upload without sending a duplicate action trigger.

React File Upload Example

Here is how to implement a drag-and-drop or file input upload element during an active voice session:
Code exampletypescript
1import React, { useRef, useState } from 'react';2import { VaniraClient } from '@vanira/sdk';3 4interface UploadProps {5  client: VaniraClient | null;6}7 8export function VisionUploadButton({ client }: UploadProps) {9  const [isUploading, setIsUploading] = useState(false);10  const fileInputRef = useRef<HTMLInputElement>(null);11 12  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {13    const file = e.target.files?.[0];14    if (!file || !client) return;15 16    try {17      setIsUploading(true);18      19      // Upload the document and let the media pipeline notify the AI.20      const response = await client.uploadMedia(21        file,22        'kyc_verification', // Routing reason23        'Please review this document and tell me if my name matches.' // Message context24      );25      26      console.log('Media uploaded successfully:', response.url);27    } catch (error) {28      console.error('Failed to upload vision context:', error);29    } finally {30      setIsUploading(false);31      if (fileInputRef.current) fileInputRef.current.value = ''; // Reset input32    }33  };34 35  return (36    <div className="flex items-center gap-2">37      <input38        type="file"39        ref={fileInputRef}40        onChange={handleFileChange}41        accept="image/*,application/pdf"42        className="hidden"43      />44      <button45        disabled={isUploading || !client}46        onClick={() => fileInputRef.current?.click()}47        className="px-4 py-2 text-sm bg-white text-black font-semibold rounded-lg hover:bg-zinc-200 disabled:opacity-50 disabled:cursor-not-allowed"48      >49        {isUploading ? 'Uploading...' : 'Upload Image / PDF'}50      </button>51    </div>52  );53}

Body Parameters

fileREQUIRED
string

The image or document to upload (JPEG, PNG, GIF, WEBP, BMP, PDF).

reasonREQUIRED
string

The routing category configured in the Dashboard (e.g. kyc_photo, general).

message
string

Optional text context to send alongside the image.

About the RN SDK

#
The React Native SDK adds live AI voice, interactive presets, and client tools to iOS and Android apps.
> Web apps use `@vanira/sdk`. This package is React Native only — do not import the web SDK in mobile apps.

Package

npm@vanira/sdk-react-native
Importimport { createReactNativeAI, PresetHostProvider } from '@vanira/sdk-react-native'

What you get

  • Voice calls over WebRTC (createReactNativeAI)
  • Built-in preset UI — forms, calendar, upload, camera, navigation, live vision
  • Same agent protocol as web (client_tool_call, uploadMedia, session continuity)

What you need

  • Agent ID from the dashboard
  • Publishable key pk_live_* in app code
  • Native modules for WebRTC (see RN Installation and Native Setup)

Read next (in order)

1. RN Installation — npm install @vanira/sdk-react-native
2. Native Setup — WebRTC globals, permissions, peer deps
3. Quick Start — PresetHostProvider + createReactNativeAI
4. Preset Handler (RN) — route tool calls with setActiveToolCall()
5. RN Events — lifecycle callbacks
6. Session Continuity (RN) — resume calls with AsyncStorage

RN Installation

#
Install the SDK package first:
Code examplebash
1npm install @vanira/sdk-react-native
Native modules are peer dependencies — your app installs them separately (the SDK does not bundle them). npm may show peer warnings until you add the modules you need.

Voice calls (required)

Code examplebash
1npm install react-native-webrtc react-native-incall-manager react-native-permissions2cd ios && pod install
Then add registerGlobals() in index.js — see Native Setup.

Presets (install only what you use)

FeaturePackages
Upload / camerareact-native-image-picker, @react-native-documents/picker
Screenshot / clip regionreact-native-view-shot
Live visionreact-native-vision-camera
Calendar, form, and navigate presets need no extra native packages.
> Full permission and Podfile steps are in Native Setup.

Native Setup

#

1. WebRTC globals (required)

Call registerGlobals() once in index.js before any SDK import:
Code examplejavascript
1import {AppRegistry} from 'react-native';2import {registerGlobals} from 'react-native-webrtc';3 4registerGlobals();5 6import App from './App';7import {name as appName} from './app.json';8 9AppRegistry.registerComponent(appName, () => App);
Without this, WebRTC APIs (RTCPeerConnection, getUserMedia) are undefined and calls fail.

2. iOS permissions

In ios/Podfile:
Code exampleruby
1require_relative '../node_modules/react-native-permissions/scripts/setup'2 3setup_permissions([4  'Camera',5  'Microphone',6  'PhotoLibrary',7])
Code examplebash
1cd ios && pod install
Add usage strings to Info.plist (NSMicrophoneUsageDescription, NSCameraUsageDescription, NSPhotoLibraryUsageDescription).

3. Android permissions

In AndroidManifest.xml:
Code examplehtml
1<uses-permission android:name="android.permission.RECORD_AUDIO" />2<uses-permission android:name="android.permission.CAMERA" />3<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />

4. Metro (if resolution fails)

Code examplejavascript
1const path = require('path');2const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');3 4module.exports = mergeConfig(getDefaultConfig(__dirname), {5  resolver: {unstable_enablePackageExports: true},6  watchFolders: [7    path.resolve(__dirname, 'node_modules/@vanira/sdk-react-native'),8  ],9});

VaniraCallBox

#
  • *Recommended** — same idea as web VaniraCallBox: voice pill + preset modals in one component.
Code exampletypescript
1import {VaniraCallBox} from '@vanira/sdk-react-native';2 3export default function App() {4  return (5    <VaniraCallBox6      agentId="YOUR_AGENT_ID"7      apiKey="pk_live_YOUR_PUBLISHABLE_KEY"8      backendUrl="https://api.vanira.io"9      title="Voice chat">10      <HomeScreen />11    </VaniraCallBox>12  );13}
  • Wraps PresetHostProvider + call lifecycle — presets open automatically
  • Default floating pill at the bottom (mute, hang up, wave bars)
  • Custom UI via renderCallUI={(props) => ...}
  • onNavigate wires React Navigation for vanira_navigate presets

Headless SDK

#
Programmatic integration — no default pill chrome. Mirrors @vanira/sdk/headless.
Code exampletypescript
1import {2  PresetHostProvider,3  VaniraCallProvider,4  useVaniraCall,5} from '@vanira/sdk-react-native/headless';6 7function App() {8  return (9    <PresetHostProvider>10      <VaniraCallProvider11        agentId="YOUR_AGENT_ID"12        apiKey="pk_live_YOUR_PUBLISHABLE_KEY"13        backendUrl="https://api.vanira.io">14        <MyScreen />15      </VaniraCallProvider>16    </PresetHostProvider>17  );18}19 20function MyScreen() {21  const {startCall, stopCall, status} = useVaniraCall();22  // your buttons…23}
Exports: VaniraAI, createReactNativeAI, PresetHostProvider, VaniraCallProvider, useVaniraCall, session storage helpers, preset utilities.

Quick Start

#

Option A — VaniraCallBox (fastest)

See VaniraCallBox guide — one component, presets included.

Option B — Manual wiring

Step 1 — Wrap the app

PresetHostProvider mounts preset modals (upload, calendar, form, camera, etc.) above your screens.
Code exampletypescript
1import {PresetHostProvider} from '@vanira/sdk-react-native';2 3export default function App() {4  return (5    <PresetHostProvider>6      <YourNavigation />7    </PresetHostProvider>8  );9}

Step 2 — Start a voice call

Code exampletypescript
1import {useRef} from 'react';2import {3  createReactNativeAI,4  usePresetHost,5  type ClientToolCall,6  type VaniraAI,7} from '@vanira/sdk-react-native';8 9function VoiceScreen() {10  const {setAiClient, setActiveToolCall} = usePresetHost();11  const aiRef = useRef<VaniraAI | null>(null);12 13  async function startCall() {14    const ai = createReactNativeAI({15      agentId: 'YOUR_AGENT_ID',16      apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY',17      backendUrl: 'https://api.vanira.io',18    });19 20    ai.on('preset', ({toolCall}) => setActiveToolCall(toolCall));21    ai.on('tool_call', (tc: ClientToolCall) => setActiveToolCall(tc));22 23    ai.on('connected', () => console.log('connected'));24    ai.on('disconnected', () => {25      aiRef.current = null;26      setAiClient(null);27    });28    ai.on('error', (msg) => console.error(msg));29 30    aiRef.current = ai;31    setAiClient(ai);   // required — presets call uploadMedia / sendToolResult on this client32    await ai.start();33  }34 35  function stopCall() {36    aiRef.current?.stop();37    aiRef.current = null;38    setAiClient(null);39  }40 41  // your start/stop button UI…42}

Rules

  • Call setAiClient(ai) when the call starts — preset modals need the live client
  • Route both preset and tool_call events to setActiveToolCall()
  • Start calls from a button tap (microphone permission + audio routing)
  • Use ai.stop() on hang-up and clear setAiClient(null)

Preset Handler (RN)

#
On React Native, presets are handled by `PresetHostProvider` — no separate PresetRenderer mount needed.
When the agent triggers a preset tool, route the tool call to the host:
Code exampletypescript
1ai.on('preset', ({toolCall}) => setActiveToolCall(toolCall));2ai.on('tool_call', (tc) => setActiveToolCall(tc));
The SDK automatically renders the matching modal (form, calendar, upload, camera, navigate, etc.) and sends sendToolResult() when the user completes or cancels.
Preset IDUIMode
vanira_formData Collection Formblocking
vanira_phoneMobile numberblocking
vanira_mcqMultiple Choice Questionblocking
vanira_calendarDate & Time Pickerblocking
vanira_uploadFile Uploadblocking
vanira_cameraCamera Capturefire_and_forget
vanira_navigateNavigate to Route — requires vanira:navigate listener on SPAsblocking
vanira_highlight_elementHighlight Elementblocking
vanira_click_elementClick Elementblocking
vanira_select_optionSelect Dropdown Optionblocking
vanira_set_dateSet Date Fieldblocking
vanira_type_textDOM Typing Simulationblocking
vanira_write_latex_textChalkboard LaTeX Writerblocking
vanira_erase_textWhiteboard / DOM Eraseblocking
vanira_live_visionLive Vision (Streaming Camera)fire_and_forget
vanira_close_live_cameraStop Live Camerablocking
vanira_live_screenLive Screen Sharefire_and_forget
vanira_close_live_screenStop Live Screen Shareblocking
vanira_clip_regionPage Region Clipblocking
vanira_screen_visionScreen Visionblocking
vanira_point_atPoint At Screenblocking
vanira_draw_on_screenDraw On Screenblocking
vanira_clear_screen_drawClear Screen Drawingsblocking
vanira_highlight_on_screenHighlight On Screenblocking
vanira_kyc_document_captureKYC Document Captureblocking
vanira_kyc_selfie_captureKYC Selfie Captureblocking
vanira_kyc_signature_captureKYC Signature Captureblocking

Native deps by preset

PresetExtra packages
Voice onlyreact-native-webrtc
Uploadreact-native-image-picker, @react-native-documents/picker
Camerareact-native-image-picker
Live visionreact-native-vision-camera
Calendar, form, navigateSDK only

Custom tools

Presets are automatic. For custom client tools (your own UI logic), handle them in the tool_call handler before calling setActiveToolCall:
Code exampletypescript
1ai.on('tool_call', (tc) => {2  if (tc.name === 'my_custom_tool') {3    showMyModal(tc.arguments);4    if (tc.execution_mode === 'blocking') {5      ai.sendToolResult(tc.tool_call_id, {success: true});6    }7    return;8  }9  setActiveToolCall(tc);10});
Dashboard preset tool bodies: see Tools → Preset Tools in this docs sidebar.

RN Events

#
Use .on(event, handler) on VaniraAI (returned by createReactNativeAI):
EventWhen it fires
connectedWebRTC live — show "connected" UI
disconnectedCall ended — clean up client ref
errorConnection or permission failure
transcriptionUser speech-to-text ({ text, isFinal })
presetAgent triggered a built-in preset
tool_callAgent triggered any client tool (preset or custom)

Example

Code exampletypescript
1ai.on('connected', () => setStatus('connected'));2ai.on('disconnected', () => {3  setStatus('idle');4  setAiClient(null);5});6ai.on('error', (message) => Alert.alert('Call failed', message));7ai.on('transcription', ({text, isFinal}) => {8  if (isFinal) setLastUtterance(text);9});10ai.on('preset', ({toolCall}) => setActiveToolCall(toolCall));11ai.on('tool_call', (tc) => setActiveToolCall(tc));

Sending events to the agent

Same API as web VaniraClient:
MethodPurpose
sendToolResult(id, result)Reply to blocking tools
sendToolError(id, message)Report tool failure
uploadMedia(file, reason, message)Send image/PDF during call
Call ai.stop() to end the session.

Session Continuity (RN)

#
Resume a previous voice session after the app restarts by plugging AsyncStorage (or any sync storage) into the runtime.
Code exampletypescript
1import {2  createReactNativeAI,3  createSyncStorageAdapter,4  reactNativeRuntime,5  hasContinueSession,6  loadContinueSession,7} from '@vanira/sdk-react-native';8import AsyncStorage from '@react-native-async-storage/async-storage';9 10const runtime = {11  ...reactNativeRuntime,12  storage: createSyncStorageAdapter(AsyncStorage),13};14 15// Check before showing "Continue" button16const canContinue = hasContinueSession(runtime.storage, agentId);17const stored = loadContinueSession(runtime.storage, agentId);18 19const ai = createReactNativeAI({20  agentId: 'YOUR_AGENT_ID',21  apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY',22  backendUrl: 'https://api.vanira.io',23  sessionBehavior: 'continue',  // or 'new'24  prospectId: stored?.prospectId,25  callId: stored?.callId,26  runtime,27});28 29await ai.start();
sessionBehaviorBehavior
'new' (default)Fresh call every time
'continue'Reuse stored prospect_id + call_id
Storage keys are managed by the SDK (vanira_prospect_id, vanira_latest_call_id) via your storage adapter.

Upload Media (RN)

#
During a live call, upload images or documents with uploadMedia(). The SDK handles the HTTP upload and sends client_media_update to the agent.
The upload preset (vanira_upload) uses this automatically. For manual uploads:
Code exampletypescript
1const response = await ai.uploadMedia(2  {3    uri: fileUri,4    type: 'image/jpeg',5    name: 'photo.jpg',6  },7  'damage_photo',8  'What is wrong with this leaf?',9);

Supported formats

JPEG, JPG, PNG, GIF, WebP, BMP, PDF, TXT, CSV — max 50 MB.

React Native file shape

Pass { uri, type, name, size? } — not File / Blob:
Code exampletypescript
1await ai.uploadMedia(2  {uri: asset.uri, type: 'image/jpeg', name: 'upload.jpg'},3  'general',4  'User uploaded a photo',5);
> Do not call triggerActionInterrupt() after uploadMedia() — the media update already notifies the agent.

RN vs Web SDK

#
Voice entryVaniraCallBox or VaniraClientVaniraCallBox or createReactNativeAI()
Headless@vanira/sdk/headless@vanira/sdk-react-native/headless
Preset UIPresetRenderer or automatic in CallBoxAutomatic in VaniraCallBox; or PresetHostProvider
Connectclient.connect() or client.start()await ai.start()
Upload file typeFile / Blob{ uri, type, name }
Session storagelocalStorage / sessionStorageYour AsyncStorage adapter
WebRTC setupBrowser APIsregisterGlobals() + native modules
Same agent, same preset IDs, same data-channel protocol — different platform adapters.

Template Agents

#
Clone a public agent into your Vanira account in one click. Perfect for learning preset tools, voice flows, and industry-specific prompts.

How it works

1. Pick a template below (or browse )
2. Sign in → Import to My Account
3. Customize voice, tools, and presets in the dashboard
4. Embed with widget or SDK using your own pk_live_* key

Make your agent shareable

In the dashboard: Agent → Share → Make public. Others can import via:
Code exampletext
1https://vanira.io/import?agentId=YOUR_AGENT_ID

Featured templates

AgentVerticalPlatformImport
Refund & Returns AgentE-commerceweb
Kisan Support AgentAgriculturereact-native, web
Maths Tutor AgentEducationweb
Citizen Services AgentCitizen accessweb

Starter Repositories

#
Fork a minimal working app instead of starting from scratch.

vanira-starter-web

Vite + React + VaniraCallBox — voice pill and presets in minutes.

vanira-starter-rn

React Native + PresetHostProvider + createReactNativeAI.
  • GitHub: https://github.com/VaniraAI/vanira-starter-rn
After cloning, add your agentId and pk_live_* from the dashboard.

Developer Referral

#
Invite other developers to Vanira from Dashboard → Settings → Refer a developer.
Your personal link includes a referral code. When someone signs up through it, both accounts can receive bonus credits (when the referral program is active).
Share format:
Code exampletext
1https://vanira.io/signup?ref=YOUR_CLIENT_ID&utm_source=referral
Also share:

Built with Vanira

#
Shipped something with Vanira? Submit your project for the Built with Vanira gallery at .
Featured projects get:
  • Homepage showcase placement
  • Backlink from docs
  • Social promotion

Preset: Form

#
Collect structured data with a dynamic form modal.
  • *Dashboard:** Client tool → preset vanira_form
  • *LLM parameters (per call):** reason, fields (comma-separated labels the agent chooses for this interaction), optional title
  • *client_fields:** preset_id only required; optional title / fields as fallbacks when the model omits them.
Works on web (PresetRenderer) and React Native (PresetHost) with zero custom UI code.
Preset IDUIMode
vanira_formData Collection Formblocking
vanira_phoneMobile numberblocking
vanira_mcqMultiple Choice Questionblocking
vanira_calendarDate & Time Pickerblocking
vanira_uploadFile Uploadblocking
vanira_cameraCamera Capturefire_and_forget
vanira_navigateNavigate to Route — requires vanira:navigate listener on SPAsblocking
vanira_highlight_elementHighlight Elementblocking
vanira_click_elementClick Elementblocking
vanira_select_optionSelect Dropdown Optionblocking
vanira_set_dateSet Date Fieldblocking
vanira_type_textDOM Typing Simulationblocking
vanira_write_latex_textChalkboard LaTeX Writerblocking
vanira_erase_textWhiteboard / DOM Eraseblocking
vanira_live_visionLive Vision (Streaming Camera)fire_and_forget
vanira_close_live_cameraStop Live Camerablocking
vanira_live_screenLive Screen Sharefire_and_forget
vanira_close_live_screenStop Live Screen Shareblocking
vanira_clip_regionPage Region Clipblocking
vanira_screen_visionScreen Visionblocking
vanira_point_atPoint At Screenblocking
vanira_draw_on_screenDraw On Screenblocking
vanira_clear_screen_drawClear Screen Drawingsblocking
vanira_highlight_on_screenHighlight On Screenblocking
vanira_kyc_document_captureKYC Document Captureblocking
vanira_kyc_selfie_captureKYC Selfie Captureblocking
vanira_kyc_signature_captureKYC Signature Captureblocking

Preset: Upload

#
  • *Snapshot upload** — user picks one file during a call.
StepBehavior
Uploadclient.uploadMedia() → WebRTC or HTTP
Notifyclient_media_update with media_id, media_url, reason
AgentCalls process_media and responds
This is not live vision. Do not use for streaming camera frames.
  • *Web accept:** image/*,application/pdf,text/plain,text/csv
  • *React Native:** requires react-native-image-picker + document picker peer deps.
  • *Routing:** set reason in client_fields (e.g. kyc_document, general) for webhook/vision pipeline routing.

Preset: Navigate

#
SPA or external navigation from voice.
  • *Web:** listen for vanira:navigate or use onNavigate on VaniraCallBox.
  • *Framework apps (Next.js, Remix, etc.) cannot paste the script tag in `layout.tsx` alone — React will not run a global `vanira:navigate` listener for you. Mount the widget once from a client component** and register navigation with your framework router (useRouter in Next.js App Router). The widget custom element stays on document.body, so route changes do not tear down the call.
  • *Next.js App Router: inject the script from a `"use client"` `VaniraWidget` and render `VaniraNavigateListener` alongside it (uses `useRouter` from `next/navigation`). See Widget Embed** in the SDK docs for full copy-paste files.
  • *React Native:** register registerInternalRouteHandler() for in-app routes.
  • *Routing fields:** target_url or path in tool arguments; SDK dispatches navigation without interrupting audio unless configured.

Preset: Live Vision

#
  • *Live camera stream** (~1 fps) — agent sees the world during the call without interrupting speech.

Client sequence (automatic via PresetRenderer)

Code exampletext
1open_live_camera2  → client_live_camera_started3  → uploadMediaFrame() per frame (HTTP)4  → client_media_frame (NOT client_media_update)5  → client_live_camera_stopped

Tool / client_fields

FieldNotes
scopefull_calluntil_call_endtimed
target_fpsDefault 1, max 3
max_widthResize before upload (px)
reasonDefault camera_capture — media routing tag
duration_secRequired for timed scope
  • *Agent config:** Agent → Vision LLM → live vision scope & defaults.
  • *Web auto-start:** liveVision: { enabled: true, scope: 'full_call' } on VaniraClient.
  • *React Native:** react-native-vision-camera required. See LiveVisionCameraHost.
See Multimodal Architecture for snapshot vs stream comparison.

Preset: Live Screen

#
  • *Live screen share stream** (~1 fps) — same protocol as live camera, different capture source.

Client sequence

Code exampletext
1open_live_screen2  → client_live_screen_started { display_surface, … }3  → uploadMediaFrame() per frame4  → client_media_frame { source: 'screen', … }5  → client_live_screen_stopped
Uses uploadMediaFrame() + client_media_frame only — never uploadMedia() / client_media_update.
  • *Web:** getDisplayMedia in WidgetPresetRenderer.
  • *React Native:** getDisplayMedia + view-shot on preview (best-effort on mobile).
  • *reason:** default screen_capture.

List Providers

GET
#
GEThttps://api.vanira.io/discovery/providers
Returns AI / TTS / STT providers available on the platform.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/discovery/providers'

Expected Response — 200 OK

json
1{2  "providers": [3    { "id": "...", "name": "AZURE", "type": "ai" },4    { "id": "...", "name": "ELEVENLABS", "type": "tts" },5    { "id": "...", "name": "DEEPGRAM", "type": "stt" }6  ]7}

Response Schema Details

nameREQUIRED
string

Provider identifier used in agent config.

typeREQUIRED
string

ai | tts | stt.

HTTP Errors

401
UNAUTHORIZED

No valid API key provided.

List AI Models

GET
#
GEThttps://api.vanira.io/discovery/models
Returns all active LLM models available on the platform.
Use the provider and model values from this response when creating or updating an agent's model field. Only status: "active" models are returned.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/discovery/models'

Expected Response — 200 OK

json
1{2  "models": [3    {4      "id": "89e40b9c-...",5      "name": "gpt-4.1-mini",6      "ai_provider": "AZURE",7      "status": "active"8    },9    {10      "id": "7d49e047-...",11      "name": "gpt-4o-mini-realtime-preview",12      "ai_provider": "AZURE_REALTIME",13      "status": "active"14    }15  ]16}

Response Schema Details

idREQUIRED
uuid

Internal model UUID (not needed for API calls).

nameREQUIRED
string

Model name to use in agent model.model field. e.g. gpt-4.1-mini

ai_providerREQUIRED
string

Provider string to use in agent model.provider field. e.g. AZURE, AZURE_REALTIME, GROQ

statusREQUIRED
string

active | inactive. Only active models are returned.

HTTP Errors

401
UNAUTHORIZED

No valid API key provided.

List Vision Models

GET
#
GEThttps://api.vanira.io/discovery/vision-models
Returns vision / multimodal models for agent live-vision configuration.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/discovery/vision-models'

Expected Response — 200 OK

json
1{2  "models": [3    {4      "id": "...",5      "name": "gpt-4.1-mini",6      "label": "GPT-4.1 Mini Vision",7      "ai_provider": "AZURE",8      "is_active": true9    }10  ]11}

Response Schema Details

nameREQUIRED
string

Model name for vision_model field.

ai_providerREQUIRED
string

Provider for vision_provider field.

is_activeREQUIRED
boolean

Whether the model is currently available.

HTTP Errors

401
UNAUTHORIZED

No valid API key provided.

List TTS Voices

GET
#
GEThttps://api.vanira.io/discovery/voices
Returns all active TTS voices available on the platform.
Use the tts_provider and name values when setting an agent's voice field.
Each voice may include:
  • demo_audio_url — legacy single sample (kept for backward compatibility)
  • previews — array of language-specific samples from tts_voice_previews ({ language, audio_url }). Prefer this when picking a clip for a caller's language.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/discovery/voices'

Expected Response — 200 OK

json
1{2  "voices": [3    {4      "id": "79506325-...",5      "name": "shubh",6      "tts_provider": "SARVAM",7      "language": "hi",8      "status": "active",9      "demo_audio_url": "https://…/tts-voice-previews/sarvam/79506325-…/hi.wav",10      "previews": [11        { "language": "hi", "audio_url": "https://…/tts-voice-previews/sarvam/79506325-…/hi.wav" }12      ]13    },14    {15      "id": "db9faea1-...",16      "name": "Riya Rao",17      "tts_provider": "ELEVENLABS",18      "language": "ENGLISH",19      "gender": "FEMALE",20      "status": "active",21      "demo_audio_url": "https://…/riya.wav",22      "previews": []23    }24  ]25}

Response Schema Details

idREQUIRED
uuid

Internal voice UUID (not needed for API calls).

nameREQUIRED
string

Voice name to use in agent voice.name field. e.g. Riya Rao

tts_providerREQUIRED
string

Provider to use in agent voice.provider field. e.g. ELEVENLABS, SARVAM

language
string

Primary language of the voice. e.g. ENGLISH, HINDI, hi

gender
string

MALE | FEMALE

statusREQUIRED
string

active | inactive. Only active voices are returned.

demo_audio_url
string

Legacy single demo clip URL. Still returned when set; prefer previews[] for language-specific audio.

previewsREQUIRED
array

Language-specific preview clips. Each item: { language: string (e.g. hi, en, te), audio_url: string }. Empty array when none exist.

HTTP Errors

401
UNAUTHORIZED

No valid API key provided.

List STT Models

GET
#
GEThttps://api.vanira.io/discovery/transcription-models
Returns all active Speech-to-Text models available on the platform.
Use the provider and name values when setting an agent's transcription field.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/discovery/transcription-models'

Expected Response — 200 OK

json
1{2  "models": [3    { "id": "8d398506-...", "name": "nova-2",    "provider": "DEEPGRAM", "status": "active" },4    { "id": "dc641dca-...", "name": "nova-3",    "provider": "DEEPGRAM", "status": "active" },5    { "id": "75bfb690-...", "name": "saaras:v3", "provider": "SARVAM",   "status": "active" },6    { "id": "30fa4dbe-...", "name": "saaras:v2", "provider": "SARVAM",   "status": "active" }7  ]8}

Response Schema Details

idREQUIRED
uuid

Internal model UUID (not needed for API calls).

nameREQUIRED
string

Model name to use in agent transcription.model field. e.g. nova-2, saaras:v3

providerREQUIRED
string

Provider to use in agent transcription.provider field. e.g. DEEPGRAM, SARVAM

statusREQUIRED
string

active | inactive. Only active models are returned.

HTTP Errors

401
UNAUTHORIZED

No valid API key provided.

List Ambient Noise Types

GET
#
GEThttps://api.vanira.io/discovery/ambient-noise-types
Returns allowed ambient_noise_type values for agents, plus platform defaults.
Use with ambient_noise_volume in [0, 1] when creating or updating an agent.
Server mixes a looping bed under TTS at call start — clients do not send ambient per call.
  • Default type: traffic
  • Default volume: 0.35
  • Set type to none to disable ambient (volume treated as 0)

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/discovery/ambient-noise-types'

Expected Response — 200 OK

json
1{2  "types": [3    { "value": "none",         "label": "Off",          "description": "No ambient bed" },4    { "value": "quiet_office", "label": "Quiet office", "description": "Soft room / HVAC tone" },5    { "value": "call_center",  "label": "Call center",  "description": "Floor ambience" },6    { "value": "traffic",      "label": "Traffic",      "description": "City / road traffic" }7  ],8  "defaults": {9    "ambient_noise_type": "traffic",10    "ambient_noise_volume": 0.3511  }12}

Response Schema Details

valueREQUIRED
string

Stable id for agent.ambient_noise_type.

labelREQUIRED
string

Suggested UI label.

descriptionREQUIRED
string

Helper text for the dashboard.

defaults.ambient_noise_typeREQUIRED
string

Platform default when agent field is null.

defaults.ambient_noise_volumeREQUIRED
number

Platform default volume in [0, 1].

HTTP Errors

401
UNAUTHORIZED

No valid API key provided.

Fetch ICE Servers

GET
#
GEThttps://api.vanira.io/discovery/ice-servers
Returns active STUN/TURN server configuration for WebRTC peer connection setup.
Pass the returned array to RTCPeerConnection({ iceServers: [...] }) or use the SDK's VaniraClient.fetchIceServers(apiKey) helper which calls this endpoint automatically.
STUN servers help discover your public IP. TURN servers relay media when a direct peer-to-peer connection can't be established (firewalls, symmetric NAT).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/discovery/ice-servers'

Expected Response — 200 OK

json
1{2  "ice_servers": [3    {4      "urls": ["stun:stun.relay.metered.ca:80"],5      "username": null,6      "credential": null7    },8    {9      "urls": [10        "turn:global.relay.metered.ca:80",11        "turn:global.relay.metered.ca:443",12        "turns:global.relay.metered.ca:443?transport=tcp"13      ],14      "username": "<metered_user_id>",15      "credential": "<metered_credential_secret>"16    }17  ]18}

Response Schema Details

urlsREQUIRED
array

List of STUN/TURN URLs for this server.

username
string

TURN username. null for STUN-only servers.

credential
string

TURN password/credential. null for STUN-only servers.

HTTP Errors

401
UNAUTHORIZED

No valid API key provided.

List Industries

GET
#
GEThttps://api.vanira.io/discovery/industries
Catalog of industries used for agent onboarding templates.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/discovery/industries'

Expected Response — 200 OK

json
1[2  {3    "id": "ind-uuid-...",4    "name": "Healthcare",5    "description": "Clinics and hospitals",6    "icon_key": "healthcare"7  }8]

HTTP Errors

401
UNAUTHORIZED

No valid API key provided.

List Use Cases

GET
#
GEThttps://api.vanira.io/discovery/use-cases
Catalog of use-case templates (prompts / welcome messages) for agent setup.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/discovery/use-cases'

Expected Response — 200 OK

json
1[2  {3    "id": "uc-uuid-...",4    "industry_id": "ind-uuid-...",5    "type": "outbound",6    "label": "Appointment reminder",7    "key": "appt_reminder",8    "prompt": "You are...",9    "welcome_message": "Hi, this is..."10  }11]

HTTP Errors

401
UNAUTHORIZED

No valid API key provided.

Generate API Key

POST
#
POSThttps://api.vanira.io/api-keys/generate
Create a secret (sk_live_*) or publishable (pk_live_*) API key. The full key is returned once.
  • *Authentication**
Requires Authorization: Bearer <kinde_jwt> with scope keys:manage. Secret API keys typically cannot manage other keys.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

nameREQUIRED
string

Label for the key.

key_typeREQUIRED
string

secret | publishable.

allowed_origins
array

CORS origins for publishable keys. Use ["*"] to allow all.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/api-keys/generate' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "Production server",5  "key_type": "secret",6  "allowed_origins": [7    "https://app.example.com"8  ]9}'

Expected Response — 200 OK

json
1{2  "key": "sk_live_••••••••",3  "name": "Production server",4  "key_type": "secret",5  "created_at": "2026-04-01T10:00:00Z",6  "key_mask": "sk_live_…abcd",7  "message": "Store this key securely — it will not be shown again."8}

Response Schema Details

keyREQUIRED
string

Full API key value (shown once).

key_maskREQUIRED
string

Masked form stored for listing.

key_typeREQUIRED
string

secret | publishable.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid JWT.

403
INSUFFICIENT_SCOPE

Missing keys:manage scope.

List API Keys

GET
#
GEThttps://api.vanira.io/api-keys
List API key metadata for the authenticated client (never returns full secrets).
  • *Authentication**
Requires Authorization: Bearer <kinde_jwt> with scope keys:manage. Secret API keys typically cannot manage other keys.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/api-keys'

Expected Response — 200 OK

json
1{2  "keys": [3    {4      "id": "key-uuid-...",5      "name": "Production server",6      "key_type": "secret",7      "key_mask": "sk_live_…abcd",8      "allowed_origins": [],9      "created_at": "2026-04-01T10:00:00Z",10      "revoked": false11    }12  ],13  "total": 114}

HTTP Errors

401
UNAUTHORIZED

Missing or invalid JWT.

403
INSUFFICIENT_SCOPE

Missing keys:manage scope.

Revoke API Key

DELETE
#
DELETEhttps://api.vanira.io/api-keys/:key_id
Revoke an API key. Existing callers will receive 401.
  • *Authentication**
Requires Authorization: Bearer <kinde_jwt> with scope keys:manage. Secret API keys typically cannot manage other keys.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

key_idREQUIRED
uuid

API key UUID from list.

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/api-keys/<key_id>' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "revoked": true,3  "message": "API key revoked"4}

HTTP Errors

404
KEY_NOT_FOUND

Key not found.

Update Allowed Origins

PATCH
#
PATCHhttps://api.vanira.io/api-keys/:key_id/origins
Update CORS allowed origins for a publishable key.
  • *Authentication**
Requires Authorization: Bearer <kinde_jwt> with scope keys:manage. Secret API keys typically cannot manage other keys.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

key_idREQUIRED
uuid

API key UUID.

Body Parameters

allowed_originsREQUIRED
array

Origin allowlist. Use ["*"] for all.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/api-keys/<key_id>/origins' \2  -H "Content-Type: application/json" \3  -d '{4  "allowed_origins": [5    "https://app.example.com",6    "*"7  ]8}'

Expected Response — 200 OK

json
1{2  "id": "key-uuid-...",3  "allowed_origins": ["https://app.example.com"]4}

HTTP Errors

404
KEY_NOT_FOUND

Key not found.

422
VALIDATION_ERROR

Invalid origins array.

List Numbers

GET
#
GEThttps://api.vanira.io/phone-numbers
Returns all active phone numbers connected to your account for both inbound and outbound calling.
This includes both bought numbers and numbers imported from external providers.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/phone-numbers'

Expected Response — 200 OK

json
1{2  "numbers": [3    {4      "id": "09d89078-b9cc-452d-ae06-126d04239b73",5      "number": "+918071387205",6      "country_code": "IN",7      "label": "Primary DID",8      "client_id": "91b5f2de-9e01-4520-837f-58f284e40a4c",9      "trunk_id": "0c014935-8e11-4632-8cfe-9028d01b492c",10      "is_active": true,11      "is_vanira_internal": false,12      "agent_id": "caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5"13    }14  ]15}

Response Schema Details

numberREQUIRED
string

The phone number in E.164 format (digits only).

country_codeREQUIRED
string

ISO 2-letter country code.

labelREQUIRED
string

Human-readable label for the number.

agent_id
uuid

ID of the agent currently handling calls for this number.

is_activeREQUIRED
boolean

Whether the number is ready to receive and make calls.

is_vanira_internalREQUIRED
boolean

If true, this number belongs to the Vanira shared pool.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

400
BAD_REQUEST

Missing client_id.

List Vanira Managed Numbers

GET
#
GEThttps://api.vanira.io/phone-numbers/vanira
List Vanira-managed DIDs available to / allocated for the authenticated client.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Query Parameters

include_inactive
boolean

Include inactive numbers. Default false.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/phone-numbers/vanira?include_inactive=false'

Expected Response — 200 OK

json
1{2  "numbers": [3    {4      "number": "+918071387205",5      "is_active": true,6      "label": "Vanira pool"7    }8  ]9}

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

Browse Inventory

GET
#
GEThttps://api.vanira.io/phone-numbers/inventory
Browse purchasable SIP inventory for a country.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Query Parameters

country
string

ISO country code. Default IN.

page
number

Page number.

per_page
number

Page size.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/phone-numbers/inventory?country=IN&page=1&per_page=20'

Expected Response — 200 OK

json
1{2  "numbers": [3    { "phone_number": "+9180XXXXXXX", "country": "IN", "monthly_price": "..." }4  ],5  "page": 16}

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

Buy Number

POST
#
POSThttps://api.vanira.io/phone-numbers/buy
Purchase a number from inventory and attach it to your account.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

phone_numberREQUIRED
string

E.164 number from inventory.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/phone-numbers/buy' \2  -H "Content-Type: application/json" \3  -d '{4  "phone_number": "+918071387205"5}'

Expected Response — 200 OK

json
1{2  "phone_number": "+918071387205",3  "purchased": true4}

HTTP Errors

400
BAD_REQUEST

Number unavailable or invalid.

402
INSUFFICIENT_CREDITS

Billing / credits issue.

Import vobiz number

POST
#
POSThttps://api.vanira.io/phone-numbers/import
Import your existing phone number from vobiz and connect it to a Vanira agent. This allows the agent to handle both incoming and outgoing calls on that number automatically.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

phone_numberREQUIRED
string

E.164 phone number (e.g. +918071387205).

agent_idREQUIRED
uuid

ID of the agent who will handle calls.

vobiz_auth_id
string

VoBiz X-Auth-ID. Required for first-time import.

vobiz_auth_token
string

VoBiz X-Auth-Token. Required for first-time import.

use_existing_credentials
boolean

Use previously stored credentials for this client. Default: false.

credential_label
string

Label for newly stored credentials.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/phone-numbers/import' \2  -H "Content-Type: application/json" \3  -d '{4  "phone_number": "+918071387205",5  "agent_id": "caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5",6  "vobiz_auth_id": "<vobiz_auth_id>",7  "vobiz_auth_token": "<vobiz_auth_token>",8  "use_existing_credentials": false,9  "credential_label": "<credential_label>"10}'

Expected Response — 200 OK

json
1{2  "phone_number": "+918071387205",3  "agent_id": "caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5",4  "trunk_endpoint": "endpoint-1387205",5  "outbound_trunk_id": "8747b89c-a5d4-4307-8e12-ccbdabcc2907",6  "assigned": true,7  "service_reloaded": true8}

HTTP Errors

401
UNAUTHORIZED

Invalid API key.

207
MULTI_STATUS

Upstream OK but secondary sync had non-fatal errors.

400
BAD_REQUEST

No credentials available or missing required fields.

409
CONFLICT

Number already exists in system — delete it first.

422
UNPROCESSABLE_ENTITY

Number not found on provider account or assignment failed.

502
BAD_GATEWAY

Upstream failure (Provider unreachable).

Assign to Agent

PUT
#
PUThttps://api.vanira.io/phone-numbers/link
Connect a phone number to a different agent. Both incoming and outgoing calls will be immediately handled by the new agent.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

phone_numberREQUIRED
string

The phone number to update.

agent_idREQUIRED
uuid

ID of the new agent to handle all call traffic.

Implementation Example

Environment
1curl -X PUT 'https://api.vanira.io/phone-numbers/link' \2  -H "Content-Type: application/json" \3  -d '{4  "phone_number": "+918071387205",5  "agent_id": "5396166a-f107-4918-b108-ff97b5987178"6}'

Expected Response — 200 OK

json
1{2  "success": true,3  "phone_number": "+918071387205",4  "agent_id": "5396166a-f107-4918-b108-ff97b5987178"5}

HTTP Errors

404
PHONE_NUMBER_NOT_FOUND

Phone number not found.

404
AGENT_NOT_FOUND

Agent not found.

Set Number Active

PATCH
#
PATCHhttps://api.vanira.io/phone-numbers/:phone_number/active
Enable or disable a phone number. Path phone_number should be E.164; URL-encode + as %2B.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

phone_numberREQUIRED
string

E.164 number (encode + as %2B).

Body Parameters

is_activeREQUIRED
boolean

true to activate, false to deactivate.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/phone-numbers/%252B918071387205/active' \2  -H "Content-Type: application/json" \3  -d '{4  "is_active": true5}'

Expected Response — 200 OK

json
1{2  "phone_number": "+918071387205",3  "is_active": true4}

HTTP Errors

404
PHONE_NUMBER_NOT_FOUND

Phone number not found.

Delete Number

DELETE
#
DELETEhttps://api.vanira.io/phone-numbers/:number
Remove a phone number from your account. This will stop the agent from making or answering any more calls on this number.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

numberREQUIRED
string

The phone number to remove (E.164 format).

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/phone-numbers/%2B918071387205' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "phone_number": "+918071387205",3  "deleted": true,4  "unassigned": true5}

HTTP Errors

401
UNAUTHORIZED

Invalid API key.

404
PHONE_NUMBER_NOT_FOUND

Phone number not found in system.

502
BAD_GATEWAY

VoBiz unassign failed.

List VoBiz Credentials

GET
#
GEThttps://api.vanira.io/phone-numbers/vobiz/credentials
Fetch stored VoBiz credential metadata for the authenticated client. Returns hints and labels, never secret tokens.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/phone-numbers/vobiz/credentials'

Expected Response — 200 OK

json
1{2  "credentials": [3    {4      "id": "436c27d7-f357-4033-8ea0-97de12a989c2",5      "label": "primary",6      "auth_id_hint": "MA_",7      "is_default": false,8      "created_at": "2026-05-08T19:47:47Z",9      "updated_at": "2026-05-08T19:47:47Z"10    }11  ]12}

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

List Agents

GET
#
GEThttps://api.vanira.io/assistant
Returns all voice agents owned by the authenticated client.
Each agent includes the three Vapi-style config objects — model, voice, and transcription — instead of raw internal IDs.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/assistant'

Expected Response — 200 OK

json
1{2  "agents": [3    {4      "id": "caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5",5      "name": "Sales Rep",6      "active": true,7      "language": "en-US",8      "model":         { "provider": "AZURE",      "model": "gpt-4.1-mini" },9      "voice":         { "provider": "ELEVENLABS",  "name": "Riya Rao" },10      "transcription": { "provider": "DEEPGRAM",    "model": "nova-2" },11      "enable_lid_detection": true,12      "lid_allowed_languages": ["hi", "en"],13      "created_at": "2026-01-10T08:00:00Z",14      "updated_at": "2026-02-01T12:00:00Z",15      "client_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"16    }17  ]18}

Response Schema Details

idREQUIRED
uuid

Agent UUID.

nameREQUIRED
string

Display name.

activeREQUIRED
boolean

Whether the agent is active.

languageREQUIRED
string

Language code e.g. en-US.

model
object

{ provider, model } — LLM config. See GET /discovery/models.

voice
object

{ provider, name } — TTS voice config. See GET /discovery/voices.

transcription
object

{ provider, model } — STT config.

ambient_noise_type
string

Ambient bed: none | quiet_office | call_center | traffic.

ambient_noise_volume
number

Ambient mix level in [0, 1].

enable_lid_detection
boolean

Whether LID is enabled.

lid_allowed_languages
string[]

Allowed languages for pivoting.

client_idREQUIRED
uuid

Owner client ID.

HTTP Errors

401
UNAUTHORIZED

No valid API key or JWT provided.

500
DATABASE_ERROR

Internal database error.

Get Agent

GET
#
GEThttps://api.vanira.io/assistant/:id
Retrieve full configuration for a specific agent including prompt, data collection settings, and all three config objects.
  • *Ownership enforced** — returns 404 if the agent belongs to a different client.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the agent.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/assistant/caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5'

Expected Response — 200 OK

json
1{2  "id": "caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5",3  "name": "Sales Rep",4  "active": true,5  "language": "en-US",6  "model":         { "provider": "AZURE",      "model": "gpt-4.1-mini" },7  "voice":         { "provider": "ELEVENLABS",  "name": "Riya Rao" },8  "transcription": { "provider": "DEEPGRAM",    "model": "nova-2" },9  "welcome_message": "Hey! How can I help you?",10  "agent_prompt": "You are a helpful sales assistant...",11  "inbound_welcome_message": "Thanks for calling. How can I help?",12  "data_collection": { ... },13  "success_metric": { ... },14  "input_needed_json_format": [ ... ],15  "temperature": 0.7,16  "top_p": 1.0,17  "speed": null,18  "duty": "support",19  "silence_alert_message": "Are you still there?",20  "call_end_duration": 20000,21  "call_user_alert_duration": 7000,22  "initial_disable_mic_duration": 0,23  "enable_lid_detection": true,24  "lid_allowed_languages": ["hi", "en"],25  "ambient_noise_type": "traffic",26  "ambient_noise_volume": 0.35,27  "created_at": "2026-01-10T08:00:00Z",28  "updated_at": "2026-02-01T12:00:00Z",29  "client_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"30}

Response Schema Details

idREQUIRED
uuid

Agent UUID.

nameREQUIRED
string

Display name.

activeREQUIRED
boolean

Active status.

model
object

{ provider, model } — LLM. Use GET /discovery/models for valid values.

voice
object

{ provider, name } — TTS voice. Use GET /discovery/voices for valid values.

transcription
object

{ provider, model } — STT transcription.

ambient_noise_type
string

Ambient bed: none | quiet_office | call_center | traffic. Default traffic.

ambient_noise_volume
number

Ambient mix level in [0, 1]. Default 0.35.

agent_prompt
string

LLM system prompt.

welcome_message
string

First message spoken by the agent.

temperature
number

LLM temperature (0–2).

speed
number

TTS speech speed multiplier.

enable_lid_detection
boolean

Whether LID is enabled.

lid_allowed_languages
string[]

Allowed languages for pivoting.

data_collection
object

Call outcome and scoring configuration.

HTTP Errors

401
UNAUTHORIZED

No valid API key or JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

422
VALIDATION_ERROR

Invalid UUID format for id.

Create Agent

POST
#
POSThttps://api.vanira.io/assistant
Create a new voice agent. Pass model, voice, and transcription as structured objects — no internal UUIDs needed.
Use GET /discovery/models and GET /discovery/voices to discover valid provider + name values.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

nameREQUIRED
string

Display name for the agent.

welcome_messageREQUIRED
string

First message the agent speaks.

agent_promptREQUIRED
string

LLM system prompt that defines the agent personality.

language
string

Language code. e.g. en-US, hi-IN.

model
object

LLM config. If omitted, defaults to AZURE / gpt-4.1-mini. See GET /discovery/models for structure.

voice
object

TTS voice config. If omitted, defaults to ELEVENLABS / Riya Rao. See GET /discovery/voices for structure.

transcription
object

STT transcription config. See GET /discovery/transcription for structure.

stt_mode
string

Sarvam STT output mode: translit | transcribe | codemix. Default: translit.

ambient_noise_type
string

Background ambient bed under TTS. Default: traffic. Use none to disable. See GET /discovery/ambient-noise-types.

ambient_noise_volume
number

Ambient mix level in [0, 1]. Default: 0.35. Ignored when type is none.

data_collection
object

Post-call extraction config.

duty
string

Agent role: support | sales | hr etc.

enable_lid_detection
boolean

Enable LID system.

lid_allowed_languages
array

Allowed ISO 639-1 codes.

active
boolean

Start active.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/assistant' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "Support Bot",5  "welcome_message": "Hey! How can I help you?",6  "agent_prompt": "<agent_prompt>",7  "language": "en-US",8  "model": {9    "provider": "AZURE",10    "model": "gpt-4.1-mini"11  },12  "voice": {13    "provider": "ELEVENLABS",14    "name": "Riya Rao"15  },16  "transcription": {17    "provider": "DEEPGRAM",18    "model": "nova-2"19  },20  "stt_mode": "translit",21  "ambient_noise_type": "traffic",22  "ambient_noise_volume": 0.35,23  "data_collection": {24    "call_cut": [],25    "required_values": {}26  },27  "duty": "support",28  "enable_lid_detection": true,29  "lid_allowed_languages": [30    "hi",31    "en"32  ],33  "active": false34}'

Expected Response — 200 OK

json
1{2  "id": "new-agent-uuid",3  "name": "Support Bot",4  "client_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",5  "created_at": "2026-03-13T09:00:00Z"6}

HTTP Errors

401
UNAUTHORIZED

No valid API key or JWT.

422
VALIDATION_ERROR

model/voice/transcription provider+name not found in active records. Check /discovery/models and /discovery/voices.

500
PERSISTENCE_ERROR

Failed to persist the new agent.

Update Agent

PATCH
#
PATCHhttps://api.vanira.io/assistant/:id
Update any subset of an agent's configuration. All fields are optional — only the ones you send will be updated.
Pass model, voice, or transcription as structured objects to change the LLM, TTS, or STT configuration. Invalid provider/name combinations return 422.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the agent to update.

Body Parameters

name
string

New display name.

agent_prompt
string

Updated system prompt.

welcome_message
string

Updated opening message.

language
string

Language code.

model
object

Update LLM. { provider, model }. See GET /discovery/models.

voice
object

Update TTS voice. { provider, name }. See GET /discovery/voices.

transcription
object

Update STT config. { provider, model }.

stt_mode
string

Sarvam STT output mode: translit | transcribe | codemix.

ambient_noise_type
string

Ambient bed: none | quiet_office | call_center | traffic.

ambient_noise_volume
number

Ambient mix level in [0, 1]. Use 0 when type is none.

temperature
number

LLM temperature (0–2).

speed
number

TTS speed multiplier (0.25–4).

enable_lid_detection
boolean

Toggle LID system.

lid_allowed_languages
array

Update allowed languages.

active
boolean

Activate or deactivate.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/assistant/caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "<name>",5  "agent_prompt": "<agent_prompt>",6  "welcome_message": "<welcome_message>",7  "language": "<language>",8  "model": {9    "provider": "AZURE_REALTIME",10    "model": "gpt-4o-mini-realtime-preview"11  },12  "voice": {13    "provider": "ELEVENLABS",14    "name": "Miranda English Voice US"15  },16  "transcription": {17    "provider": "SARVAM",18    "model": "saaras:v3"19  },20  "stt_mode": "codemix",21  "ambient_noise_type": "quiet_office",22  "ambient_noise_volume": 0.35,23  "temperature": null,24  "speed": null,25  "enable_lid_detection": false,26  "lid_allowed_languages": "<lid_allowed_languages>",27  "active": false28}'

Expected Response — 200 OK

json
1{2  "id": "caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5",3  "name": "Updated Agent Name",4  "active": true,5  "updated_at": "2026-03-13T09:51:00Z"6}

HTTP Errors

401
UNAUTHORIZED

No valid API key or JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

422
VALIDATION_ERROR

Invalid model/voice/transcription config. Check /discovery/models and /discovery/voices for valid values.

Delete Agent

DELETE
#
DELETEhttps://api.vanira.io/assistant/:id
Permanently delete an agent. Irreversible.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the agent to delete.

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/assistant/caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "id": "caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5",3  "name": "Deleted Agent"4}

HTTP Errors

401
UNAUTHORIZED

No valid API key or JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

422
VALIDATION_ERROR

Invalid UUID format.

Get Agent Widget

GET
#
GEThttps://api.vanira.io/assistant/:id/widget
Fetch the widget embed configuration for an agent. Auto-creates with defaults if none exists.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the agent.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/assistant/caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5/widget'

Expected Response — 200 OK

json
1{2  "id": "widget-uuid",3  "agent_id": "caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5",4  "mode": "voice_only",5  "primary_color": "#6366f1",6  "secondary_color": "#a855f7",7  "created_at": "2026-04-27T12:00:00Z"8}

HTTP Errors

404
AGENT_NOT_FOUND

No agent with this UUID.

Update Agent Widget

PATCH
#
PATCHhttps://api.vanira.io/assistant/widget/:widget_id
Update widget appearance (colors, mode, icon).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

widget_idREQUIRED
uuid

Widget UUID (from Get Agent Widget response).

Body Parameters

mode
string

voice_only | chat_only | chat_voice | avatar_only | chat_avatar.

primary_color
string

Primary hex color. e.g. #6366f1.

secondary_color
string

Secondary hex color.

icon
string

Widget icon identifier.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/assistant/widget/a4fbac73-3f8c-4e3e-a742-195e1b68d2c3' \2  -H "Content-Type: application/json" \3  -d '{4  "mode": "<mode>",5  "primary_color": "<primary_color>",6  "secondary_color": "<secondary_color>",7  "icon": "<icon>"8}'

Expected Response — 200 OK

json
1{2  "id": "widget-uuid",3  "mode": "chat_voice",4  "primary_color": "#ff0000",5  "updated_at": "2026-04-27T12:05:00Z"6}

HTTP Errors

404
WIDGET_NOT_FOUND

Widget not found.

422
VALIDATION_ERROR

Invalid field value.

List Data Collections

GET
#
GEThttps://api.vanira.io/assistant/:id/data-collection
Fetch all post-call data extraction parameters for an agent. These define what information the AI should extract from a conversation (e.g., email, sentiment, intent).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the agent.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/assistant/caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5/data-collection'

Expected Response — 200 OK

json
1{2  "collections": [3    {4      "id": "766c8b9d-5a4e-4f3d-9c8b-7d6e5f4a3b2c",5      "agent_id": "caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5",6      "key": "lead_email",7      "prompt": "Extract the email address mentioned by the user.",8      "data_type": "string",9      "store_to_prospect_data": true,10      "is_active": true11    }12  ]13}

HTTP Errors

404
AGENT_NOT_FOUND

Agent not found.

Create Data Collection

POST
#
POSThttps://api.vanira.io/assistant/:id/data-collection
Add a new post-call data extraction parameter to an agent.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the agent.

Body Parameters

keyREQUIRED
string

Unique key for this field in extraction results.

promptREQUIRED
string

Instructions for the AI to extract this value.

data_type
string

string | boolean | number | enum. Default: string.

enum_values
array

List of valid values if data_type is enum.

store_to_prospect
boolean

Whether to store this value in the main prospect record.

prospect_column_name
string

The specific column name in the prospect table to map to.

store_to_prospect_data
boolean

Whether to store in the custom prospect_data table (key-value storage).

prospect_data_key
string

The key to use when storing in prospect_data.

store_directly_to_prospect
boolean

Flag for direct storage logic.

is_active
boolean

Whether to enable this extraction parameter.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/assistant/<id>/data-collection' \2  -H "Content-Type: application/json" \3  -d '{4  "key": "interested_in_demo",5  "prompt": "Did the user express interest in a demo? Answer yes or no.",6  "data_type": "enum",7  "enum_values": [8    "Interested",9    "Not Interested",10    "Call Back Later"11  ],12  "store_to_prospect": false,13  "prospect_column_name": "<prospect_column_name>",14  "store_to_prospect_data": false,15  "prospect_data_key": "<prospect_data_key>",16  "store_directly_to_prospect": false,17  "is_active": false18}'

Expected Response — 200 OK

json
1{2  "id": "766c8b9d-5a4e-4f3d-9c8b-7d6e5f4a3b2c",3  "key": "interested_in_demo",4  "prompt": "Did the user express interest in a demo? Answer yes or no.",5  "data_type": "boolean",6  "agent_id": "caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5",7  "created_at": "2026-05-09T12:00:00Z"8}

HTTP Errors

400
BAD_REQUEST

Invalid configuration.

404
AGENT_NOT_FOUND

Agent not found.

Update Data Collection

PATCH
#
PATCHhttps://api.vanira.io/assistant/data-collection/:collection_id
Update an existing data extraction parameter.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

collection_idREQUIRED
uuid

UUID of the collection parameter.

Body Parameters

prompt
string

Updated extraction prompt.

data_type
string

Update the expected data type.

enum_values
array

Update allowed enum values.

store_to_prospect
boolean

Update main record storage setting.

is_active
boolean

Enable/disable this parameter.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/assistant/data-collection/<collection_id>' \2  -H "Content-Type: application/json" \3  -d '{4  "prompt": "<prompt>",5  "data_type": "<data_type>",6  "enum_values": "<enum_values>",7  "store_to_prospect": false,8  "is_active": false9}'

Expected Response — 200 OK

json
1{2  "id": "766c8b9d-5a4e-4f3d-9c8b-7d6e5f4a3b2c",3  "key": "lead_email",4  "is_active": false,5  "updated_at": "2026-05-09T12:05:00Z"6}

HTTP Errors

404
DATA_COLLECTION_NOT_FOUND

Parameter not found.

Delete Data Collection

DELETE
#
DELETEhttps://api.vanira.io/assistant/data-collection/:collection_id
Remove a data extraction parameter from an agent.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

collection_idREQUIRED
uuid

UUID of the collection parameter.

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/assistant/data-collection/<collection_id>' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "success": true,3  "id": "766c8b9d-5a4e-4f3d-9c8b-7d6e5f4a3b2c"4}

HTTP Errors

404
DATA_COLLECTION_NOT_FOUND

Parameter not found.

List Media Handlers

GET
#
GEThttps://api.vanira.io/assistant/:id/media-handlers
Fetch vision media handlers for an agent (routes uploads by reason tag into the LLM).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the agent.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/assistant/<id>/media-handlers'

Expected Response — 200 OK

json
1{2  "handlers": [3    {4      "id": "m1",5      "agent_id": "caaa5b2a-...",6      "reason": "kyc_photo",7      "route": "vision",8      "inject_as": "system",9      "interrupt": true10    }11  ]12}

HTTP Errors

404
AGENT_NOT_FOUND

Agent not found.

Create Media Handler

POST
#
POSThttps://api.vanira.io/assistant/:id/media-handlers
Create a vision media handler — routes client.uploadMedia() payloads by reason tag into process_media.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the agent.

Body Parameters

reasonREQUIRED
string

The routing category/tag sent by the client SDK (e.g. kyc_photo).

route
string

Must be "vision". Media is processed in-session over WebRTC — not forwarded to external URLs.

inject_asREQUIRED
string

"system" or "user". How the parsed media result is injected into the prompt context.

interruptREQUIRED
boolean

Whether to interrupt the agent mid-sentence when media is processed.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/assistant/<id>/media-handlers' \2  -H "Content-Type: application/json" \3  -d '{4  "reason": "kyc_photo",5  "route": "vision",6  "inject_as": "system",7  "interrupt": true8}'

Expected Response — 200 OK

json
1{2  "id": "new-handler-uuid",3  "reason": "kyc_photo",4  "route": "vision",5  "inject_as": "system",6  "interrupt": true7}

HTTP Errors

400
BAD_REQUEST

Invalid handler configuration.

404
AGENT_NOT_FOUND

Agent not found.

Update Media Handler

PATCH
#
PATCHhttps://api.vanira.io/assistant/media-handlers/:id
Update an existing media handler configuration.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the media handler.

Body Parameters

reason
string

Updated routing category.

inject_as
string

Updated prompt injection mode.

interrupt
boolean

Update interrupt behavior.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/assistant/media-handlers/<id>' \2  -H "Content-Type: application/json" \3  -d '{4  "reason": "<reason>",5  "inject_as": "<inject_as>",6  "interrupt": false7}'

Expected Response — 200 OK

json
1{2  "id": "handler-uuid",3  "reason": "updated_kyc_photo",4  "updated_at": "2026-05-09T12:05:00Z"5}

HTTP Errors

404
MEDIA_HANDLER_NOT_FOUND

Handler not found.

Delete Media Handler

DELETE
#
DELETEhttps://api.vanira.io/assistant/media-handlers/:id
Remove a media handler from an agent.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the media handler.

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/assistant/media-handlers/<id>' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "success": true3}

HTTP Errors

404
MEDIA_HANDLER_NOT_FOUND

Handler not found.

Outbound Agent Setup

POST
#
POSThttps://api.vanira.io/assistant/outbound-setup
Generate a starter outbound agent prompt, welcome message, and suggested name from product/goal inputs.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

purposeREQUIRED
string

High-level purpose of the agent.

product_serviceREQUIRED
string

What you sell / offer.

call_goalREQUIRED
string

Desired call outcome.

target_audience
string

Who is being called.

post_call_steps
string

What happens after the call.

company_name
string

Your company name.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/assistant/outbound-setup' \2  -H "Content-Type: application/json" \3  -d '{4  "purpose": "Book product demos",5  "product_service": "Vanira voice AI",6  "call_goal": "Schedule a 30-min demo",7  "target_audience": "SMB founders",8  "post_call_steps": "<post_call_steps>",9  "company_name": "Acme"10}'

Expected Response — 200 OK

json
1{2  "agent_prompt": "You are an outbound sales agent...",3  "welcome_message": "Hi, this is Priya from Acme...",4  "suggested_name": "Demo Booking Agent"5}

HTTP Errors

422
VALIDATION_ERROR

Missing required fields.

Duplicate Agent

POST
#
POSThttps://api.vanira.io/assistant/duplicate-agent
Clone an existing agent into a new agent. Requires Kinde JWT (dashboard session) — API keys alone return 403.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

agent_idREQUIRED
uuid

Source agent UUID.

name
string

Optional name for the clone.

active
boolean

Whether the clone starts active.

make_public
boolean

Whether the clone is public.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/assistant/duplicate-agent' \2  -H "Content-Type: application/json" \3  -d '{4  "agent_id": "<agent_id>",5  "name": "<name>",6  "active": false,7  "make_public": false8}'

Expected Response — 200 OK

json
1{2  "id": "new-agent-uuid-...",3  "name": "Sales Rep (copy)",4  "active": true5}

HTTP Errors

403
FORBIDDEN

API key auth not allowed — use dashboard JWT.

404
AGENT_NOT_FOUND

Source agent not found.

Import Public Agent

POST
#
POSThttps://api.vanira.io/assistant/:id/import
Import a public shared agent into your account. Requires Kinde JWT. Path :id is the public agent UUID.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Public agent UUID to import.

Body Parameters

name
string

Optional override name for the imported agent.

active
boolean

Whether imported agent starts active.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/assistant/<id>/import' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "<name>",5  "active": false6}'

Expected Response — 200 OK

json
1{2  "id": "imported-agent-uuid-...",3  "name": "Imported Agent",4  "active": true5}

HTTP Errors

403
FORBIDDEN

API key auth not allowed — use dashboard JWT.

404
AGENT_NOT_FOUND

Public agent not found.

Toggle Public Sharing

PATCH
#
PATCHhttps://api.vanira.io/assistant/:id/toggle-public
Mark an owned agent as public or private for the share/import gallery.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Agent UUID (must be owned).

Query Parameters

is_publicREQUIRED
boolean

true to publish, false to unpublish.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/assistant/<id>/toggle-public' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "id": "caaa5b2a-...",3  "is_public": true4}

HTTP Errors

404
AGENT_NOT_FOUND

Agent not found or not owned.

List Public Agents

GET
#
GEThttps://api.vanira.io/assistant/public/list
Public gallery of shared agents. No API key required.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Query Parameters

limit
number

Page size.

offset
number

Offset.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/assistant/public/list?limit=20&offset=0'

Expected Response — 200 OK

json
1{2  "agents": [3    { "id": "public-agent-uuid-...", "name": "KYC Demo", "active": true }4  ]5}

Get Public Agent

GET
#
GEThttps://api.vanira.io/assistant/public/:id
Fetch a public agent by ID for preview/import. No API key required.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Public agent UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/assistant/public/<id>'

Expected Response — 200 OK

json
1{2  "id": "public-agent-uuid-...",3  "name": "KYC Demo",4  "active": true,5  "model": { "provider": "AZURE", "model": "gpt-4.1-mini" }6}

HTTP Errors

404
AGENT_NOT_FOUND

Public agent not found.

List Agent Parts

GET
#
GEThttps://api.vanira.io/assistant/:agent_id/parts
List key/value agent parts (prompt fragments / config bags) for an agent.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/assistant/<agent_id>/parts'

Expected Response — 200 OK

json
1{2  "parts": [3    { "key": "closing", "value": "Thanks for your time!", "agent_id": "caaa5b2a-..." }4  ]5}

HTTP Errors

404
AGENT_NOT_FOUND

Agent not found.

Upsert Agent Part

POST
#
POSThttps://api.vanira.io/assistant/:agent_id/parts
Create or update a key/value part on an agent.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

Body Parameters

keyREQUIRED
string

Part key.

valueREQUIRED
string

Part value.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/assistant/<agent_id>/parts' \2  -H "Content-Type: application/json" \3  -d '{4  "key": "closing",5  "value": "Thanks for your time!"6}'

Expected Response — 200 OK

json
1{2  "key": "closing",3  "value": "Thanks for your time!",4  "agent_id": "caaa5b2a-..."5}

HTTP Errors

404
AGENT_NOT_FOUND

Agent not found.

Delete Agent Part

DELETE
#
DELETEhttps://api.vanira.io/assistant/:agent_id/parts/:key
Delete a part by key.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

keyREQUIRED
string

Part key.

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/assistant/<agent_id>/parts/closing' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{ "status": "success" }

HTTP Errors

404
NOT_FOUND

Agent or part not found.

Get Vision LLM Options

GET
#
GEThttps://api.vanira.io/assistant/:agent_id/vision-llm-options
Fetch live-vision / multimodal LLM options for an agent.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/assistant/<agent_id>/vision-llm-options'

Expected Response — 200 OK

json
1{2  "enabled": true,3  "vision_provider": "AZURE",4  "vision_model": "gpt-4.1-mini",5  "live_vision_scope": "agent",6  "fps": 17}

HTTP Errors

404
AGENT_NOT_FOUND

Agent not found.

Update Vision LLM Options

PUT
#
PUThttps://api.vanira.io/assistant/:agent_id/vision-llm-options
Create or replace vision LLM options for an agent.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

Body Parameters

enabledREQUIRED
boolean

Enable live vision.

vision_provider
string

Vision model provider.

vision_model
string

Vision model name.

live_vision_scope
string

Scope for live vision.

fps
number

Capture FPS.

Implementation Example

Environment
1curl -X PUT 'https://api.vanira.io/assistant/<agent_id>/vision-llm-options' \2  -H "Content-Type: application/json" \3  -d '{4  "enabled": true,5  "vision_provider": "AZURE",6  "vision_model": "gpt-4.1-mini",7  "live_vision_scope": "agent",8  "fps": 19}'

Expected Response — 200 OK

json
1{2  "enabled": true,3  "vision_provider": "AZURE",4  "vision_model": "gpt-4.1-mini"5}

HTTP Errors

404
AGENT_NOT_FOUND

Agent not found.

422
VALIDATION_ERROR

Invalid vision options.

Create Call (SIP or Web)

POST
#
POSThttps://api.vanira.io/calls/create
Unified endpoint to create an outbound SIP call or a WebRTC web call.
  • *Authentication**
All requests require an X-API-Key header:
  • sk_live_* — secret key (server-side). Can create both web and sip calls.
  • pk_live_* — publishable key (browser/widget). Can only create web calls. Use * to allow all origins, or set domains to restrict usage.
  • *SIP vs Web**
Set type to "sip" for outbound phone calls or "web" for in-browser WebRTC sessions.
For SIP calls, sip_data (phone number + name) is required.
  • Dynamic DID Selection: If sip_data.from_number is provided, it must be a provisioned number owned by the client.
  • Automated Fallback: If sip_data.from_number is omitted, the backend automatically selects a default number from the Vanira managed pool.
  • Strict Validation: All phone numbers are strictly validated against E.164 format (7-15 digits).
For web calls, prospect_id is optional — a new anonymous prospect is created if omitted.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

agent_idREQUIRED
uuid

UUID of the voice agent that will handle the call.

typeREQUIRED
string

"web" for an in-browser WebRTC session. "sip" for an outbound phone call. Note: pk_live_* keys can only create web calls.

sip_data
object

Required when type is "sip". Nested object containing the call destination. See sip_data.to and sip_data.name below.

sip_data.to
string

E.164 formatted destination phone number. Required when type is "sip". Example: +919182517283 (country code + number, no spaces or dashes).

sip_data.name
string

Display name of the person being called. Used for prospect creation and call logging. Defaults to "Unknown" if omitted.

sip_data.from_number
string

Optional. The provisioned phone number (E.164) to dial from. If omitted, Vanira uses its shared pool default.

prospect_id
uuid

Optional. Link the call to an existing prospect record. If omitted for web calls, an anonymous prospect is created automatically.

welcome_message
string

Optional. First message spoken when the call connects. Stored on the call row; overrides the agent default when set.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/calls/create' \2  -H "Content-Type: application/json" \3  -d '{4  "agent_id": "919801d9-f357-4033-8ea0-97de12a989c2",5  "type": "web",6  "sip_data": {7    "to": "+919182517283",8    "name": "John Doe"9  },10  "sip_data.to": "+919182517283",11  "sip_data.name": "John Doe",12  "sip_data.from_number": "+918071387205",13  "prospect_id": "7fdc9111-2b35-4252-a85c-781c37470ac0",14  "welcome_message": "Hi Ravi — ready to start your tutoring session?"15}'

Expected Response — 200 OK

json
1// Web call response2{3  "call_id": "da4ca1e9-e488-4059-b1d2-fdc348d26950",4  "status": "in-progress",5  "worker_url": "https://<worker>.vanira.io/webrtc?agent=919801d9..._da4ca1e9..."6}7 8// SIP call response9{10  "call_id": "6fdc9111-2b35-4252-a85c-781c37470ac0",11  "status": "triggered",12  "worker_url": null13}

Response Schema Details

call_idREQUIRED
uuid

Unique identifier for the created call record.

statusREQUIRED
string

"in-progress" for web calls. "triggered" for SIP calls.

worker_url
string

WebRTC worker URL to connect to. Only returned for type="web". Pass this to the Vanira SDK.

HTTP Errors

401
UNAUTHORIZED

No X-API-Key header provided.

401
INVALID_API_KEY

API key is invalid, revoked, or the secret does not match.

402
INSUFFICIENT_CREDITS

Client balance is below the overdraft floor (default -1000 credits), or Saathi soft overdraft floor exceeded.

403
INSUFFICIENT_SCOPE

Publishable key (pk_live_*) attempted to create a SIP call.

404
AGENT_NOT_FOUND

No agent exists with the provided agent_id.

404
PROSPECT_NOT_FOUND

The provided prospect_id does not exist.

422
VALIDATION_ERROR

Invalid E.164 format (7-15 digits) or missing required fields.

502
UPSTREAM_SERVICE_TIMEOUT

SIP gateway is unreachable or returned an error.

500
DATABASE_ERROR

Unexpected server error.

List Calls

GET
#
GEThttps://api.vanira.io/calls
Retrieve a paginated list of calls for the authenticated client.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Publishable keys cannot access call history.
  • *Filtering**
Use query params to filter by agent, status, or paginate. Results are always scoped to the authenticated client — you cannot see other clients' calls.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Query Parameters

agent_id
uuid

Filter calls by a specific agent UUID.

status
string

Filter by call status: triggered | in-progress | completed | failed.

limit
number

Number of results to return. Default 100, max 500.

offset
number

Number of results to skip for pagination.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/calls?agent_id=919801d9-f357-4033-8ea0-97de12a989c2&status=completed&limit=25&offset=0'

Expected Response — 200 OK

json
1{2  "calls": [3    {4      "id": "da4ca1e9-e488-4059-b1d2-fdc348d26950",5      "agent_id": "919801d9-f357-4033-8ea0-97de12a989c2",6      "client_id": "91b5f2de-9e01-4520-837f-58f284e40a4c",7      "phone_to": "+917268030283",8      "phone_from": null,9      "status": "completed",10      "direction": "outbound",11      "type": "sip_call",12      "created_at": "2026-05-01T10:00:00Z",13      "duration": 142,14      "recording_url": null,15      "is_call_successful_according_to_agent_criteria": true,16      "prospect": { "id": "<uuid>", "name": "John Doe", "phone": "+917268030283" },17      "agent": { "id": "919801d9-...", "name": "Support Agent" },18      "call_data": [{ "key": "sentiment", "value": "positive" }]19    }20  ],21  "total": 330822}

Response Schema Details

callsREQUIRED
array

Array of call objects.

totalREQUIRED
number

Total matching calls across all pages (use for pagination UI).

calls[].idREQUIRED
uuid

Call UUID.

calls[].statusREQUIRED
string

triggered | in-progress | completed | failed.

calls[].direction
string

inbound (web) or outbound (SIP).

calls[].type
string

web_call or sip_call.

calls[].duration
number

Call duration in seconds.

calls[].recording_url
string

URL to the call recording if available.

calls[].prospect
object

Linked prospect name and phone.

calls[].agent
object

Agent id and name.

calls[].call_data
array

Structured key/value output from the agent (sentiment, outcome, etc.).

HTTP Errors

401
UNAUTHORIZED

No X-API-Key header provided.

401
INVALID_API_KEY

API key is invalid or revoked.

403
INSUFFICIENT_SCOPE

Publishable key (pk_live_*) cannot access call history.

500
DATABASE_ERROR

Unexpected server error.

Get Call Details

GET
#
GEThttps://api.vanira.io/calls/:id
Retrieve full details for a specific call by its UUID, including the linked prospect (with key/value prospect data) and the agent with its client information.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Publishable keys (pk_live_*) cannot access call details.
The authenticated client must own the call — requests for calls belonging to other clients return 404.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the call to retrieve. Returned by POST /calls/create as call_id.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/calls/6fdc9111-2b35-4252-a85c-781c37470ac0'

Expected Response — 200 OK

json
1{2  "id": "6fdc9111-2b35-4252-a85c-781c37470ac0",3  "agent_id": "919801d9-f357-4033-8ea0-97de12a989c2",4  "client_id": "91b5f2de-9e01-4520-837f-58f284e40a4c",5  "phone_from": "+919182517283",6  "phone_to": "+917268030283",7  "status": "completed",8  "call_triggered_at": "2026-03-13T10:00:00Z",9  "extra_details": { "duration": 142 },10  "provider_call_id": "prov-abc-123",11  "prospect": {12    "id": "<prospect-uuid>",13    "name": "John Doe",14    "phone": "+919182517283",15    "prospect_data": [16      { "key": "company", "value": "Acme Corp" }17    ]18  },19  "agent": {20    "id": "919801d9-f357-4033-8ea0-97de12a989c2",21    "client": {22      "name": "Demo Client",23      "base_prospect_group_id": "<group-uuid>"24    }25  }26}

Response Schema Details

idREQUIRED
uuid

Call UUID.

agent_idREQUIRED
uuid

UUID of the agent that handled the call.

client_idREQUIRED
uuid

UUID of the client who owns this call.

phone_from
string

Caller's phone number.

phone_to
string

Dialled phone number.

status
string

Call status: triggered | in-progress | completed | failed.

call_triggered_at
string

ISO 8601 timestamp when the call was initiated.

extra_details
object

Arbitrary metadata returned by the telephony provider (duration, recording_url, etc.).

provider_call_id
string

Provider-side call identifier.

prospect
object

Linked prospect with name, phone, and prospect_data key/value pairs.

agent
object

Agent info including nested client name and base_prospect_group_id.

HTTP Errors

401
UNAUTHORIZED

No X-API-Key header provided.

401
INVALID_API_KEY

API key is invalid or revoked.

403
INSUFFICIENT_SCOPE

Publishable key (pk_live_*) cannot access call details.

404
CALL_NOT_FOUND

Call not found, or the authenticated client does not own this call.

422
VALIDATION_ERROR

id path parameter is not a valid UUID.

500
DATABASE_ERROR

Unexpected server error.

Get Call Media

GET
#
GEThttps://api.vanira.io/calls/:id/media
List media captures (screenshots / uploads) associated with a call, including signed media URLs where available.
  • *Authentication**
Requires X-API-Key: sk_live_* or Bearer JWT with calls:read.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Call UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/calls/6fdc9111-2b35-4252-a85c-781c37470ac0/media'

Expected Response — 200 OK

json
1[2  {3    "media_id": "media-uuid-...",4    "blob_path": "calls/.../frame.jpg",5    "source": "live_vision",6    "captured_at": "2026-03-13T10:01:00Z",7    "reason": "kyc_photo",8    "media_url": "https://..."9  }10]

Response Schema Details

media_idREQUIRED
uuid

Media row UUID.

blob_pathREQUIRED
string

Storage path for the blob.

source
string

Capture source (e.g. live_vision, upload).

media_url
string

Signed URL when available.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

404
CALL_NOT_FOUND

Call not found or not owned.

Get Call Media Usage

GET
#
GEThttps://api.vanira.io/calls/:id/media-usage
Shows how captured media was consumed by agent tools / vision (action name, summary, timestamps).
  • *Authentication**
Requires calls:read.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Call UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/calls/<id>/media-usage'

Expected Response — 200 OK

json
1[2  {3    "media_id": "media-uuid-...",4    "action_name": "analyze_document",5    "vision_summary": "Aadhaar front detected",6    "used_at": "2026-03-13T10:01:05Z"7  }8]

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

404
CALL_NOT_FOUND

Call not found or not owned.

Get Media SAS URL

GET
#
GEThttps://api.vanira.io/calls/media-sas
Mint a short-lived SAS / presigned URL for a media blob path returned from call media endpoints.
  • *Authentication**
Requires calls:read.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Query Parameters

blob_pathREQUIRED
string

Blob path from call media.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/calls/media-sas?blob_path=calls%2F...%2Fframe.jpg'

Expected Response — 200 OK

json
1{2  "url": "https://storage.example.com/...?sv=..."3}

Response Schema Details

urlREQUIRED
string

Time-limited download URL.

HTTP Errors

400
BAD_REQUEST

Missing blob_path.

401
UNAUTHORIZED

Missing or invalid API key.

404
NOT_FOUND

Blob path not found or not owned.

Upload & Create Campaign

POST
#
POSThttps://api.vanira.io/campaigns
Create a new outbound campaign, bulk-insert prospects, and allocate DIDs. Note: You must either provide from_numbers or set use_vanira_managed to true; otherwise, creation will fail.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

nameREQUIRED
string

The name of the campaign

agent_idREQUIRED
uuid

ID of the voice agent to use

candidatesREQUIRED
array

List of prospects including name and phone number

providerREQUIRED
string

The voice provider to use (e.g., vonage, twilio)

timezoneREQUIRED
string

Timezone for the campaign scheduling

call_hours_startREQUIRED
string

Daily start time for calls (HH:MM:SS)

call_hours_endREQUIRED
string

Daily end time for calls (HH:MM:SS)

call_daysREQUIRED
array

Days of the week to make calls

max_concurrent_callsREQUIRED
number

Maximum number of simultaneous calls

call_timeout_secondsREQUIRED
number

Seconds to wait before considering a call timed out

start_campaignREQUIRED
boolean

Whether to start the campaign immediately after upload

from_numbers
array

Optional list of E.164 phone numbers to use as Caller IDs. System will resolve and allocate them automatically.

use_vanira_managed
boolean

Optional. If true, the campaign will also use Vanira internal managed numbers.

retry_failed_callsREQUIRED
boolean

Retry calls that failed (e.g. error/network issue)

max_retries_failedREQUIRED
number

Maximum number of retries for failed calls

retry_delay_failed_secondsREQUIRED
number

Seconds to wait before retrying a failed call

retry_busy_callsREQUIRED
boolean

Retry calls where the line was busy

max_retries_busyREQUIRED
number

Maximum number of retries for busy calls

retry_delay_busy_secondsREQUIRED
number

Seconds to wait before retrying a busy call

retry_no_answer_callsREQUIRED
boolean

Retry calls where there was no answer

max_retries_no_answerREQUIRED
number

Maximum number of retries for no-answer calls

retry_delay_no_answer_secondsREQUIRED
number

Seconds to wait before retrying a no-answer call

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/campaigns' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "Q1 Feedback Survey",5  "agent_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",6  "candidates": [7    {8      "name": "John Doe",9      "phone": "+1234567890"10    }11  ],12  "provider": "vonage",13  "timezone": "Asia/Kolkata",14  "call_hours_start": "09:00:00",15  "call_hours_end": "18:00:00",16  "call_days": [17    "Monday",18    "Tuesday",19    "Wednesday",20    "Thursday",21    "Friday"22  ],23  "max_concurrent_calls": 5,24  "call_timeout_seconds": 60,25  "start_campaign": true,26  "from_numbers": [27    "+918071387205",28    "+919876543210"29  ],30  "use_vanira_managed": true,31  "retry_failed_calls": true,32  "max_retries_failed": 3,33  "retry_delay_failed_seconds": 300,34  "retry_busy_calls": true,35  "max_retries_busy": 2,36  "retry_delay_busy_seconds": 180,37  "retry_no_answer_calls": true,38  "max_retries_no_answer": 3,39  "retry_delay_no_answer_seconds": 60040}'

Expected Response — 200 OK

json
1{2  "success": true,3  "campaign_id": "c1234567-89ab-cdef-0123-456789abcdef",4  "total_prospects": 2,5  "message": "Campaign created successfully",6  "started": false7}

Response Schema Details

successREQUIRED
boolean

Always true on success.

campaign_idREQUIRED
uuid

UUID of the created campaign.

total_prospectsREQUIRED
number

Number of prospects added.

messageREQUIRED
string

Human-readable status message.

startedREQUIRED
boolean

True if campaign was auto-started.

HTTP Errors

400
validation_error

More than 50 candidates provided.

400
bad_request

No Caller IDs provided. You must either provide from_numbers or set use_vanira_managed to true.

422
BAD_REQUEST_FORMAT

Missing required fields (agent_id, name, candidates).

404
AGENT_NOT_FOUND

Agent not found or agent has no associated client.

500
INTERNAL_SERVER_ERROR

Failed to create prospect group or insert prospects.

502
UPSTREAM_SERVICE_ERROR

Campaign API or SIP gateway is unreachable.

Start Campaign

POST
#
POSThttps://api.vanira.io/campaigns/:id/start
Transition a campaign from draft or paused to active (running) status. Migrated from n8n to the Python FastAPI backend.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the campaign to start.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/campaigns/1a817016-a3f5-41c1-995c-c74a5fb33720/start' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "success": true,3  "campaign_id": "1a817016-a3f5-41c1-995c-c74a5fb33720",4  "status": "active",5  "message": "Campaign started successfully",6  "extra_data": {7    "id": "1a817016-a3f5-41c1-995c-c74a5fb33720",8    "status": "active"9  }10}

Response Schema Details

successREQUIRED
boolean

Always true on success.

campaign_idREQUIRED
uuid

UUID of the campaign.

status
string

New campaign status returned by the Campaign API.

messageREQUIRED
string

Human-readable result.

extra_data
object

Raw upstream Campaign API response.

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found or not owned by the authenticated client.

422
BAD_REQUEST_FORMAT

Campaign ID is not a valid UUID.

502
gateway_error

Campaign API unreachable or returned an error.

Pause Campaign

POST
#
POSThttps://api.vanira.io/campaigns/:id/pause
Temporarily stop all outgoing calls for a running campaign. Migrated from n8n to the Python FastAPI backend.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the campaign to pause.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/campaigns/1a817016-a3f5-41c1-995c-c74a5fb33720/pause' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "success": true,3  "campaign_id": "1a817016-a3f5-41c1-995c-c74a5fb33720",4  "status": "paused",5  "message": "Campaign paused successfully",6  "extra_data": {7    "id": "1a817016-a3f5-41c1-995c-c74a5fb33720",8    "status": "paused"9  }10}

Response Schema Details

successREQUIRED
boolean

Always true on success.

campaign_idREQUIRED
uuid

UUID of the campaign.

status
string

New status (paused).

messageREQUIRED
string

Human-readable result.

extra_data
object

Raw upstream Campaign API response.

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found or not owned by the authenticated client.

422
BAD_REQUEST_FORMAT

Campaign ID is not a valid UUID.

502
gateway_error

Campaign API unreachable or returned an error (e.g. already paused).

Resume Campaign

POST
#
POSThttps://api.vanira.io/campaigns/:id/resume
Restart a paused campaign and resume outgoing calls. Migrated from n8n to the Python FastAPI backend.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the campaign to resume.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/campaigns/1a817016-a3f5-41c1-995c-c74a5fb33720/resume' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "success": true,3  "campaign_id": "1a817016-a3f5-41c1-995c-c74a5fb33720",4  "status": "active",5  "message": "Campaign resumed successfully",6  "extra_data": {7    "id": "1a817016-a3f5-41c1-995c-c74a5fb33720",8    "status": "active"9  }10}

Response Schema Details

successREQUIRED
boolean

Always true on success.

campaign_idREQUIRED
uuid

UUID of the campaign.

status
string

New status (active).

messageREQUIRED
string

Human-readable result.

extra_data
object

Raw upstream Campaign API response.

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found or not owned by the authenticated client.

422
BAD_REQUEST_FORMAT

Campaign ID is not a valid UUID.

502
gateway_error

Campaign API unreachable or returned an error (e.g. not paused).

Schedule Campaign Start

POST
#
POSThttps://api.vanira.io/campaigns/:id/schedule-start
Set a future ISO 8601 datetime for the campaign to automatically start. Migrated from n8n to the Python FastAPI backend.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the campaign to schedule.

Body Parameters

scheduled_start_timeREQUIRED
string

ISO 8601 datetime for the auto-start (must be in the future).

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/campaigns/1a817016-a3f5-41c1-995c-c74a5fb33720/schedule-start' \2  -H "Content-Type: application/json" \3  -d '{4  "scheduled_start_time": "2026-04-01T09:00:00Z"5}'

Expected Response — 200 OK

json
1{2  "success": true,3  "campaign_id": "1a817016-a3f5-41c1-995c-c74a5fb33720",4  "scheduled_start_time": "2026-04-01T09:00:00Z",5  "status": "scheduled",6  "message": "Campaign start scheduled successfully",7  "extra_data": {8    "id": "1a817016-a3f5-41c1-995c-c74a5fb33720",9    "status": "scheduled"10  }11}

Response Schema Details

successREQUIRED
boolean

Always true on success.

campaign_idREQUIRED
uuid

UUID of the campaign.

scheduled_start_timeREQUIRED
string

Confirmed scheduled start time.

status
string

Campaign status after scheduling.

messageREQUIRED
string

Human-readable result.

extra_data
object

Raw upstream Campaign API response.

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found or not owned by the authenticated client.

422
BAD_REQUEST_FORMAT

Campaign ID is not a valid UUID, or scheduled_start_time is blank/missing.

502
gateway_error

Campaign API unreachable or returned an error (e.g. time in the past).

List Campaigns

GET
#
GEThttps://api.vanira.io/campaigns
Fetch a list of all campaigns for a specific client. Migrated to FastAPI backend.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/campaigns'

Expected Response — 200 OK

json
1{2  "data": [3    {4      "id": "1a817016-a3f5-41c1-995c-c74a5fb33720",5      "name": "Q1 Outreach",6      "status": "active",7      "agent_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",8      "client_id": "c2d3e4f5-1111-2222-3333-444455556666",9      "provider": "vobiz",10      "total_prospects": 150,11      "successful_calls": 45,12      "failed_calls": 12,13      "created_at": "2026-03-29T10:00:00Z",14      "updated_at": "2026-03-29T10:00:00Z"15    }16  ]17}

HTTP Errors

422
BAD_REQUEST_FORMAT

Invalid client_id format

Get Campaign Details

GET
#
GEThttps://api.vanira.io/campaigns/:id
Fetch complete details and configuration for a specific campaign. Migrated to FastAPI backend.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the campaign to fetch.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/campaigns/<id>'

Expected Response — 200 OK

json
1{2  "id": "1a817016-a3f5-41c1-995c-c74a5fb33720",3  "name": "Q1 Outreach",4  "status": "active",5  "max_concurrent_calls": 3,6  "timezone": "Asia/Kolkata",7  "call_timeout_seconds": 60,8  "allow_reschedule": true,9  "max_reschedules_per_prospect": 3,10  "reschedule_min_delay_hours": 1,11  "total_prospects": 150,12  "active_prospects": 2,13  "pending_prospects": 91,14  "is_hr_campaign": false,15  "created_at": "2026-03-29T10:00:00Z",16  "allocated_dids": [17    {18      "did_id": "09d89078-b9cc-452d-ae06-126d04239b73",19      "number": "918071387205",20      "max_concurrent_calls": 321    }22  ]23}

Response Schema Details

idREQUIRED
uuid

UUID of the campaign.

nameREQUIRED
string

Campaign name.

statusREQUIRED
string

Current status (draft, active, paused, scheduled, completed).

allocated_dids
array

List of phone numbers (Caller IDs) assigned to this campaign.

allocated_dids[].numberREQUIRED
string

The E.164 phone number.

total_prospects
number

Total number of contacts in the campaign.

active_prospects
number

Number of contacts currently being called.

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found

Update Campaign

PATCH
#
PATCHhttps://api.vanira.io/campaigns/:id
Modify campaign settings. Migrated to FastAPI backend.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the campaign to update.

Body Parameters

name
string

New name for the campaign

max_concurrent_calls
number

Maximum concurrent calls allowed

allow_reschedule
boolean

Whether to allow rescheduling calls

max_reschedules_per_prospect
number

Maximum reschedules allowed per prospect

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/campaigns/<id>' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "<name>",5  "max_concurrent_calls": null,6  "allow_reschedule": false,7  "max_reschedules_per_prospect": null8}'

Expected Response — 200 OK

json
1{2  "id": "1a817016-a3f5-41c1-995c-c74a5fb33720",3  "name": "Updated Campaign Name",4  "status": "paused",5  "updated_at": "2026-03-29T10:05:00Z"6}

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found

400
BAD_REQUEST

No fields provided

422
VALIDATION_ERROR

Invalid fields format

Upload CSV Import

POST
#
POSThttps://api.vanira.io/campaigns/imports
Upload a CSV/XLSX prospect file to start an async import job. Returns 202 with an import_id — poll status, then create a campaign from the import.
  • *Body** is multipart/form-data with file and agent_id.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

agent_idREQUIRED
uuid

Agent that will own the eventual campaign.

fileREQUIRED
string

CSV or XLSX file (multipart form field named file).

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/campaigns/imports' \2  -H "Content-Type: application/json" \3  -d '{4  "agent_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",5  "file": "<file>"6}'

Expected Response — 200 OK

json
1{2  "import_id": "imp-uuid-...",3  "status": "queued",4  "message": "Import queued"5}

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

422
VALIDATION_ERROR

Missing file or agent_id.

Get Import Status

GET
#
GEThttps://api.vanira.io/campaigns/imports/:import_id
Poll CSV import job status, progress, preview rows, and validation samples.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

import_idREQUIRED
uuid

Import job UUID from POST /campaigns/imports.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/campaigns/imports/<import_id>'

Expected Response — 200 OK

json
1{2  "import_id": "imp-uuid-...",3  "status": "completed",4  "progress": 100,5  "phase": "ready",6  "file_name": "prospects.csv",7  "summary": { "total_rows": 500, "valid": 480, "duplicates": 15, "invalid": 5 },8  "preview": [],9  "campaign_id": null,10  "error_message": null11}

HTTP Errors

404
IMPORT_NOT_FOUND

Import job not found.

Create Campaign from Import

POST
#
POSThttps://api.vanira.io/campaigns/imports/:import_id/campaign
Create a voice campaign using prospects from a completed import job. Body fields mirror campaign create (schedule, concurrency, DIDs, etc.).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

import_idREQUIRED
uuid

Completed import job UUID.

Body Parameters

nameREQUIRED
string

Campaign name.

providerREQUIRED
string

Voice provider (e.g. vonage).

timezoneREQUIRED
string

IANA timezone.

call_hours_startREQUIRED
string

Daily start (HH:MM:SS).

call_hours_endREQUIRED
string

Daily end (HH:MM:SS).

call_daysREQUIRED
array

Days of week.

max_concurrent_callsREQUIRED
number

Max simultaneous calls.

start_campaign
boolean

Start immediately after create.

from_numbers
array

Caller ID numbers (E.164).

use_vanira_managed
boolean

Also use Vanira managed DIDs.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/campaigns/imports/<import_id>/campaign' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "Q1 Import Campaign",5  "provider": "vonage",6  "timezone": "Asia/Kolkata",7  "call_hours_start": "09:00:00",8  "call_hours_end": "18:00:00",9  "call_days": [10    "Monday",11    "Tuesday",12    "Wednesday",13    "Thursday",14    "Friday"15  ],16  "max_concurrent_calls": 5,17  "start_campaign": false,18  "from_numbers": "<from_numbers>",19  "use_vanira_managed": true20}'

Expected Response — 200 OK

json
1{2  "success": true,3  "campaign_id": "camp-uuid-...",4  "total_prospects": 480,5  "message": "Campaign created",6  "started": false7}

HTTP Errors

404
IMPORT_NOT_FOUND

Import not found or not ready.

422
VALIDATION_ERROR

Invalid campaign settings.

Add Prospects

POST
#
POSThttps://api.vanira.io/campaigns/:campaign_id/add-prospects
Append prospects to an existing voice campaign.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

campaign_idREQUIRED
uuid

Campaign UUID.

Body Parameters

prospectsREQUIRED
array

Array of { phone, name, extra_details? }.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/campaigns/<campaign_id>/add-prospects' \2  -H "Content-Type: application/json" \3  -d '{4  "prospects": [5    {6      "phone": "+919876543210",7      "name": "John"8    }9  ]10}'

Expected Response — 200 OK

json
1{2  "success": true,3  "campaign_id": "camp-uuid-...",4  "status": "active",5  "message": "Prospects added"6}

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found.

422
VALIDATION_ERROR

Invalid prospect rows.

List Prospects

GET
#
GEThttps://api.vanira.io/campaigns/:campaign_id/prospects
Paginated prospects for a voice campaign with optional filters.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

campaign_idREQUIRED
uuid

Campaign UUID.

Query Parameters

limit
number

Page size.

offset
number

Offset.

status
string

Filter by prospect status.

search
string

Search name/phone.

is_successful
boolean

Filter by success flag.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/campaigns/<campaign_id>/prospects?limit=25&offset=0&status=%3Cstatus%3E&search=%3Csearch%3E&is_successful=%3Cis_successful%3E'

Expected Response — 200 OK

json
1{2  "prospects": [3    { "id": "p-uuid", "name": "John", "phone": "+919876543210", "status": "pending" }4  ],5  "total_count": 4806}

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found.

Create WhatsApp Campaign

POST
#
POSThttps://api.vanira.io/whatsapp-campaigns
Create a WhatsApp outbound campaign with a message template and prospect list.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

nameREQUIRED
string

Campaign name.

inbox_idREQUIRED
uuid

Connected WhatsApp inbox UUID.

message_templateREQUIRED
string

Message body template. Supports prospect placeholders.

candidatesREQUIRED
array

Prospects: name, phone, optional extra_details.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/whatsapp-campaigns' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "Diwali Promo",5  "inbox_id": "<inbox-uuid>",6  "message_template": "Hi {{name}}, checking in from Vanira!",7  "candidates": [8    {9      "name": "John",10      "phone": "+919876543210"11    }12  ]13}'

Expected Response — 200 OK

json
1{2  "success": true,3  "campaign_id": "wa-camp-uuid-...",4  "total_prospects": 120,5  "message": "Campaign created"6}

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

404
INBOX_NOT_FOUND

Inbox not found or not owned.

422
VALIDATION_ERROR

Invalid candidates or missing fields.

List WhatsApp Campaigns

GET
#
GEThttps://api.vanira.io/whatsapp-campaigns
List WhatsApp campaigns for the authenticated client.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/whatsapp-campaigns'

Expected Response — 200 OK

json
1[2  {3    "id": "wa-camp-uuid-...",4    "name": "Diwali Promo",5    "status": "draft",6    "inbox_id": "<inbox-uuid>",7    "total_prospects": 120,8    "created_at": "2026-04-01T10:00:00Z"9  }10]

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

Get WhatsApp Campaign

GET
#
GEThttps://api.vanira.io/whatsapp-campaigns/:campaign_id
Fetch a WhatsApp campaign by ID.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

campaign_idREQUIRED
uuid

Campaign UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/whatsapp-campaigns/<campaign_id>'

Expected Response — 200 OK

json
1{2  "id": "wa-camp-uuid-...",3  "name": "Diwali Promo",4  "status": "active",5  "inbox_id": "<inbox-uuid>",6  "message_template": "Hi {{name}}...",7  "total_prospects": 1208}

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found.

List Prospects

GET
#
GEThttps://api.vanira.io/whatsapp-campaigns/:campaign_id/prospects
Paginated prospects for a WhatsApp campaign.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

campaign_idREQUIRED
uuid

Campaign UUID.

Query Parameters

limit
number

Page size (1–100). Default 25.

offset
number

Pagination offset. Default 0.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/whatsapp-campaigns/<campaign_id>/prospects?limit=25&offset=0'

Expected Response — 200 OK

json
1{2  "prospects": [3    { "id": "p-uuid", "name": "John", "phone": "+919876543210", "status": "pending" }4  ],5  "total_count": 1206}

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found.

Start Campaign

POST
#
POSThttps://api.vanira.io/whatsapp-campaigns/:campaign_id/start
Start sending messages for a WhatsApp campaign.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

campaign_idREQUIRED
uuid

Campaign UUID.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/whatsapp-campaigns/<campaign_id>/start' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "success": true,3  "status": "active",4  "message": "Campaign started"5}

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found.

400
BAD_REQUEST

Campaign cannot be started from current status.

Pause Campaign

POST
#
POSThttps://api.vanira.io/whatsapp-campaigns/:campaign_id/pause
Pause an active WhatsApp campaign.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

campaign_idREQUIRED
uuid

Campaign UUID.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/whatsapp-campaigns/<campaign_id>/pause' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "success": true,3  "status": "paused",4  "message": "Campaign paused"5}

HTTP Errors

404
CAMPAIGN_NOT_FOUND

Campaign not found.

List Inboxes

GET
#
GEThttps://api.vanira.io/inbox
List connected messaging inboxes (WhatsApp Web / Business, etc.).
  • *Authentication**
Requires X-API-Key: sk_live_* or Bearer JWT. Scopes: messaging:read / messaging:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Query Parameters

types
string

Comma-separated inbox types filter.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/inbox?types=WHATSAPP_WEB%2CWHATSAPP_BUSINESS'

Expected Response — 200 OK

json
1{2  "inboxes": [3    {4      "id": "<inbox-uuid>",5      "inbox_type": "WHATSAPP_WEB",6      "inbox_name": "Support line",7      "agent_id": "caaa5b2a-...",8      "config": {}9    }10  ]11}

Response Schema Details

idREQUIRED
uuid

Inbox UUID — use as inbox_id when sending.

inbox_typeREQUIRED
string

Inbox channel type.

inbox_name
string

Display name.

agent_id
uuid

Linked agent if any.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

List Inbox Messages

GET
#
GEThttps://api.vanira.io/inbox/messages
Fetch recent messages for an inbox.
  • *Authentication**
Requires X-API-Key: sk_live_* or Bearer JWT. Scopes: messaging:read / messaging:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Query Parameters

inbox_idREQUIRED
uuid

Inbox UUID.

limit
number

Max messages (default 50).

sender
string

Optional filter by sender phone/id.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/inbox/messages?inbox_id=%3Cinbox-uuid%3E&limit=50&sender=%3Csender%3E'

Expected Response — 200 OK

json
1{2  "inbox_message": [3    {4      "id": "msg-uuid-...",5      "inbox_id": "<inbox-uuid>",6      "direction": "outbound",7      "body": "Hello from API!",8      "created_at": "2026-04-01T10:00:00Z"9    }10  ]11}

HTTP Errors

400
BAD_REQUEST

inbox_id missing.

401
UNAUTHORIZED

Missing or invalid API key.

404
INBOX_NOT_FOUND

Inbox not found.

Send WhatsApp Message

POST
#
POSThttps://api.vanira.io/inbox/send
Send a WhatsApp message to a phone number via a connected inbox. Requires an active WhatsApp inbox integration.
  • *Authentication**
Requires X-API-Key: sk_live_* or Bearer JWT. Scopes: messaging:read / messaging:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

inbox_idREQUIRED
uuid

UUID of the connected WhatsApp inbox.

toREQUIRED
string

Recipient phone number in E.164 format.

messageREQUIRED
string

Message content to send.

conversation_id
uuid

Optional existing conversation UUID.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/inbox/send' \2  -H "Content-Type: application/json" \3  -d '{4  "inbox_id": "<inbox-uuid>",5  "to": "+919182517283",6  "message": "Hello from API!",7  "conversation_id": "<conversation_id>"8}'

Expected Response — 200 OK

json
1{2  "success": true,3  "message_id": "<message-uuid>",4  "status": "sent"5}

Response Schema Details

successREQUIRED
boolean

true if the message was queued successfully.

message_id
uuid

Unique identifier for the sent message.

status
string

Message status: sent | queued | failed.

HTTP Errors

400
missing_field

inbox_id, to, or message was not provided.

404
inbox_not_found

No WhatsApp inbox exists with the provided inbox_id.

401
inbox_not_authenticated

The inbox has not been authenticated (QR code not scanned).

503
whatsapp_unavailable

WhatsApp service is unavailable or the number is unreachable.

List Lead Groups

GET
#
GEThttps://api.vanira.io/leads/groups
List lead groups for the authenticated client.
  • *Authentication**
Requires X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/leads/groups'

Expected Response — 200 OK

json
1{2  "groups": [3    { "id": "group-uuid-...", "name": "Website inbound" }4  ]5}

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

List Lead Columns

GET
#
GEThttps://api.vanira.io/leads/columns
List custom lead column definitions (key/label) for the client.
  • *Authentication**
Requires X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/leads/columns'

Expected Response — 200 OK

json
1{2  "columns": [3    { "id": "col-uuid-...", "key": "company", "label": "Company" }4  ]5}

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

List Leads

GET
#
GEThttps://api.vanira.io/leads
Fetch leads for the authenticated organization/client.
  • *Authentication**
Requires X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/leads'

Expected Response — 200 OK

json
1{2  "leads": [3    {4      "id": "e30e70ab-7d43-4a11-b75c-3f2d2948cba4",5      "client_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",6      "name": "John Doe",7      "phone_number": "+1234567890",8      "email_id": "john.doe@example.com",9      "lead_source": "Website",10      "status": "New",11      "remarks": "Interested in premium plan",12      "lead_data": [{ "key": "company", "value": "Acme" }],13      "created_at": "2026-04-20T10:30:00Z",14      "updated_at": "2026-04-20T10:30:00Z"15    }16  ]17}

Response Schema Details

idREQUIRED
uuid

Unique identifier for the lead.

client_idREQUIRED
uuid

Owner organization ID.

name
string

Full name of the lead.

phone_number
string

Primary phone number.

email_id
string

Primary email address.

lead_source
string

Source of the lead (e.g., Website, Import).

status
string

Current status of the lead.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

500
DATABASE_ERROR

Database connectivity issue.

Create Lead

POST
#
POSThttps://api.vanira.io/leads
Create a new lead. phone_number is required.
  • *Authentication**
Requires X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

phone_numberREQUIRED
string

Primary phone (E.164 preferred).

name
string

Lead name.

email_id
email

Primary email.

alternate_phone_number
string

Secondary phone.

alternate_email_id
email

Secondary email.

lead_source
string

Source label.

status
string

Initial status.

remarks
string

Free-text notes.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/leads' \2  -H "Content-Type: application/json" \3  -d '{4  "phone_number": "+919876543210",5  "name": "John Doe",6  "email_id": "john@example.com",7  "alternate_phone_number": "<alternate_phone_number>",8  "alternate_email_id": "<alternate_email_id>",9  "lead_source": "Website",10  "status": "New",11  "remarks": "<remarks>"12}'

Expected Response — 200 OK

json
1{2  "id": "e30e70ab-7d43-4a11-b75c-3f2d2948cba4",3  "phone_number": "+919876543210",4  "name": "John Doe",5  "status": "New"6}

HTTP Errors

422
VALIDATION_ERROR

phone_number missing or invalid.

Get Lead

GET
#
GEThttps://api.vanira.io/leads/:id
Retrieve a lead by UUID.
  • *Authentication**
Requires X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the lead to retrieve.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/leads/e30e70ab-7d43-4a11-b75c-3f2d2948cba4'

Expected Response — 200 OK

json
1{2  "id": "e30e70ab-7d43-4a11-b75c-3f2d2948cba4",3  "client_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",4  "name": "John Doe",5  "phone_number": "+1234567890",6  "email_id": "john.doe@example.com",7  "alternate_phone_number": null,8  "alternate_email_id": null,9  "lead_source": "Website",10  "status": "New",11  "remarks": "Interested in premium plan",12  "created_at": "2026-04-20T10:30:00Z",13  "updated_at": "2026-04-20T10:30:00Z"14}

Response Schema Details

idREQUIRED
uuid

Unique identifier for the lead.

client_idREQUIRED
uuid

Owner organization ID.

name
string

Full name of the lead.

phone_number
string

Primary phone number.

email_id
string

Primary email address.

lead_source
string

Source of the lead (e.g., Website, Import).

status
string

Current status of the lead.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

404
LEAD_NOT_FOUND

No lead exists with the provided UUID.

422
VALIDATION_ERROR

Invalid UUID format.

500
DATABASE_ERROR

Database connectivity issue.

Update Lead

PATCH
#
PATCHhttps://api.vanira.io/leads/:id
Partially update lead contact or status fields.
  • *Authentication**
Requires X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Lead UUID.

Body Parameters

name
string

Updated name.

phone_number
string

Updated phone.

email_id
email

Updated email.

status
string

Updated status.

remarks
string

Updated notes.

lead_source
string

Updated source.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/leads/<id>' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "<name>",5  "phone_number": "<phone_number>",6  "email_id": "<email_id>",7  "status": "Contacted",8  "remarks": "<remarks>",9  "lead_source": "<lead_source>"10}'

Expected Response — 200 OK

json
1{2  "id": "e30e70ab-7d43-4a11-b75c-3f2d2948cba4",3  "status": "Contacted",4  "updated_at": "2026-04-21T09:00:00Z"5}

HTTP Errors

404
LEAD_NOT_FOUND

Lead not found.

Schedule Follow-up

POST
#
POSThttps://api.vanira.io/leads/:id/followup
Schedule a follow-up for a lead.
  • *Authentication**
Requires X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Lead UUID.

Body Parameters

date_timeREQUIRED
string

ISO 8601 follow-up datetime.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/leads/<id>/followup' \2  -H "Content-Type: application/json" \3  -d '{4  "date_time": "2026-04-25T15:00:00Z"5}'

Expected Response — 200 OK

json
1{2  "status": "success",3  "id": "followup-uuid-..."4}

HTTP Errors

404
LEAD_NOT_FOUND

Lead not found.

422
VALIDATION_ERROR

Invalid date_time.

List Bookings

GET
#
GEThttps://api.vanira.io/bookings
List appointments / bookings for the authenticated client.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: bookings:read / bookings:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/bookings'

Expected Response — 200 OK

json
1{2  "appointments": [3    {4      "id": "appt-uuid-...",5      "title": "Demo call",6      "status": "scheduled",7      "start_time": "2026-04-10T09:00:00Z",8      "end_time": "2026-04-10T09:30:00Z",9      "ticket": {10        "id": "ticket-uuid-...",11        "status": "open",12        "priority": "medium"13      }14    }15  ]16}

Response Schema Details

appointmentsREQUIRED
array

Appointment objects, optionally with nested ticket.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

Update Ticket Status

PATCH
#
PATCHhttps://api.vanira.io/bookings/ticket/:ticket_id/status
Update the status of a booking-linked ticket.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: bookings:read / bookings:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

ticket_idREQUIRED
uuid

Ticket UUID.

Body Parameters

statusREQUIRED
string

New ticket status.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/bookings/ticket/<ticket_id>/status' \2  -H "Content-Type: application/json" \3  -d '{4  "status": "resolved"5}'

Expected Response — 200 OK

json
1{2  "id": "ticket-uuid-...",3  "status": "resolved",4  "priority": "medium"5}

HTTP Errors

404
TICKET_NOT_FOUND

Ticket not found.

422
VALIDATION_ERROR

Invalid status.

Update Ticket Priority

PATCH
#
PATCHhttps://api.vanira.io/bookings/ticket/:ticket_id/priority
Update the priority of a booking-linked ticket.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: bookings:read / bookings:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

ticket_idREQUIRED
uuid

Ticket UUID.

Body Parameters

priorityREQUIRED
string

New priority.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/bookings/ticket/<ticket_id>/priority' \2  -H "Content-Type: application/json" \3  -d '{4  "priority": "high"5}'

Expected Response — 200 OK

json
1{2  "id": "ticket-uuid-...",3  "status": "open",4  "priority": "high"5}

HTTP Errors

404
TICKET_NOT_FOUND

Ticket not found.

422
VALIDATION_ERROR

Invalid priority.

List Calendar Users

GET
#
GEThttps://api.vanira.io/calendar/users
List calendar users for the authenticated client, including availability and integrations.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: calendar:read / calendar:write (agent mapping uses assistant:read / assistant:write).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/calendar/users'

Expected Response — 200 OK

json
1{2  "users": [3    {4      "id": "u1a2b3c4-...",5      "name": "Priya Sharma",6      "user_type": "human",7      "timezone": "Asia/Kolkata",8      "provider": "google",9      "configured_availability": true,10      "calendar_integrations": []11    }12  ]13}

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

Create Calendar User

POST
#
POSThttps://api.vanira.io/calendar/users
Create a calendar user that agents can book against.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: calendar:read / calendar:write (agent mapping uses assistant:read / assistant:write).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

nameREQUIRED
string

Display name.

user_typeREQUIRED
string

User type (e.g. human).

timezone
string

IANA timezone.

provider
string

Calendar provider hint (e.g. google).

configured_availability
boolean

Whether availability has been configured.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/calendar/users' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "Priya Sharma",5  "user_type": "human",6  "timezone": "Asia/Kolkata",7  "provider": "google",8  "configured_availability": false9}'

Expected Response — 200 OK

json
1{2  "id": "u1a2b3c4-...",3  "name": "Priya Sharma",4  "user_type": "human",5  "timezone": "Asia/Kolkata"6}

HTTP Errors

422
VALIDATION_ERROR

Invalid timezone or missing required fields.

Update Calendar User

PATCH
#
PATCHhttps://api.vanira.io/calendar/users/:user_id
Partially update a calendar user.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: calendar:read / calendar:write (agent mapping uses assistant:read / assistant:write).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

user_idREQUIRED
uuid

Calendar user UUID.

Body Parameters

name
string

Display name.

email_id
email

Contact email.

timezone
string

IANA timezone.

integrator_account_id
string

External integrator account ID.

configured_availability
boolean

Availability configured flag.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/calendar/users/<user_id>' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "<name>",5  "email_id": "<email_id>",6  "timezone": "<timezone>",7  "integrator_account_id": "<integrator_account_id>",8  "configured_availability": false9}'

Expected Response — 200 OK

json
1{2  "id": "u1a2b3c4-...",3  "name": "Priya Sharma",4  "timezone": "Asia/Kolkata"5}

HTTP Errors

404
NOT_FOUND

Calendar user not found.

Delete Calendar User

DELETE
#
DELETEhttps://api.vanira.io/calendar/users/:user_id
Delete a calendar user.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: calendar:read / calendar:write (agent mapping uses assistant:read / assistant:write).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

user_idREQUIRED
uuid

Calendar user UUID.

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/calendar/users/<user_id>' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{ "status": "success" }

HTTP Errors

404
NOT_FOUND

Calendar user not found.

Get Availability

GET
#
GEThttps://api.vanira.io/calendar/users/:user_id/availability
Fetch configured availability slots for a calendar user.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: calendar:read / calendar:write (agent mapping uses assistant:read / assistant:write).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

user_idREQUIRED
uuid

Calendar user UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/calendar/users/<user_id>/availability'

Expected Response — 200 OK

json
1{2  "availability": [3    { "day": "Monday", "start": "09:00", "end": "17:00" }4  ]5}

HTTP Errors

404
NOT_FOUND

Calendar user not found.

Set Availability

POST
#
POSThttps://api.vanira.io/calendar/users/:user_id/availability
Replace availability slots for a calendar user. Body is a JSON array of slot objects.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: calendar:read / calendar:write (agent mapping uses assistant:read / assistant:write).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

user_idREQUIRED
uuid

Calendar user UUID.

Body Parameters

availabilityREQUIRED
array

Array of availability slot objects.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/calendar/users/<user_id>/availability' \2  -H "Content-Type: application/json" \3  -d '{4  "availability": [5    {6      "day": "Monday",7      "start": "09:00",8      "end": "17:00"9    }10  ]11}'

Expected Response — 200 OK

json
1{ "status": "success", "affected_rows": 5 }

HTTP Errors

404
NOT_FOUND

Calendar user not found.

422
VALIDATION_ERROR

Invalid availability payload.

Save Integration

POST
#
POSThttps://api.vanira.io/calendar/integrations
Persist a calendar provider connection for a user (e.g. after OAuth).
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: calendar:read / calendar:write (agent mapping uses assistant:read / assistant:write).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

calendar_user_idREQUIRED
uuid

Calendar user UUID.

connection_idREQUIRED
string

Provider connection ID.

providerREQUIRED
string

Provider name (e.g. google).

integrator_user_idREQUIRED
string

Integrator-side user ID.

provider_metadata
object

Optional provider metadata object.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/calendar/integrations' \2  -H "Content-Type: application/json" \3  -d '{4  "calendar_user_id": "<calendar_user_id>",5  "connection_id": "<connection_id>",6  "provider": "google",7  "integrator_user_id": "<integrator_user_id>",8  "provider_metadata": "<provider_metadata>"9}'

Expected Response — 200 OK

json
1{ "status": "success", "id": "int-uuid-..." }

HTTP Errors

422
VALIDATION_ERROR

Missing required fields.

Update Integration Metadata

POST
#
POSThttps://api.vanira.io/calendar/users/:user_id/integrations/:provider/metadata
Update provider metadata for a calendar user's integration.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: calendar:read / calendar:write (agent mapping uses assistant:read / assistant:write).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

user_idREQUIRED
uuid

Calendar user UUID.

providerREQUIRED
string

Provider key.

Body Parameters

metadataREQUIRED
object

Metadata object to merge/store.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/calendar/users/<user_id>/integrations/google/metadata' \2  -H "Content-Type: application/json" \3  -d '{4  "metadata": {5    "calendar_id": "primary"6  }7}'

Expected Response — 200 OK

json
1{ "status": "success", "affected_rows": 1 }

HTTP Errors

404
NOT_FOUND

User or integration not found.

Get Agent Calendar Mapping

GET
#
GEThttps://api.vanira.io/calendar/agent/:agent_id
List calendar user IDs mapped to an agent. Agent must belong to the authenticated client.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: calendar:read / calendar:write (agent mapping uses assistant:read / assistant:write).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/calendar/agent/<agent_id>'

Expected Response — 200 OK

json
1{2  "calendar_user_ids": ["u1a2b3c4-...", "u5d6e7f8-..."]3}

HTTP Errors

404
AGENT_NOT_FOUND

Agent not found or not owned.

Set Agent Calendar Mapping

POST
#
POSThttps://api.vanira.io/calendar/agent/:agent_id
Replace the set of calendar users linked to an agent for booking.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: calendar:read / calendar:write (agent mapping uses assistant:read / assistant:write).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

Body Parameters

calendar_user_idsREQUIRED
array

Array of calendar user UUIDs.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/calendar/agent/<agent_id>' \2  -H "Content-Type: application/json" \3  -d '{4  "calendar_user_ids": [5    "u1a2b3c4-..."6  ]7}'

Expected Response — 200 OK

json
1{2  "calendar_user_ids": ["u1a2b3c4-..."]3}

HTTP Errors

404
AGENT_NOT_FOUND

Agent not found or not owned.

422
VALIDATION_ERROR

Invalid calendar_user_ids.

List Webhooks

GET
#
GEThttps://api.vanira.io/webhooks
Returns all outbound webhooks for the authenticated client. Secrets are never returned on list/get.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/webhooks'

Expected Response — 200 OK

json
1{2  "webhooks": [3    {4      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",5      "url": "https://example.com/hooks/vanira",6      "status": "active",7      "events": ["CALL_COMPLETED", "NEW_LEAD"],8      "created_at": "2026-04-01T10:00:00Z",9      "updated_at": "2026-04-01T10:00:00Z"10    }11  ]12}

Response Schema Details

idREQUIRED
uuid

Webhook UUID.

urlREQUIRED
string

HTTPS delivery URL.

statusREQUIRED
string

active | inactive.

eventsREQUIRED
array

Subscribed event types: NEW_LEAD | CALL_COMPLETED | CALL_ANALYSIS_COMPLETED | NEW_BOOKING | NEW_TICKET.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

403
INSUFFICIENT_SCOPE

Missing webhooks:read scope.

Create Webhook

POST
#
POSThttps://api.vanira.io/webhooks
Register an HTTPS endpoint to receive Vanira events. The signing secret is returned once — store it securely.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

urlREQUIRED
string

HTTPS URL that will receive POST deliveries.

eventsREQUIRED
array

Event types to subscribe to: NEW_LEAD | CALL_COMPLETED | CALL_ANALYSIS_COMPLETED | NEW_BOOKING | NEW_TICKET.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/webhooks' \2  -H "Content-Type: application/json" \3  -d '{4  "url": "https://example.com/hooks/vanira",5  "events": [6    "CALL_COMPLETED",7    "NEW_LEAD"8  ]9}'

Expected Response — 200 OK

json
1{2  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",3  "url": "https://example.com/hooks/vanira",4  "status": "active",5  "events": ["CALL_COMPLETED", "NEW_LEAD"],6  "signing_secret": "whsec_••••••••",7  "created_at": "2026-04-01T10:00:00Z",8  "updated_at": "2026-04-01T10:00:00Z"9}

Response Schema Details

signing_secretREQUIRED
string

HMAC signing secret. Shown only on create / regenerate.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

403
INSUFFICIENT_SCOPE

Missing webhooks:write scope.

422
VALIDATION_ERROR

URL must be HTTPS, or events invalid.

Get Webhook

GET
#
GEThttps://api.vanira.io/webhooks/:id
Fetch a single webhook by ID (no secret).
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Webhook UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890'

Expected Response — 200 OK

json
1{2  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",3  "url": "https://example.com/hooks/vanira",4  "status": "active",5  "events": ["CALL_COMPLETED"],6  "created_at": "2026-04-01T10:00:00Z",7  "updated_at": "2026-04-01T10:00:00Z"8}

HTTP Errors

404
WEBHOOK_NOT_FOUND

Webhook not found or not owned by client.

Update Webhook

PATCH
#
PATCHhttps://api.vanira.io/webhooks/:id
Update webhook status or subscribed events.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Webhook UUID.

Body Parameters

status
string

active | inactive.

events
array

Replace the subscribed event list.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/webhooks/<id>' \2  -H "Content-Type: application/json" \3  -d '{4  "status": "inactive",5  "events": [6    "NEW_BOOKING"7  ]8}'

Expected Response — 200 OK

json
1{2  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",3  "url": "https://example.com/hooks/vanira",4  "status": "inactive",5  "events": ["NEW_BOOKING"],6  "updated_at": "2026-04-02T12:00:00Z"7}

HTTP Errors

404
WEBHOOK_NOT_FOUND

Webhook not found.

422
VALIDATION_ERROR

Invalid status or events.

Delete Webhook

DELETE
#
DELETEhttps://api.vanira.io/webhooks/:id
Permanently delete a webhook subscription.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Webhook UUID.

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/webhooks/<id>' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1// 204 No Content

HTTP Errors

404
WEBHOOK_NOT_FOUND

Webhook not found.

Regenerate Secret

POST
#
POSThttps://api.vanira.io/webhooks/:id/regenerate-secret
Rotate the HMAC signing secret. The new secret is returned once; previous signatures become invalid.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Webhook UUID.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/webhooks/<id>/regenerate-secret' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",3  "url": "https://example.com/hooks/vanira",4  "status": "active",5  "events": ["CALL_COMPLETED"],6  "signing_secret": "whsec_new_••••••••"7}

HTTP Errors

404
WEBHOOK_NOT_FOUND

Webhook not found.

List Deliveries

GET
#
GEThttps://api.vanira.io/webhooks/:id/deliveries
Returns the last 50 delivery attempts for a webhook (success/failure, latency, payload).
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Webhook UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/webhooks/<id>/deliveries'

Expected Response — 200 OK

json
1{2  "deliveries": [3    {4      "id": "d1e2f3a4-...",5      "webhook_id": "a1b2c3d4-...",6      "event_type": "CALL_COMPLETED",7      "http_status": 200,8      "duration_ms": 120,9      "attempt": 1,10      "success": true,11      "delivered_at": "2026-04-01T10:05:00Z"12    }13  ]14}

Response Schema Details

event_typeREQUIRED
string

Event that was delivered.

http_status
number

HTTP status from your endpoint.

successREQUIRED
boolean

Whether the delivery succeeded.

duration_ms
number

Round-trip latency in milliseconds.

HTTP Errors

404
WEBHOOK_NOT_FOUND

Webhook not found.

Ping Webhook

POST
#
POSThttps://api.vanira.io/webhooks/:id/ping
Send a test delivery for one of the webhook's subscribed events.
  • *Authentication**
Requires X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Webhook UUID.

Query Parameters

event_type
string

Optional event type; defaults to first subscribed event.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/webhooks/<id>/ping' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "success": true,3  "event_type": "CALL_COMPLETED",4  "payload": { "event": "CALL_COMPLETED", "data": {} }5}

HTTP Errors

404
WEBHOOK_NOT_FOUND

Webhook not found.

400
BAD_REQUEST

event_type not in webhook subscriptions.

Overview

#
Tools let your AI agent take actions during a conversation — calling an API, showing a UI component, booking an appointment, or triggering a call.
  • *Two tool types**
  • *Server tools** — the AI calls your HTTP webhook with extracted parameters. Your server processes the request and returns a result. The AI uses the result in its next response.
  • *Client tool kinds** (documented separately):
PageWhat it covers
Preset ToolsBuilt-in UI — form, calendar, navigate, DOM actions, screen overlay, …
Custom Client ToolsYour own handler — popups, API calls, custom logic
  • *Server tools — HTTP webhooks; see Create Tool** for POST /tools payload shape.
Use {{param_name}} in request.body or client_fields for AI-extracted values; plain strings for static fields.

Preset Tools

#
  • *Preset tools** are built-in client tools with ready-made UI. The SDK renders them automatically — no onCustomTool handler needed.
Set client_fields.preset_id when creating the tool. With VaniraCallBox or PresetRenderer, preset UI appears on its own.

Add a preset (dashboard)

  • *Agent → Tools → Create tool → Client** — pick a preset tile (Form, Calendar, Navigate, Upload, …). Attach to your agent.

Add a preset (API)

1. POST /tools — copy a body below (set client_fields.preset_id)
2. POST /assistant/{agent_id}/tools — attach with { "tool_id": "<uuid>" }
Code examplebash
1# 1. Create2curl -X POST https://api.vanira.io/tools \3  -H "X-API-Key: sk_live_..." \4  -H "Content-Type: application/json" \5  -d @vanira_form_tool.json6 7# 2. Attach to agent8curl -X POST https://api.vanira.io/assistant/YOUR_AGENT_ID/tools \9  -H "X-API-Key: sk_live_..." \10  -H "Content-Type: application/json" \11  -d '{"tool_id": "TOOL_UUID_FROM_STEP_1"}'

All preset IDs

Preset IDUIMode
vanira_formData Collection Formblocking
vanira_phoneMobile numberblocking
vanira_mcqMultiple Choice Questionblocking
vanira_calendarDate & Time Pickerblocking
vanira_uploadFile Uploadblocking
vanira_cameraCamera Capturefire_and_forget
vanira_navigateNavigate to Route — requires vanira:navigate listener on SPAsblocking
vanira_highlight_elementHighlight Elementblocking
vanira_click_elementClick Elementblocking
vanira_select_optionSelect Dropdown Optionblocking
vanira_set_dateSet Date Fieldblocking
vanira_type_textDOM Typing Simulationblocking
vanira_write_latex_textChalkboard LaTeX Writerblocking
vanira_erase_textWhiteboard / DOM Eraseblocking
vanira_live_visionLive Vision (Streaming Camera)fire_and_forget
vanira_close_live_cameraStop Live Camerablocking
vanira_live_screenLive Screen Sharefire_and_forget
vanira_close_live_screenStop Live Screen Shareblocking
vanira_clip_regionPage Region Clipblocking
vanira_screen_visionScreen Visionblocking
vanira_point_atPoint At Screenblocking
vanira_draw_on_screenDraw On Screenblocking
vanira_clear_screen_drawClear Screen Drawingsblocking
vanira_highlight_on_screenHighlight On Screenblocking
vanira_kyc_document_captureKYC Document Captureblocking
vanira_kyc_selfie_captureKYC Selfie Captureblocking
vanira_kyc_signature_captureKYC Signature Captureblocking
  • *Blocking presets wait for `sendToolResult()` (the SDK sends it when the user completes or dismisses the UI). fire_and_forget** presets do not block the agent.

DOM presets — route in client_fields

For vanira_click_element, vanira_select_option, vanira_set_date, vanira_type_text, and vanira_erase_text, set route to the SPA path where the target element lives. The SDK navigates first if needed.

Navigate preset — SPA listener

When the agent calls vanira_navigate, the SDK dispatches a browser event instead of forcing a full page reload:
TargetSDK behavior
Same-origin path (e.g. /pricing, /docs#faq)Fires vanira:navigate with detail.path — your site must handle it
External URL (different origin)Opens in a new tab automatically — no listener needed
  • *SPA sites (React, Vue, Next.js, etc.) must register a vanira:navigate listener** that routes with your framework and sets event.detail.handled = true. Without it, same-origin navigation fails with status: cancelled and the console shows: No SPA listener handled vanira:navigate.
  • *Framework apps (Next.js, Remix, etc.) cannot paste the script tag in `layout.tsx` alone — React will not run a global `vanira:navigate` listener for you. Mount the widget once from a client component** and register navigation with your framework router (useRouter in Next.js App Router). The widget custom element stays on document.body, so route changes do not tear down the call.
  • *Blocking tool:** the AI pauses until the SDK sends client_tool_result. Success payload: { status: 'success', navigated_to, target_url }. Server interrupt (clearAudio / client_tool_cancel): { status: 'interrupted', reason, target_url }.
  • *Multi-page sites** can use window.location.assign(event.detail.path) in the listener, or the same pattern as a fallback.

Copy-paste POST /tools bodies

vanira_form — Data Collection Form

Popup form — blocking. AI passes fields (comma-separated labels) per call; optional title fallback in client_fields.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "collect_user_data",3  "ref_code": "collect_user_data",4  "description": "Call this tool to display a form to collect information from the user.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "reason",11      "type": "string",12      "description": "A short message explaining why you need their info (e.g., \"To look up your order\").",13      "required": true14    },15    {16      "name": "fields",17      "type": "string",18      "description": "Comma-separated field labels for this form (e.g. \"Full Name, Email, Order ID\"). Choose based on the conversation.",19      "required": true20    },21    {22      "name": "title",23      "type": "string",24      "description": "Optional form heading.",25      "required": false26    }27  ],28  "client_fields": {29    "preset_id": "vanira_form",30    "title": "Enter your details"31  }32}

vanira_phone — Mobile number

Country-code dropdown plus mobile number — blocking. Submits E.164 (mobile_number, country_code, national_number).
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "collect_mobile_number",3  "ref_code": "collect_mobile_number",4  "description": "Open a mobile-number popup with a country-code dropdown.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "reason",11      "type": "string",12      "description": "Why you need the mobile number.",13      "required": true14    },15    {16      "name": "title",17      "type": "string",18      "description": "Optional popup heading.",19      "required": false20    },21    {22      "name": "mobile_number",23      "type": "string",24      "description": "Optional number the visitor already said.",25      "required": false26    }27  ],28  "client_fields": {29    "preset_id": "vanira_phone",30    "title": "Your mobile number",31    "default_country": "IN"32  }33}

vanira_mcq — Multiple Choice Question

Question + tappable options modal. question and options can be static in client_fields or overridden per call. Submit sends action_interrupt + client_action_trigger (same as form), not client_tool_result.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "ask_multiple_choice",3  "ref_code": "ask_multiple_choice",4  "description": "Call this tool to show a multiple-choice question to the user. Pass question and options only when they differ from the static values on the tool.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "reason",11      "type": "string",12      "description": "A short message explaining why you are asking (e.g., \"Let's check your understanding\").",13      "required": true14    },15    {16      "name": "question",17      "type": "string",18      "description": "The question text. Omit to use static client_fields.question.",19      "required": false20    },21    {22      "name": "options",23      "type": "string",24      "description": "Pipe- or comma-separated options. Omit to use static client_fields.options.",25      "required": false26    },27    {28      "name": "title",29      "type": "string",30      "description": "Optional modal heading.",31      "required": false32    },33    {34      "name": "image_url",35      "type": "string",36      "description": "Optional image URL shown above the question.",37      "required": false38    }39  ],40  "client_fields": {41    "preset_id": "vanira_mcq",42    "title": "Quick question",43    "question": "Is water a liquid at room temperature?",44    "options": ["True", "False"],45    "allow_multiple": false46  }47}

vanira_calendar — Date & Time Picker

Calendar + time slots. Optional slots_api_url for live availability. blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "display_booking_calendar",3  "ref_code": "display_booking_calendar",4  "description": "Call this tool to display a calendar for the user to select an appointment date and time.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "reason",11      "type": "string",12      "description": "A short message explaining why they need to pick a time (e.g., \"To schedule your consultation\").",13      "required": true14    }15  ],16  "client_fields": {17    "preset_id": "vanira_calendar",18    "title": "Select a Date & Time",19    "timezone": "America/New_York",20    "slots_api_url": "https://api.example.com/slots?date={{date}}&tz={{timezone}}",21    "slots_api_method": "GET",22    "slots_api_headers": "{\"Authorization\": \"Bearer YOUR_TOKEN\"}",23    "slots_api_body": "{}"24  }25}

vanira_upload — File Upload

Drag-and-drop uploader (up to 3 MB). blocking — client_tool_result includes media_id when upload succeeds.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "request_file_upload",3  "ref_code": "request_file_upload",4  "description": "Call this tool to ask the user to upload a file (image, PDF, document, CSV) so the agent can inspect or process it.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "reason",11      "type": "string",12      "description": "A short message explaining why you need the file (e.g., \"To verify your identity\").",13      "required": true14    }15  ],16  "client_fields": {17    "preset_id": "vanira_upload",18    "title": "Upload a File",19    "description": "Drop or select any file — images, PDFs, documents — up to 3 MB",20    "reason": "upload",21    "accept": "application/pdf,image/*"22  }23}

vanira_camera — Camera Capture

Single photo capture mid-call. fire_and_forget.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "open_camera",3  "ref_code": "open_camera",4  "description": "Call this tool to open the user's camera so they can take a photo for you to inspect (e.g. damage, hardware issue, ID verification).",5  "type": "client",6  "execution_mode": "fire_and_forget",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "reason",11      "type": "string",12      "description": "A short message explaining why you need a photo (e.g., \"To inspect the damage on your device\").",13      "required": true14    }15  ],16  "client_fields": {17    "preset_id": "vanira_camera",18    "title": "Take a Photo",19    "description": "Point your camera at the subject, then tap capture to send it to your agent.",20    "reason": "camera_capture",21    "facing_mode": "environment",22    "liveness_check": false23  }24}

vanira_navigate — Navigate to Route

Same-origin paths dispatch vanira:navigate — register a listener on your site (see SPA setup below). External URLs open in a new tab. blocking — AI waits for client_tool_result; server interrupt returns status: interrupted.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "navigate_user",3  "ref_code": "navigate_user",4  "description": "Call this tool to redirect the user to a different route.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [],9  "client_fields": {10    "preset_id": "vanira_navigate",11    "target_url": "/pricing"12  }13}
When the agent calls vanira_navigate, the SDK dispatches a browser event instead of forcing a full page reload:
TargetSDK behavior
Same-origin path (e.g. /pricing, /docs#faq)Fires vanira:navigate with detail.path — your site must handle it
External URL (different origin)Opens in a new tab automatically — no listener needed
  • *SPA sites (React, Vue, Next.js, etc.) must register a vanira:navigate listener** that routes with your framework and sets event.detail.handled = true. Without it, same-origin navigation fails with status: cancelled and the console shows: No SPA listener handled vanira:navigate.
  • *Framework apps (Next.js, Remix, etc.) cannot paste the script tag in `layout.tsx` alone — React will not run a global `vanira:navigate` listener for you. Mount the widget once from a client component** and register navigation with your framework router (useRouter in Next.js App Router). The widget custom element stays on document.body, so route changes do not tear down the call.
  • *Blocking tool:** the AI pauses until the SDK sends client_tool_result. Success payload: { status: 'success', navigated_to, target_url }. Server interrupt (clearAudio / client_tool_cancel): { status: 'interrupted', reason, target_url }.
  • *Multi-page sites** can use window.location.assign(event.detail.path) in the listener, or the same pattern as a fallback.
  • *Listener snippet** (add to your site):
Code examplejavascript
1// Add once on your site (same page as the Vanira widget).2// Required when your agent uses the vanira_navigate preset.3window.addEventListener('vanira:navigate', (event) => {4  const path = event.detail.path; // e.g. "/pricing" or "/docs#section"5 6  // Option A — multi-page site or simple fallback:7  window.location.assign(path);8 9  // Option B — SPA router (pick one that matches your stack):10  // router.push(path);              // React Router: useNavigate()11  // navigate(path);                 // Vue Router12  // router.push(path);              // Next.js App Router13 14  event.detail.handled = true; // required — tells the SDK navigation succeeded15});

vanira_highlight_element — Highlight Element

Glow outline on a CSS selector. blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "highlight_ui_element",3  "ref_code": "highlight_ui_element",4  "description": "Call this tool to draw the user's attention to a specific button or element on the page.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [],9  "client_fields": {10    "preset_id": "vanira_highlight_element",11    "css_selector": "#buy-button",12    "color": "#10B981"13  }14}

vanira_click_element — Click Element

Programmatic click by HTML id (no #). route required — SDK navigates first when the user is on another page. blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "click_button",3  "ref_code": "click_button",4  "description": "Call this tool to click a specific button on the user's screen by HTML id.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [],9  "client_fields": {10    "preset_id": "vanira_click_element",11    "element_id": "buy-button",12    "route": "/checkout"13  }14}

vanira_select_option — Select Dropdown Option

Select native <select> or custom dropdown by HTML id. route required — SDK navigates first. blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "select_option",3  "ref_code": "select_option",4  "description": "Call this tool to select a dropdown option on the user's page (e.g. country, cabin class).",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "option_value",11      "type": "string",12      "description": "Option value attribute (e.g. economy, IN).",13      "required": false14    },15    {16      "name": "option_label",17      "type": "string",18      "description": "Visible label to match (e.g. Economy, India).",19      "required": false20    }21  ],22  "client_fields": {23    "preset_id": "vanira_select_option",24    "element_id": "country-select",25    "route": "/flights",26    "allowed_options": ["economy", "business", "first_class"]27  }28}

vanira_set_date — Set Date Field

Set text or native date input by HTML id. Agent passes ISO date; SDK formats per text_format. route required. blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "set_date_field",3  "ref_code": "set_date_field",4  "description": "Call this tool to set a departure, check-in, or delivery date on the user's form.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "date",11      "type": "string",12      "description": "Date in ISO YYYY-MM-DD (e.g. 2026-06-15).",13      "required": true14    }15  ],16  "client_fields": {17    "preset_id": "vanira_set_date",18    "element_id": "departure-date",19    "route": "/flights",20    "input_kind": "text",21    "text_format": "DD/MM/YYYY"22  }23}

vanira_type_text — DOM Typing Simulation

Type into an input or chalkboard. typing_mode: append (boards) or replace (search bars). route only when CSS selector / element id is set. blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "type_on_whiteboard",3  "ref_code": "type_on_whiteboard",4  "description": "Call when writing something visible to the student — a formula, solution step, definition, or note. Pass text_to_type with the exact text.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "text_to_type",11      "type": "string",12      "description": "Exact text to write. LaTeX for math ($...$ inline, $$...$$ display). Plain text for steps and prose.",13      "required": true14    }15  ],16  "client_fields": {17    "preset_id": "vanira_type_text",18    "css_selector": "#answer-input",19    "element_id": "",20    "route": "/lesson",21    "typing_mode": "append",22    "delay_ms": 5023  }24}

vanira_write_latex_text — Chalkboard LaTeX Writer

Write LaTeX with KaTeX on the chalkboard or a configured page element. latex_text can be static in client_fields or overridden per call. blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "write_latex_text",3  "ref_code": "write_latex_text",4  "description": "Call when showing math — formulas, matrices, derivations, or worked steps. Pass latex_text only when it differs from the static value on the tool. Uses client_fields element when set; otherwise chalkboard.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "latex_text",11      "type": "string",12      "description": "Content to render. LaTeX: $...$ inline, $$...$$ display. Plain text for step labels. Omit to use static client_fields.latex_text.",13      "required": false14    }15  ],16  "client_fields": {17    "preset_id": "vanira_write_latex_text",18    "latex_text": "A support team resolves 45 out of 60 tickets.\n\nWhat percentage were resolved?\n\n$$\\text{Resolution rate} = \\frac{\\text{Resolved tickets}}{\\text{Total tickets}} \\times 100$$",19    "css_selector": "",20    "element_id": "",21    "route": "",22    "typing_mode": "append",23    "font_style": "inter",24    "delay_ms": 5025  }26}

vanira_erase_text — Whiteboard / DOM Erase

Clear input or erase words on chalkboard. route only when element id is set. blocking — call sendToolResult() when done.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "erase_text",3  "ref_code": "erase_text",4  "description": "Call this tool to clear the whiteboard or erase the last few words.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "mode",11      "type": "string",12      "description": "Whether to erase everything (\"all\") or just the last few words (\"words\").",13      "required": false,14      "enum": ["all", "words"]15    },16    {17      "name": "num_words",18      "type": "number",19      "description": "The number of words to erase (only used if mode is \"words\").",20      "required": false21    }22  ],23  "client_fields": {24    "preset_id": "vanira_erase_text",25    "element_id": "#search-input",26    "route": "/search",27    "delay_ms": 5028  }29}

vanira_live_vision — Live Vision (Streaming Camera)

Background ~1 FPS camera stream. fire_and_forget.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "open_live_camera",3  "ref_code": "open_live_camera",4  "description": "Call this tool to open the user's camera and start a live video stream so you can continuously see what they're looking at.",5  "type": "client",6  "execution_mode": "fire_and_forget",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "scope",11      "type": "string",12      "description": "How long to stream: until_call_end (default), timed (N seconds), or full_call.",13      "required": false,14      "enum": ["until_call_end", "timed", "full_call"]15    },16    {17      "name": "duration_sec",18      "type": "number",19      "description": "Seconds to stream (only used when scope is \"timed\").",20      "required": false21    },22    {23      "name": "reason",24      "type": "string",25      "description": "Routing key for the media server (e.g. \"damage_inspection\").",26      "required": false27    }28  ],29  "client_fields": {30    "preset_id": "vanira_live_vision",31    "target_fps": 1,32    "max_width": 640,33    "facing_mode": "environment",34    "reason": "camera_capture",35    "show_preview": true36  }37}

vanira_close_live_camera — Stop Live Camera

Stops an active live vision session. blocking. Pair with Live Vision.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "close_live_camera",3  "ref_code": "close_live_camera",4  "description": "Call this tool to stop the live camera stream and close the camera session.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [],9  "client_fields": {10    "preset_id": "vanira_close_live_camera"11  }12}

vanira_live_screen — Live Screen Share

Background ~1 FPS screen stream. fire_and_forget.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "open_live_screen",3  "ref_code": "open_live_screen",4  "description": "Call this tool to ask the user to share their screen so you can continuously see what they are working on.",5  "type": "client",6  "execution_mode": "fire_and_forget",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "scope",11      "type": "string",12      "description": "How long to stream: until_call_end (default), timed (N seconds), or full_call.",13      "required": false,14      "enum": ["until_call_end", "timed", "full_call"]15    },16    {17      "name": "duration_sec",18      "type": "number",19      "description": "Seconds to stream (only used when scope is \"timed\").",20      "required": false21    },22    {23      "name": "reason",24      "type": "string",25      "description": "Routing key for the media server (e.g. \"support_ticket\").",26      "required": false27    }28  ],29  "client_fields": {30    "preset_id": "vanira_live_screen",31    "target_fps": 1,32    "max_width": 1280,33    "reason": "screen_capture",34    "prefer_current_tab": true,35    "show_preview": true36  }37}

vanira_close_live_screen — Stop Live Screen Share

Stops an active live screen session. blocking. Pair with Live Screen Share.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "close_live_screen",3  "ref_code": "close_live_screen",4  "description": "Call this tool to stop the live screen share and end the screen session.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [],9  "client_fields": {10    "preset_id": "vanira_close_live_screen"11  }12}

vanira_clip_region — Page Region Clip

Snipping overlay on the host page — user drags a box, only the crop uploads. blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "clip_page_region",3  "ref_code": "clip_page_region",4  "description": "Call this tool so the user can clip a region of the page and ask a question about it.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "prompt",11      "type": "string",12      "description": "The question about the selected region.",13      "required": true14    },15    {16      "name": "reason",17      "type": "string",18      "description": "Media routing key (e.g. page_clip).",19      "required": false20    }21  ],22  "client_fields": {23    "preset_id": "vanira_clip_region",24    "hint": "Drag to select an area — release to clip.",25    "reason": "page_clip",26    "min_region_px": 2427  }28}

vanira_screen_vision — Screen Vision

Silent page JPEG (html2canvas) + screenshot pixel coords for buddy pointing. blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "capture_screen_vision",3  "ref_code": "capture_screen_vision",4  "description": "Capture visible page as JPEG (no share prompt by default). Returns screenshot_width/height in pixels. Follow with point_at_screen.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "prompt",11      "type": "string",12      "description": "Optional context for why capture is needed.",13      "required": false14    },15    {16      "name": "reason",17      "type": "string",18      "description": "Media routing key (e.g. screen_vision).",19      "required": false20    },21    {22      "name": "max_width",23      "type": "number",24      "description": "Max JPEG width in pixels (default 960).",25      "required": false26    },27    {28      "name": "jpeg_quality",29      "type": "number",30      "description": "JPEG quality 0.4–1.0 (default 0.72).",31      "required": false32    },33    {34      "name": "capture_surface",35      "type": "string",36      "description": "tab (silent page, default) or display (share picker).",37      "required": false38    }39  ],40  "client_fields": {41    "preset_id": "vanira_screen_vision",42    "reason": "screen_vision",43    "max_width": 960,44    "jpeg_quality": 0.72,45    "capture_surface": "tab",46    "reuse_live_screen": true47  }48}

vanira_point_at — Point At Screen

Fly blue buddy to screenshot pixel coords. Visual only — blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "point_at_screen",3  "ref_code": "point_at_screen",4  "description": "Visually point at x,y in the last screen_vision screenshot pixel space. Does not click.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "x",11      "type": "number",12      "description": "X in screenshot pixels (top-left origin).",13      "required": true14    },15    {16      "name": "y",17      "type": "number",18      "description": "Y in screenshot pixels (top-left origin).",19      "required": true20    },21    {22      "name": "label",23      "type": "string",24      "description": "Short element label (1-3 words).",25      "required": false26    },27    {28      "name": "bubble_text",29      "type": "string",30      "description": "Custom speech bubble text.",31      "required": false32    },33    {34      "name": "point_tag",35      "type": "string",36      "description": "Optional raw [POINT:x,y:label] tag instead of x/y.",37      "required": false38    }39  ],40  "client_fields": {41    "preset_id": "vanira_point_at"42  }43}

vanira_draw_on_screen — Draw On Screen

Tier B vector overlay — animated stroke-draw, no overlap — blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "draw_on_screen",3  "ref_code": "draw_on_screen",4  "description": "Draw structured shapes on the viewport after capture_screen_vision. Sequential stroke animation (default animate_ms=1000). Persists until clear_screen_draw.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "commands",11      "type": "string",12      "description": "JSON array of draw ops: line, polygon, regular_polygon, circle, ellipse, arrow, underline, label, parabola, hyperbola, bezier, path.",13      "required": true14    },15    {16      "name": "animate_ms",17      "type": "number",18      "description": "Stroke-draw animation ms per shape (default 1000, sequential).",19      "required": false20    },21    {22      "name": "ttl_ms",23      "type": "number",24      "description": "Optional auto-fade ms. Omit to persist until clear_screen_draw.",25      "required": false26    },27    {28      "name": "clear",29      "type": "boolean",30      "description": "Clear all existing drawings before drawing (default false).",31      "required": false32    },33    {34      "name": "allow_overlap",35      "type": "boolean",36      "description": "Draw at exact coords on top of existing diagrams (bisectors/chords). Default false = strict no-overlap.",37      "required": false38    }39  ],40  "client_fields": {41    "preset_id": "vanira_draw_on_screen"42  }43}

vanira_clear_screen_draw — Clear Screen Drawings

Remove all draw_on_screen annotations — blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "clear_screen_draw",3  "ref_code": "clear_screen_draw",4  "description": "Clear all vector annotations from the screen overlay.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [],9  "client_fields": {10    "preset_id": "vanira_clear_screen_draw"11  }12}

vanira_highlight_on_screen — Highlight On Screen

Glowing box around a layout-scan element (label or element_id) — blocking.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "highlight_on_screen",3  "ref_code": "highlight_on_screen",4  "description": "After capture_screen_vision, highlight a button/tab by label or element_id from the layout scan. Live DOM bbox + overlay box.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "label",11      "type": "string",12      "description": "Visible element label from layout scan (preferred).",13      "required": false14    },15    {16      "name": "element_id",17      "type": "string",18      "description": "Layout scan id (e.g. e9).",19      "required": false20    },21    {22      "name": "css_selector",23      "type": "string",24      "description": "CSS selector fallback.",25      "required": false26    },27    {28      "name": "color",29      "type": "string",30      "description": "Highlight stroke color (default #3b82f6).",31      "required": false32    },33    {34      "name": "point_at",35      "type": "boolean",36      "description": "Fly buddy to element center (default true).",37      "required": false38    }39  ],40  "client_fields": {41    "preset_id": "vanira_highlight_on_screen"42  }43}

vanira_kyc_document_capture — KYC Document Capture

Manual ID capture with border detection guidance. blocking. Requires reason. Optional title / description (instructions) on the popup.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "kyc_document_capture",3  "ref_code": "kyc_document_capture",4  "description": "Scan user ID — pass reason (e.g. kyc_document). User aligns ID and presses Capture now.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "reason",11      "type": "string",12      "description": "Media routing key (e.g. kyc_document, kyc_id_front).",13      "required": true14    },15    {16      "name": "document_side",17      "type": "string",18      "description": "front or back (default front).",19      "required": false20    },21    {22      "name": "title",23      "type": "string",24      "description": "Optional heading on the ID capture popup.",25      "required": false26    },27    {28      "name": "description",29      "type": "string",30      "description": "Optional instructions text under the title.",31      "required": false32    }33  ],34  "client_fields": {35    "preset_id": "vanira_kyc_document_capture",36    "reason": "kyc_document",37    "title": "Scan your ID",38    "description": "Hold your ID in the frame. On desktop, use your webcam; on mobile, we use the rear camera."39  }40}

vanira_kyc_selfie_capture — KYC Selfie Capture

Auto-capture selfie with liveness. blocking. Requires reason. Optional title / description (instructions) on the popup.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "kyc_selfie_capture",3  "ref_code": "kyc_selfie_capture",4  "description": "Live selfie with liveness — pass reason (e.g. kyc_selfie). Auto-uploads after verification.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "reason",11      "type": "string",12      "description": "Media routing key (e.g. kyc_selfie).",13      "required": true14    },15    {16      "name": "title",17      "type": "string",18      "description": "Optional heading on the selfie capture popup.",19      "required": false20    },21    {22      "name": "description",23      "type": "string",24      "description": "Optional instructions text under the title.",25      "required": false26    }27  ],28  "client_fields": {29    "preset_id": "vanira_kyc_selfie_capture",30    "reason": "kyc_selfie",31    "title": "Verify it's you",32    "description": "Center your face in the oval. Blink or turn slightly when prompted — we'll capture automatically."33  }34}

vanira_kyc_signature_capture — KYC Signature Capture

Signature pad — draw and submit PNG. blocking. Requires reason. Optional title / description (instructions) on the popup.
  • *Create tool body** (POST /tools):
Code examplejson
1{2  "name": "kyc_signature_capture",3  "ref_code": "kyc_signature_capture",4  "description": "Show signature pad — pass reason (e.g. kyc_signature). User draws and submits.",5  "type": "client",6  "execution_mode": "blocking",7  "channels": ["voice_web", "voice_telephony"],8  "parameters": [9    {10      "name": "reason",11      "type": "string",12      "description": "Media routing key (e.g. kyc_signature).",13      "required": true14    },15    {16      "name": "title",17      "type": "string",18      "description": "Optional heading on the signature popup.",19      "required": false20    },21    {22      "name": "description",23      "type": "string",24      "description": "Optional instructions text under the title.",25      "required": false26    }27  ],28  "client_fields": {29    "preset_id": "vanira_kyc_signature_capture",30    "reason": "kyc_signature",31    "title": "Sign here",32    "description": "Draw your signature in the box below, then submit."33  }34}

Custom Client Tools

#
Custom client tools are browser actions you implement — popups, modals, client-side API calls, or any UI the SDK presets do not cover.
Create in the dashboard: Agent → Tools → New tool → Client → Custom.

Step 1 — Agent parameters

Define what the AI should extract from the conversation before invoking the tool. These are not sent directly to your handler — they drive the tool schema only.
Example:
  • customer_name (string, required) — "Person's name from the conversation"

Step 2 — Frontend payload

Map the keys your app code expects. Each value is either:
  • {{param_name}} — substituted with the AI-extracted agent parameter
  • a static string — always the same value
This becomes client_fields in the API and resolves to arguments at runtime.
Payload keyValue
name{{customer_name}}
sourcewebsite
At runtime: { "name": "Teja", "source": "website" }

Step 3 — Execution mode

Dashboard labelAPI valueWhen to use
BlockingblockingAI should wait (form submit, user confirmation) — call sendToolResult()
Asyncfire_and_forgetFire-and-forget UI (popup, toast, map pan)

Step 4 — Wire in the SDK

With VaniraCallBox, handle custom tools in onCustomTool (presets are automatic):
Code exampletypescript
1onCustomTool={(call, client) => {2  if (call.name === 'say_hi') {3    showHiPopup();4    if (call.execution_mode !== 'fire_and_forget' && call.tool_call_id) {5      client.sendToolResult(call.tool_call_id, { status: 'success' });6    }7  }8}}
See the SDK Custom Client Tools guide for the full POST /tools payload.

End Call

SDK
#
BUILT-INend_call
The End Call tool is automatically attached to every Vanira agent. You do not need to create it.
### Behavior
The AI will invoke this tool when:
1. It senses the conversation has reached a natural conclusion (e.g., "Goodbye", "Thank you for your help").
2. The user explicitly asks to hang up.
### Payload Structure
In the API response, it appears with the following properties:
Code examplejson
1{2  "name": "end_call",3  "ref_code": "end_call",4  "description": "End the call when the conversation is finished.",5  "type": "client",6  "execution_mode": "fire_and_forget",7  "parameters": []8}

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1const response = await fetch('end_call', {2  method: 'SDK',3  headers: { 'Content-Type': 'application/json' },4  body: JSON.stringify({}),5});6const data = await response.json();

Human Transfer

POST
#
POSThttps://api.vanira.io/tools
The Human Transfer tool escalates the conversation to a live operator.
### Telephony Behavior
In voice calls, calling this tool triggers an immediate SIP Transfer to your configured fallback number or the to_number parameter.

Creation Payload

Code examplejson
1{2  "name": "human_transfer",3  "ref_code": "human_transfer",4  "description": "Transfers the caller to a live human agent.",5  "type": "server",6  "channels": ["voice_telephony"],7  "parameters": [8    {9      "name": "to_number",10      "type": "string",11      "description": "The destination phone number.",12      "required": true13    }14  ],15  "server": {16    "url": "https://api.vanira.io/webhook/human-transfer",17    "method": "POST"18  },19  "request": {20    "body": { "to_number": "919182517283" },21    "headers": {},22    "query": {}23  }24}

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/tools' \2  -H "Content-Type: application/json"

Agent Transfer

POST
#
POSThttps://api.vanira.io/tools
The Agent Transfer tool switches the current conversation context to a different AI agent.
### Use Case
Transferring a user from a "Lead Qualification" agent to a "Support" agent once their identity is verified.

Creation Payload

Code examplejson
1{2  "name": "agent_transfer",3  "ref_code": "agent_transfer",4  "description": "Transfers the call to another AI agent configuration.",5  "type": "server",6  "channels": ["voice_web", "voice_telephony"],7  "parameters": [8    {9      "name": "agent_id",10      "type": "string",11      "description": "UUID of the target agent.",12      "required": true13    }14  ],15  "server": {16    "url": "https://api.vanira.io/webhook/agent-transfer",17    "method": "POST"18  },19  "request": {20    "body": { "agent_id": "dcf2b11c-81c2-4619-8483-580c8e25cb23" },21    "headers": {},22    "query": {}23  }24}

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/tools' \2  -H "Content-Type: application/json"

List Tools

GET
#
GEThttps://api.vanira.io/tools
Returns all tools defined for the authenticated client. Tools are client-level — they can be attached to multiple agents.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/tools'

Expected Response — 200 OK

json
1{2  "tools": [3    {4      "id": "e2705199-...",5      "name": "show_location_map",6      "description": "Show an interactive map for a location the user asks about.",7      "ref_code": "show_location_map",8      "type": "client",9      "execution_mode": "fire_and_forget",10      "channels": ["voice_web"],11      "parameters": [12        { "name": "location_query", "type": "string", "description": "City or landmark", "required": true }13      ],14      "client_fields": { "query": "{{location_query}}" }15    },16    {17      "id": "a1b2c3d4-...",18      "name": "check_order_status",19      "description": "Check the status of a customer order.",20      "ref_code": "check_order_status",21      "type": "server",22      "execution_mode": "fire_and_forget",23      "channels": ["voice_web", "voice_telephony"],24      "parameters": [25        { "name": "order_id", "type": "string", "description": "Order ID", "required": true }26      ],27      "server": { "url": "https://api.acme.com/orders", "method": "POST" },28      "request": {29        "body":    { "order_id": "{{order_id}}", "source": "vanira" },30        "headers": { "X-API-Key": "sk-abc123" },31        "query":   {}32      }33    }34  ],35  "total": 236}

Response Schema Details

idREQUIRED
uuid

Tool UUID.

nameREQUIRED
string

Tool name — used as the function name the AI calls.

descriptionREQUIRED
string

What the tool does — AI uses this to decide when to call it.

typeREQUIRED
string

"server" | "client".

execution_modeREQUIRED
string

"blocking" | "fire_and_forget". For client tools only.

channelsREQUIRED
array

Which channels this tool is active on.

parametersREQUIRED
array

Parameter schema — what the AI extracts from the conversation.

server
object

{ url, method } — present for server tools only.

request
object

{ body, headers, query } with {{param}} notation.

client_fields
object

Fields sent to the client-side action with {{param}} notation.

HTTP Errors

401
UNAUTHORIZED

No valid API key.

Get Tool

GET
#
GEThttps://api.vanira.io/tools/:id
Retrieve the full definition of a single tool by its UUID.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

The unique ID of the tool.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/tools/e2705199-b431-4091-ad7c-ca1110b8e025'

Expected Response — 200 OK

json
1{2  "id": "e2705199-...",3  "name": "check_order_status",4  "description": "Check the status of a customer order.",5  "ref_code": "check_order_status",6  "type": "server",7  "execution_mode": "blocking",8  "channels": ["voice_web", "voice_telephony"],9  "parameters": [10    { "name": "order_id", "type": "string", "description": "Order ID", "required": true }11  ],12  "server": { "url": "https://api.acme.com/orders", "method": "POST" },13  "request": {14    "body": { "order_id": "{{order_id}}", "source": "vanira" },15    "headers": { "X-API-Key": "sk-abc123" }16  }17}

HTTP Errors

401
UNAUTHORIZED

No valid API key.

404
TOOL_NOT_FOUND

Tool not found or not owned by the authenticated client.

Create Tool

POST
#
POSThttps://api.vanira.io/tools
Create a new tool. The tool is created at the client level — attach it to agents separately using POST /assistant/{id}/tools.
  • *Server tools** — describe what the AI extracts (parameters) and map to your webhook (request.body, headers, query). Use {{param_name}} for dynamic values, plain strings for static.
  • *Client tools — custom** — use two layers:
1. parameters — agent parameters (what the AI collects from chat)
  • *Client tools — two kinds:**
  • Preset — see Preset Tools for every preset_id and copy-paste POST /tools body
  • Custom — see Custom Client Tools for agent parameters + frontend payload mapping
If client_fields is omitted for a custom client tool, each parameter auto-maps to the same key in arguments.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

nameREQUIRED
string

Tool name — becomes the function name the AI calls.

descriptionREQUIRED
string

What the tool does. The AI reads this to decide when to call it.

ref_code
string

Optional reference code (slug). If omitted, one is generated from the name.

typeREQUIRED
string

"server" — HTTP webhook. "client" — UI action in the browser.

execution_mode
string

"blocking" = AI waits for result. "fire_and_forget" = AI continues. Default: blocking for server, fire_and_forget for client.

channels
array

voice_web | voice_telephony | chat | whatsapp. Defaults to [voice_web, voice_telephony].

parameters
array

What the AI extracts from the conversation. Each item: { name, type, description, required, enum? }.

server
object

Required when type is "server". { url, method: POST|GET|PUT|DELETE }

request
object

HTTP fields. If omitted, parameters auto-map to body by name. Use {{param}} for dynamic values.

client_fields
object

Frontend payload for client tools. Use {{param}} for agent values or static strings. Presets use preset_id and preset config keys.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/tools' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "check_order_status",5  "description": "Check the status of a customer order by order ID",6  "ref_code": "check_order_status",7  "type": "server",8  "execution_mode": "blocking",9  "channels": [10    "voice_web",11    "voice_telephony"12  ],13  "parameters": [14    {15      "name": "order_id",16      "type": "string",17      "description": "Order ID to check",18      "required": true19    }20  ],21  "server": {22    "url": "https://api.acme.com/orders",23    "method": "POST"24  },25  "request": {26    "body": {27      "order_id": "{{order_id}}",28      "source": "vanira"29    },30    "headers": {31      "X-API-Key": "sk-abc"32    },33    "query": {}34  },35  "client_fields": {36    "name": "{{customer_name}}",37    "source": "website"38  }39}'

Expected Response — 200 OK

json
1// Server tool example2{3  "name": "check_order_status",4  "description": "Check the status of a customer order",5  "ref_code": "check_order_status",6  "type": "server",7  "execution_mode": "blocking",8  "channels": ["voice_web", "voice_telephony"],9  "server": { "url": "https://api.acme.com/orders", "method": "POST" },10  "parameters": [11    {12      "name": "order_id",13      "type": "string",14      "description": "The order ID the customer mentioned",15      "required": true16    }17  ],18  "request": {19    "body":    { "order_id": "{{order_id}}", "source": "vanira" },20    "headers": { "X-API-Key": "sk-your-key" },21    "query":   {}22  }23}24 25// Client tool example26{27  "name": "show_location_map",28  "description": "Show an interactive map to the user for a location they asked about",29  "ref_code": "show_location_map",30  "type": "client",31  "execution_mode": "fire_and_forget",32  "channels": ["voice_web"],33  "parameters": [34    {35      "name": "location",36      "type": "string",37      "description": "The city or landmark to show on the map",38      "required": true39    }40  ],41  "client_fields": { "query": "{{location}}", "zoom": 12 }42}43 44// Custom client tool — agent params + frontend payload mapping45{46  "name": "say_hi",47  "description": "Show a greeting popup when the user says hello",48  "ref_code": "say_hi",49  "type": "client",50  "execution_mode": "fire_and_forget",51  "channels": ["voice_web"],52  "parameters": [],53  "client_fields": {}54}55 56// Custom client tool with mapped payload57{58  "name": "greet_user",59  "description": "Show a personalized greeting popup",60  "ref_code": "greet_user",61  "type": "client",62  "execution_mode": "blocking",63  "channels": ["voice_web"],64  "parameters": [65    {66      "name": "customer_name",67      "type": "string",68      "description": "The person's name from the conversation",69      "required": true70    }71  ],72  "client_fields": {73    "name": "{{customer_name}}",74    "source": "website"75  }76}

HTTP Errors

401
UNAUTHORIZED

No valid API key.

422
VALIDATION_ERROR

Missing required fields, or server.url not provided for type="server".

Update Tool

PATCH
#
PATCHhttps://api.vanira.io/tools/:id
Update a tool's name, description, URL, request body, headers, or parameters. All fields are optional — only what you send is updated.
When updating request fields, the full body/headers/query object is replaced. Parameters are preserved from the existing tool unless explicitly re-sent.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the tool to update.

Body Parameters

name
string

New tool name.

description
string

Updated description.

ref_code
string

Updated reference code (slug).

server
object

Updated server config { url, method }.

request
object

Updated request body/headers/query mapping. {{param}} notation supported.

client_fields
object

Updated client-side fields.

channels
array

Updated channel list.

parameters
array

Updated parameters list. Replaces existing ones.

Implementation Example

Environment
1curl -X PATCH 'https://api.vanira.io/tools/e2705199-b431-4091-ad7c-ca1110b8e025' \2  -H "Content-Type: application/json" \3  -d '{4  "name": "<name>",5  "description": "<description>",6  "ref_code": "<ref_code>",7  "server": "<server>",8  "request": "<request>",9  "client_fields": "<client_fields>",10  "channels": "<channels>",11  "parameters": [12    {13      "name": "order_id",14      "type": "string",15      "description": "Order ID",16      "required": true17    }18  ]19}'

HTTP Errors

401
UNAUTHORIZED

No valid API key.

404
TOOL_NOT_FOUND

Tool not found or not owned by the authenticated client.

Delete Tool

DELETE
#
DELETEhttps://api.vanira.io/tools/:id
Permanently delete a tool and remove it from all agents it is attached to. Irreversible.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

UUID of the tool to delete.

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/tools/e2705199-b431-4091-ad7c-ca1110b8e025' \2  -H "Content-Type: application/json"

HTTP Errors

404
TOOL_NOT_FOUND

Tool not found or not owned by the authenticated client.

List Agent Tools

GET
#
GEThttps://api.vanira.io/assistant/:id/tools
Returns all tools currently attached to a specific agent.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Agent UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/assistant/28c591f1-f17c-4c46-82ac-4054a843007a/tools'

Expected Response — 200 OK

json
1{2  "tools": [3    {4      "id": "7ccfd8ea-...",5      "tool_id": "e2705199-...",6      "is_active": true,7      "name": "show_location_map",8      "ref_code": "show_location_map",9      "type": "client",10      "execution_mode": "fire_and_forget",11      "channels": ["voice_web"],12      "parameters": [13        { "name": "location_query", "type": "string", "required": true }14      ],15      "client_fields": { "query": "{{location_query}}" }16    }17  ],18  "total": 119}

Response Schema Details

idREQUIRED
uuid

agent_actions join record ID — use this to detach the tool.

tool_idREQUIRED
uuid

base_actions ID — use this to reference the tool definition.

is_activeREQUIRED
boolean

Whether the tool is active for this agent.

HTTP Errors

401
UNAUTHORIZED

No valid API key.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

Attach Tool to Agent

POST
#
POSThttps://api.vanira.io/assistant/:id/tools
Attach an existing tool to an agent. The tool must have been created via POST /tools first.
Tools are reusable — the same tool can be attached to multiple agents.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Agent UUID.

Body Parameters

tool_idREQUIRED
uuid

UUID of the tool to attach (from GET /tools).

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/assistant/28c591f1-f17c-4c46-82ac-4054a843007a/tools' \2  -H "Content-Type: application/json" \3  -d '{4  "tool_id": "e2705199-b431-4091-ad7c-ca1110b8e025"5}'

Expected Response — 200 OK

json
1{2  "id": "7ccfd8ea-8c99-4022-82e3-7c68bdb8d02b",3  "is_active": true4}

HTTP Errors

401
UNAUTHORIZED

No valid API key.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

404
TOOL_NOT_FOUND

Tool not found or not owned by the authenticated client.

Detach Tool from Agent

DELETE
#
DELETEhttps://api.vanira.io/assistant/:id/tools/:tool_id
Remove a tool from an agent. The tool definition is not deleted — only the attachment is removed.
Use the id from GET /assistant/{id}/tools (the agent_actions ID, not the tool_id).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

idREQUIRED
uuid

Agent UUID.

tool_idREQUIRED
uuid

The agent_actions.id from GET /assistant/{id}/tools — NOT the base tool ID.

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/assistant/28c591f1-f17c-4c46-82ac-4054a843007a/tools/7ccfd8ea-8c99-4022-82e3-7c68bdb8d02b' \2  -H "Content-Type: application/json"

HTTP Errors

401
UNAUTHORIZED

No valid API key.

404
AGENT_NOT_FOUND

Agent or attachment not found.

Crawl Website

POST
#
POSThttps://api.vanira.io/knowledge/crawl
Crawl a website (Firecrawl) and return onboarding suggestions — routes, use cases, agent prompt, welcome message, and presets.
  • *Rate limited** (heavy). Requires knowledge:write.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Body Parameters

urlREQUIRED
string

Site URL to crawl.

purposeREQUIRED
string

What the agent should accomplish.

deploymentREQUIRED
string

web | app.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/knowledge/crawl' \2  -H "Content-Type: application/json" \3  -d '{4  "url": "https://example.com",5  "purpose": "Answer product questions",6  "deployment": "web"7}'

Expected Response — 200 OK

json
1{2  "job_id": "crawl-job-...",3  "purpose": "Answer product questions",4  "deployment": "web",5  "needs_navigation": true,6  "needs_on_page_guide": false,7  "suggested_agent_name": "Example Support",8  "routes": [],9  "use_cases": [],10  "site_summary": "...",11  "agent_prompt": "...",12  "welcome_message": "...",13  "suggested_presets": []14}

Response Schema Details

job_idREQUIRED
string

Crawl job identifier.

suggested_agent_name
string

Suggested agent display name.

agent_prompt
string

Generated system prompt.

welcome_message
string

Suggested first message.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key.

422
VALIDATION_ERROR

Invalid url / purpose / deployment.

502
UPSTREAM_SERVICE_ERROR

Crawl provider failure.

FAQ Status

GET
#
GEThttps://api.vanira.io/knowledge/agents/:agent_id/status
Returns whether the agent has vectors and how many FAQs are stored.
  • *Ownership enforced** — agent must belong to the authenticated client. Proxies coreinfra GET /knowledge/agents/{agent_id}/status.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/knowledge/agents/3a607fa1-5beb-46a6-beb3-c8118392980e/status'

Expected Response — 200 OK

json
1{2  "agent_id": "3a607fa1-5beb-46a6-beb3-c8118392980e",3  "has_vectors": true,4  "faq_count": 15}

Response Schema Details

agent_idREQUIRED
uuid

Agent UUID.

has_vectorsREQUIRED
boolean

Whether Qdrant has vectors for this agent.

faq_countREQUIRED
number

Number of FAQ rows.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key / JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

502
UPSTREAM_SERVICE_ERROR

coreinfra / Hasura / Cohere / Qdrant failure.

List FAQs

GET
#
GEThttps://api.vanira.io/knowledge/agents/:agent_id/faqs
List FAQs for an agent with optional search.
  • *Ownership enforced.** Proxies coreinfra list (embed/index side effects already applied at write time).

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

Query Parameters

limit
number

Page size (1–500). Default 100.

offset
number

Pagination offset. Default 0.

q
string

Optional search on question/answer.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/knowledge/agents/3a607fa1-5beb-46a6-beb3-c8118392980e/faqs?limit=100&offset=0&q=support%20hours'

Expected Response — 200 OK

json
1{2  "agent_id": "3a607fa1-5beb-46a6-beb3-c8118392980e",3  "faqs": [4    {5      "id": "a1ca5da3-1cd1-40d1-9671-7c7f6192fca9",6      "agent_id": "3a607fa1-5beb-46a6-beb3-c8118392980e",7      "question": "which courses do you support",8      "answer": "we support finance to tech to life style courses",9      "qdrant_id": "79e37cac-2bc5-49b6-a66c-9ccb8683069d",10      "document_id": null11    }12  ],13  "total": 114}

Response Schema Details

agent_idREQUIRED
uuid

Agent UUID.

faqsREQUIRED
array

FAQ objects.

totalREQUIRED
number

Total matching FAQs.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key / JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

502
UPSTREAM_SERVICE_ERROR

coreinfra / Hasura / Cohere / Qdrant failure.

Get FAQ

GET
#
GEThttps://api.vanira.io/knowledge/agents/:agent_id/faqs/:faq_id
Retrieve a single FAQ by ID. Ownership enforced via agent.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

faq_idREQUIRED
uuid

FAQ UUID.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/knowledge/agents/3a607fa1-5beb-46a6-beb3-c8118392980e/faqs/48071789-080a-4b9a-8442-fc55e1e68314'

Expected Response — 200 OK

json
1{2  "id": "48071789-080a-4b9a-8442-fc55e1e68314",3  "agent_id": "3a607fa1-5beb-46a6-beb3-c8118392980e",4  "question": "What are your support hours?",5  "answer": "We support customers from 9 AM to 6 PM IST on weekdays.",6  "qdrant_id": "48071789-080a-4b9a-8442-fc55e1e68314",7  "document_id": null8}

Response Schema Details

idREQUIRED
uuid

FAQ UUID.

agent_idREQUIRED
uuid

Owning agent UUID.

questionREQUIRED
string

FAQ question text.

answerREQUIRED
string

FAQ answer text.

qdrant_id
uuid

Vector store point ID (coreinfra / Qdrant).

document_id
uuid

Optional linked document ID.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key / JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

502
UPSTREAM_SERVICE_ERROR

coreinfra / Hasura / Cohere / Qdrant failure.

404
FAQ_NOT_FOUND

FAQ does not exist for this agent.

Create FAQ

POST
#
POSThttps://api.vanira.io/knowledge/agents/:agent_id/faqs
Create one FAQ. coreinfra embeds the question (Cohere), upserts Qdrant, inserts faq_data, and updates agent.knowledge_base_vector_count.
  • *Ownership enforced.**

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

Body Parameters

questionREQUIRED
string

FAQ question.

answerREQUIRED
string

FAQ answer.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/knowledge/agents/3a607fa1-5beb-46a6-beb3-c8118392980e/faqs' \2  -H "Content-Type: application/json" \3  -d '{4  "question": "What are your support hours?",5  "answer": "We support customers from 9 AM to 6 PM IST on weekdays."6}'

Expected Response — 200 OK

json
1{2  "id": "48071789-080a-4b9a-8442-fc55e1e68314",3  "agent_id": "3a607fa1-5beb-46a6-beb3-c8118392980e",4  "question": "What are your support hours?",5  "answer": "We support customers from 9 AM to 6 PM IST on weekdays.",6  "qdrant_id": "48071789-080a-4b9a-8442-fc55e1e68314",7  "document_id": null8}

Response Schema Details

idREQUIRED
uuid

FAQ UUID.

agent_idREQUIRED
uuid

Owning agent UUID.

questionREQUIRED
string

FAQ question text.

answerREQUIRED
string

FAQ answer text.

qdrant_id
uuid

Vector store point ID (coreinfra / Qdrant).

document_id
uuid

Optional linked document ID.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key / JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

502
UPSTREAM_SERVICE_ERROR

coreinfra / Hasura / Cohere / Qdrant failure.

400
VALIDATION_ERROR

question or answer missing / invalid.

Bulk Create FAQs

POST
#
POSThttps://api.vanira.io/knowledge/agents/:agent_id/faqs/bulk
Create up to 100 FAQs in one request. Same embed/Qdrant side effects per item. Ownership enforced.
  • *Request body (canonical):**
Code examplejson
1{ "items": [ { "question": "...", "answer": "..." } ] }
Dashboard bulk UI also accepts a bare JSON array or CSV with header question,answer.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

Body Parameters

itemsREQUIRED
array

Array of { question, answer } (max 100). Canonical wrapper: { "items": [...] }.

Implementation Example

Environment
1curl -X POST 'https://api.vanira.io/knowledge/agents/3a607fa1-5beb-46a6-beb3-c8118392980e/faqs/bulk' \2  -H "Content-Type: application/json" \3  -d '{4  "items": [5    {6      "question": "Do you offer refunds?",7      "answer": "Yes, within 7 days."8    }9  ]10}'

Expected Response — 200 OK

json
1{2  "agent_id": "3a607fa1-5beb-46a6-beb3-c8118392980e",3  "created": [4    {5      "id": "468ae249-5cb4-47ea-907b-196df087efed",6      "agent_id": "3a607fa1-5beb-46a6-beb3-c8118392980e",7      "question": "Do you offer refunds?",8      "answer": "Yes, within 7 days of purchase.",9      "qdrant_id": "468ae249-5cb4-47ea-907b-196df087efed",10      "document_id": null11    }12  ],13  "count": 114}

Response Schema Details

agent_idREQUIRED
uuid

Agent UUID.

createdREQUIRED
array

Created FAQ objects.

countREQUIRED
number

Number created.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key / JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

502
UPSTREAM_SERVICE_ERROR

coreinfra / Hasura / Cohere / Qdrant failure.

400
VALIDATION_ERROR

items empty, >100, or invalid entries.

Update FAQ

PUT
#
PUThttps://api.vanira.io/knowledge/agents/:agent_id/faqs/:faq_id
Full replace of question/answer. Re-embeds and upserts the same Qdrant point. Ownership enforced.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

faq_idREQUIRED
uuid

FAQ UUID.

Body Parameters

questionREQUIRED
string

Updated question.

answerREQUIRED
string

Updated answer.

Implementation Example

Environment
1curl -X PUT 'https://api.vanira.io/knowledge/agents/3a607fa1-5beb-46a6-beb3-c8118392980e/faqs/48071789-080a-4b9a-8442-fc55e1e68314' \2  -H "Content-Type: application/json" \3  -d '{4  "question": "<question>",5  "answer": "<answer>"6}'

Expected Response — 200 OK

json
1{2  "id": "48071789-080a-4b9a-8442-fc55e1e68314",3  "agent_id": "3a607fa1-5beb-46a6-beb3-c8118392980e",4  "question": "What are your support hours?",5  "answer": "We support customers from 9 AM to 9 PM IST every day.",6  "qdrant_id": "48071789-080a-4b9a-8442-fc55e1e68314",7  "document_id": null8}

Response Schema Details

idREQUIRED
uuid

FAQ UUID.

agent_idREQUIRED
uuid

Owning agent UUID.

questionREQUIRED
string

FAQ question text.

answerREQUIRED
string

FAQ answer text.

qdrant_id
uuid

Vector store point ID (coreinfra / Qdrant).

document_id
uuid

Optional linked document ID.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key / JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

502
UPSTREAM_SERVICE_ERROR

coreinfra / Hasura / Cohere / Qdrant failure.

404
FAQ_NOT_FOUND

FAQ does not exist for this agent.

Delete FAQ

DELETE
#
DELETEhttps://api.vanira.io/knowledge/agents/:agent_id/faqs/:faq_id
Delete one FAQ (and its vector). Returns 204 empty body. Ownership enforced.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

faq_idREQUIRED
uuid

FAQ UUID.

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/knowledge/agents/3a607fa1-5beb-46a6-beb3-c8118392980e/faqs/48071789-080a-4b9a-8442-fc55e1e68314' \2  -H "Content-Type: application/json"

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key / JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

502
UPSTREAM_SERVICE_ERROR

coreinfra / Hasura / Cohere / Qdrant failure.

404
FAQ_NOT_FOUND

FAQ does not exist for this agent.

Delete All FAQs

DELETE
#
DELETEhttps://api.vanira.io/knowledge/agents/:agent_id/faqs
Delete every FAQ for the agent. Ownership enforced.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Path Parameters

agent_idREQUIRED
uuid

Agent UUID.

Implementation Example

Environment
1curl -X DELETE 'https://api.vanira.io/knowledge/agents/3a607fa1-5beb-46a6-beb3-c8118392980e/faqs' \2  -H "Content-Type: application/json"

Expected Response — 200 OK

json
1{2  "agent_id": "3a607fa1-5beb-46a6-beb3-c8118392980e",3  "deleted_count": 24}

Response Schema Details

agent_idREQUIRED
uuid

Agent UUID.

deleted_countREQUIRED
number

Number of FAQs deleted.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key / JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

502
UPSTREAM_SERVICE_ERROR

coreinfra / Hasura / Cohere / Qdrant failure.

GEThttps://api.vanira.io/knowledge/search
Semantic retrieval over the agent FAQ vectors. Proxies coreinfra /knowledgeSearch.
Multiple hits are joined with blank lines. Empty string when nothing is above threshold. Ownership enforced.

Required Headers

X-API-KeyREQUIRED
string

Your Sovereign API key. Securely authorizes all requests.

Content-TypeREQUIRED
string

Must be application/json

Query Parameters

queryREQUIRED
string

Search text.

agent_idREQUIRED
uuid

Agent UUID.

threshold
number

Score threshold. Default 0.

limit
number

Max hits (1–50). Default 5.

Implementation Example

Environment
1curl -X GET 'https://api.vanira.io/knowledge/search?query=support%20hours&agent_id=3a607fa1-5beb-46a6-beb3-c8118392980e&threshold=0&limit=5'

Expected Response — 200 OK

json
1{2  "results": "Question: which courses do you support Answer: we support finance to tech to life style courses"3}

Response Schema Details

resultsREQUIRED
string

Joined retrieval hits, or empty string.

HTTP Errors

401
UNAUTHORIZED

Missing or invalid API key / JWT.

404
AGENT_NOT_FOUND

Agent not found or not owned by the authenticated client.

502
UPSTREAM_SERVICE_ERROR

coreinfra / Hasura / Cohere / Qdrant failure.

400
VALIDATION_ERROR

query or agent_id missing.