API Reference
v1.0Multimodal 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 .
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-commerceLive camera inspection, guided return UI, and multimodal refund confirmation.
Kisan Support Agent
AgricultureFarmer-facing welfare intake — live camera, forms, regional languages.
Citizen Services Agent
Citizen accessVoice-guided portal navigation — search, dates, and forms in regional language.
Starter repos
vanira-starter-web
Vite + React + VaniraCallBox — voice pill and presets in minutes.
About the SDK
What you get in one WebRTC session
| Layer | Capability |
|---|---|
| Voice | Bidirectional audio, transcription, barge-in |
| Vision | Snapshot upload + live camera + live screen share |
| UI presets | Forms, calendar, navigate, click, upload, whiteboard, … |
| Routing | SPA navigation, page context sync, media reason tags |
Two integration paths — pick one
| Path | When to use |
|---|---|
| Widget embed | No-code / marketing sites — paste a script tag, Vanira renders the UI |
| npm SDK | Developers building React, Next.js, Vue, or vanilla apps with their own UI |
npm integration surfaces
| Surface | Import | What you get |
|---|---|---|
VaniraCallBox | @vanira/sdk | Voice pill + presets + custom tool hook |
| Headless | @vanira/sdk/headless | VaniraClient + PresetRenderer — you build the call UI |
Build a Saathi-style tutor
What you need
- Agent ID from the dashboard
- Publishable key
pk_live_*for browser code (ortokeninside the Vanira dashboard) - No backend URL — the SDK uses Vanira's cloud API automatically
Read next (in order)
2. Widget — script-tag embed
3. SDK Installation —
npm install @vanira/sdk4. 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
Widget Embed
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><vanira-convai> custom element on document.body. It survives SPA route changes because it lives outside your React/Vue tree.SPA navigation
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 (
useRouterin Next.js App Router). The widget custom element stays ondocument.body, so route changes do not tear down the call.
- *Plain HTML / multi-page** — add once on your site:
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:
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}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}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}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}vanira_navigate, the SDK dispatches a browser event instead of forcing a full page reload:| Target | SDK 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:navigatelistener** that routes with your framework and setsevent.detail.handled = true. Without it, same-origin navigation fails withstatus: cancelledand 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 (
useRouterin Next.js App Router). The widget custom element stays ondocument.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
Powered by Vanira
SDK Installation
@vanira/sdk when you want VaniraCallBox or a headless integration with your own UI.1npm install @vanira/sdk2# or3yarn add @vanira/sdkImports
| Use case | Import |
|---|---|
| Drop-in voice pill | import { VaniraCallBox } from '@vanira/sdk' |
| Your own call UI | import { 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
API Keys & Configuration
API keys
| Key | Where | Use |
|---|---|---|
pk_live_* | Browser, widget embed, VaniraCallBox | Web calls only — safe for frontend |
sk_live_* | Your backend only | Full API access — never expose in browser code |
apiKey: 'pk_live_…' in browser integrations. The SDK provisions the call and opens WebRTC — no backend URL, no manual REST calls.data-pk-key. Inside the Vanira dashboard, VaniraCallBox can use token (Bearer JWT) instead of apiKey.VaniraCallBox props
| Prop | Required | Description |
|---|---|---|
agentId | Yes | Agent UUID from dashboard |
apiKey | Yes* | pk_live_* for external sites |
token | Yes* | Dashboard Bearer JWT (*one of apiKey or token) |
onNavigate | Recommended | SPA router hook for vanira_navigate preset |
onCustomTool | As needed | Handler for custom client tools (not presets) |
sessionBehavior | No | 'new' (default) or 'continue' |
autoStart | No | Default false — tap-to-talk |
onMinimize / onClose | No | Host UI callbacks |
VaniraClient props
| Prop | Required | Description |
|---|---|---|
agentId | Yes | Agent UUID |
apiKey or token | Yes* | Auth (*unless serverUrl + callId + iceServers pre-supplied) |
sessionBehavior | No | 'new' or 'continue' |
prospectId / callId | No | Manual session resume |
trackRouteContext | No | Default true — auto page-route context sync |
onConnected / onDisconnected / onError | Recommended | Lifecycle callbacks |
onClientToolCall | As needed | All client tool calls (presets + custom) |
onTranscription | No | User speech-to-text stream |
.on(event) + start() — same class, two styles.Example
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.agentId + apiKey required. Mount above your router so SPA navigation does not tear down the call.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
onCustomToolonly - Do not mount inside a single page behind
{showCall && …}on multi-route SPAs
Custom call button (optional)
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
@vanira/sdk/headless: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}1<PresetRenderer ref={presetRef} client={client} onCustomTool={handleCustomTool} />Callbacks or events
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();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.
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 ID | UI | Mode |
|---|---|---|
vanira_form | Data Collection Form | blocking |
vanira_phone | Mobile number | blocking |
vanira_mcq | Multiple Choice Question | blocking |
vanira_calendar | Date & Time Picker | blocking |
vanira_upload | File Upload | blocking |
vanira_camera | Camera Capture | fire_and_forget |
vanira_navigate | Navigate to Route — requires vanira:navigate listener on SPAs | blocking |
vanira_highlight_element | Highlight Element | blocking |
vanira_click_element | Click Element | blocking |
vanira_select_option | Select Dropdown Option | blocking |
vanira_set_date | Set Date Field | blocking |
vanira_type_text | DOM Typing Simulation | blocking |
vanira_write_latex_text | Chalkboard LaTeX Writer | blocking |
vanira_erase_text | Whiteboard / DOM Erase | blocking |
vanira_live_vision | Live Vision (Streaming Camera) | fire_and_forget |
vanira_close_live_camera | Stop Live Camera | blocking |
vanira_live_screen | Live Screen Share | fire_and_forget |
vanira_close_live_screen | Stop Live Screen Share | blocking |
vanira_clip_region | Page Region Clip | blocking |
vanira_screen_vision | Screen Vision | blocking |
vanira_point_at | Point At Screen | blocking |
vanira_draw_on_screen | Draw On Screen | blocking |
vanira_clear_screen_draw | Clear Screen Drawings | blocking |
vanira_highlight_on_screen | Highlight On Screen | blocking |
vanira_kyc_document_capture | KYC Document Capture | blocking |
vanira_kyc_selfie_capture | KYC Selfie Capture | blocking |
vanira_kyc_signature_capture | KYC Signature Capture | blocking |
- *Blocking presets (most): the AI waits until the SDK calls `sendToolResult()`. fire_and_forget**:
vanira_camera,vanira_live_vision.
onCustomTool.Navigate preset — host-site setup
vanira_navigate, the SDK dispatches a browser event instead of forcing a full page reload:| Target | SDK 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:navigatelistener** that routes with your framework and setsevent.detail.handled = true. Without it, same-origin navigation fails withstatus: cancelledand 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 (
useRouterin Next.js App Router). The widget custom element stays ondocument.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
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.POST /tools JSON for every preset.React Integration Example
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
Two data layers (do not confuse them)
| Layer | Dashboard section | Who fills it | Where it lands in code |
|---|---|---|---|
| 1. Agent parameters | *Agent parameters* | The AI extracts from the conversation | Tool schema only — tells the AI what to collect |
| 2. Frontend payload | *Frontend payload* | You map keys → {{param}} or static values | call.arguments in onCustomTool |
- *Agent parameters** define the conversation contract (e.g.
customer_name,order_id).
- *Frontend payload** (
client_fieldsin 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 key | Value |
|---|---|
name | {{customer_name}} |
source | website |
- *At runtime** your handler receives:
1{2 "name": "Teja",3 "source": "website"4}call.arguments.Execution mode
| Mode | AI behavior | Your code |
|---|---|---|
blocking | Pauses until sendToolResult() | Must call client.sendToolResult(tool_call_id, result) |
fire_and_forget | Keeps speaking | No result required |
VaniraCallBox handler
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)
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}client_fields.preset_id — handled automatically by PresetRenderer, not onCustomTool.Tool call payload
| Field | Description |
|---|---|
name | Tool name or ref_code |
arguments | Resolved frontend payload your app reads |
tool_call_id | ID for sendToolResult() / sendToolError() |
execution_mode | blocking or fire_and_forget |
client_tool_ack within ~2.3s — you do not ack manually.On error or cancel
sendToolError(tool_call_id, message) when the operation fails so the agent can recover: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.
onConnected, …) or .on('connected', …) + start() — same events either way.| Event / callback | When it fires |
|---|---|
onSessionStarted / session_started | Session provisioned — not live yet |
onConnected / connected | WebRTC live — show your "connected" UI here |
onDisconnected / disconnected | Call ended |
onError / error | Connection or permission failure |
onTranscription / transcription | User speech-to-text (isFinal flag) |
onLocalStream | Microphone stream ready |
onRemoteTrack | Agent audio/video track arrives |
onClientToolCall / tool_call | AI requested a browser action |
onSessionStarted. Wait for onConnected.VaniraClient Example
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
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.
prospectId and callId in browser storage after a call starts. With sessionBehavior: 'continue', the next connect() reuses that context.Storage Keys
| Key | Meaning |
|---|---|
vanira_prospect_id | The user/prospect identity used across chat and voice |
vanira_latest_call_id | The latest web-call session ID |
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 suppliedprospectIdandcallId.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 resolvedprospectId,callId, andserverUrl.
React Integration Example
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
Interrupt Audio Only
Interrupt Audio Only
interruptAudioOnly() for an audio-only interrupt.Code Example
1// Cut current agent audio output immediately2client.interruptAudioOnly();Ending a Call
disconnect() or stop() — both release the microphone, close the data channel, close the peer connection, and emit a disconnected event.Code Example
1client.disconnect();2client = null;3 4// React cleanup5useEffect(() => {6 return () => {7 clientRef.current?.disconnect();8 clientRef.current = null;9 };10}, []);Error Handling
serverUrl, failed /calls/create (Phase 1), or WebRTC/ICE failure reaching the worker (Phase 2).POST /calls/create in the network tab, Phase 1 succeeded but Phase 2 did not — check onError, microphone permission, and worker POST …/webrtc responses.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
| Symptom | Likely cause | What to do |
|---|---|---|
Only POST /calls/create in network tab | Phase 2 failed (mic, worker SDP, ICE) | Check onError; call connect() from button click; allow microphone |
onSessionStarted fires but never onConnected | Stuck in Phase 2 | Check worker /webrtc POST response and ICE; see console [WebRTC] logs |
serverUrl is missing | No apiKey and no manual worker URL | Pass apiKey, or pass serverUrl and callId from your backend |
createCall failed (401/403) | Invalid key, wrong scope, or origin mismatch | Check key type and origin setting |
| Microphone permission denied | Browser blocked mic access | Start from a user click and show permission guidance |
| DataChannel not open | Sending too early or after disconnect | Wait for onConnected before calling context/actions/uploads |
| Audio autoplay blocked | Browser policy | Start calls from a user gesture and keep audio element playback user-initiated |
Retry Pattern
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
connectingorconnected. - Call
disconnect()orstop()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
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.
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
sessionBehavior: 'continue' for the voice session.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
### 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.
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).
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)
client.uploadMedia(). The SDK uploads via WebRTC media-bytes (web) or HTTP fallback, then sends client_media_update so the agent runs process_media.Parameters
| Argument | Type | Required | Description | |
|---|---|---|---|---|
file | `File | Blob` | Yes | The file object to upload. Supported by the high-level SDK: JPEG, PNG, GIF, WEBP, BMP, and PDF up to 50 MB. |
reason | string | Yes | Category tag (e.g. 'kyc_document', 'error_screenshot'). Tells your backend webhook how to process this upload. | |
message | string | No | Optional text question or message to accompany the file (e.g. "What does this line item mean?"). | |
interruptFirst | boolean | No | Available on VaniraClient.uploadMedia(). Cuts current audio before upload without sending a duplicate action trigger. |
React File Upload Example
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
fileREQUIREDThe image or document to upload (JPEG, PNG, GIF, WEBP, BMP, PDF).
reasonREQUIREDThe routing category configured in the Dashboard (e.g. kyc_photo, general).
messageOptional text context to send alongside the image.
About the RN SDK
Package
| npm | @vanira/sdk-react-native |
|---|---|
| Import | import { 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)
npm install @vanira/sdk-react-native2. Native Setup — WebRTC globals, permissions, peer deps
3. Quick Start —
PresetHostProvider + createReactNativeAI4. Preset Handler (RN) — route tool calls with
setActiveToolCall()5. RN Events — lifecycle callbacks
6. Session Continuity (RN) — resume calls with AsyncStorage
RN Installation
1npm install @vanira/sdk-react-nativeVoice calls (required)
1npm install react-native-webrtc react-native-incall-manager react-native-permissions2cd ios && pod installregisterGlobals() in index.js — see Native Setup.Presets (install only what you use)
| Feature | Packages |
|---|---|
| Upload / camera | react-native-image-picker, @react-native-documents/picker |
| Screenshot / clip region | react-native-view-shot |
| Live vision | react-native-vision-camera |
Native Setup
1. WebRTC globals (required)
registerGlobals() once in index.js before any SDK import: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);RTCPeerConnection, getUserMedia) are undefined and calls fail.2. iOS permissions
ios/Podfile:1require_relative '../node_modules/react-native-permissions/scripts/setup'2 3setup_permissions([4 'Camera',5 'Microphone',6 'PhotoLibrary',7])1cd ios && pod installInfo.plist (NSMicrophoneUsageDescription, NSCameraUsageDescription, NSPhotoLibraryUsageDescription).3. Android permissions
AndroidManifest.xml: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)
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.
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) => ...} onNavigatewires React Navigation forvanira_navigatepresets
Headless SDK
@vanira/sdk/headless.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}VaniraAI, createReactNativeAI, PresetHostProvider, VaniraCallProvider, useVaniraCall, session storage helpers, preset utilities.Quick Start
Option A — VaniraCallBox (fastest)
Option B — Manual wiring
Step 1 — Wrap the app
PresetHostProvider mounts preset modals (upload, calendar, form, camera, etc.) above your screens.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
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
presetandtool_callevents tosetActiveToolCall() - Start calls from a button tap (microphone permission + audio routing)
- Use
ai.stop()on hang-up and clearsetAiClient(null)
Preset Handler (RN)
PresetRenderer mount needed.1ai.on('preset', ({toolCall}) => setActiveToolCall(toolCall));2ai.on('tool_call', (tc) => setActiveToolCall(tc));sendToolResult() when the user completes or cancels.| Preset ID | UI | Mode |
|---|---|---|
vanira_form | Data Collection Form | blocking |
vanira_phone | Mobile number | blocking |
vanira_mcq | Multiple Choice Question | blocking |
vanira_calendar | Date & Time Picker | blocking |
vanira_upload | File Upload | blocking |
vanira_camera | Camera Capture | fire_and_forget |
vanira_navigate | Navigate to Route — requires vanira:navigate listener on SPAs | blocking |
vanira_highlight_element | Highlight Element | blocking |
vanira_click_element | Click Element | blocking |
vanira_select_option | Select Dropdown Option | blocking |
vanira_set_date | Set Date Field | blocking |
vanira_type_text | DOM Typing Simulation | blocking |
vanira_write_latex_text | Chalkboard LaTeX Writer | blocking |
vanira_erase_text | Whiteboard / DOM Erase | blocking |
vanira_live_vision | Live Vision (Streaming Camera) | fire_and_forget |
vanira_close_live_camera | Stop Live Camera | blocking |
vanira_live_screen | Live Screen Share | fire_and_forget |
vanira_close_live_screen | Stop Live Screen Share | blocking |
vanira_clip_region | Page Region Clip | blocking |
vanira_screen_vision | Screen Vision | blocking |
vanira_point_at | Point At Screen | blocking |
vanira_draw_on_screen | Draw On Screen | blocking |
vanira_clear_screen_draw | Clear Screen Drawings | blocking |
vanira_highlight_on_screen | Highlight On Screen | blocking |
vanira_kyc_document_capture | KYC Document Capture | blocking |
vanira_kyc_selfie_capture | KYC Selfie Capture | blocking |
vanira_kyc_signature_capture | KYC Signature Capture | blocking |
Native deps by preset
| Preset | Extra packages |
|---|---|
| Voice only | react-native-webrtc |
| Upload | react-native-image-picker, @react-native-documents/picker |
| Camera | react-native-image-picker |
| Live vision | react-native-vision-camera |
| Calendar, form, navigate | SDK only |
Custom tools
tool_call handler before calling setActiveToolCall: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});RN Events
.on(event, handler) on VaniraAI (returned by createReactNativeAI):| Event | When it fires |
|---|---|
connected | WebRTC live — show "connected" UI |
disconnected | Call ended — clean up client ref |
error | Connection or permission failure |
transcription | User speech-to-text ({ text, isFinal }) |
preset | Agent triggered a built-in preset |
tool_call | Agent triggered any client tool (preset or custom) |
Example
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
VaniraClient:| Method | Purpose |
|---|---|
sendToolResult(id, result) | Reply to blocking tools |
sendToolError(id, message) | Report tool failure |
uploadMedia(file, reason, message) | Send image/PDF during call |
ai.stop() to end the session.Session Continuity (RN)
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();sessionBehavior | Behavior |
|---|---|
'new' (default) | Fresh call every time |
'continue' | Reuse stored prospect_id + call_id |
vanira_prospect_id, vanira_latest_call_id) via your storage adapter.Upload Media (RN)
uploadMedia(). The SDK handles the HTTP upload and sends client_media_update to the agent.vanira_upload) uses this automatically. For manual uploads: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
React Native file shape
{ uri, type, name, size? } — not File / Blob:1await ai.uploadMedia(2 {uri: asset.uri, type: 'image/jpeg', name: 'upload.jpg'},3 'general',4 'User uploaded a photo',5);triggerActionInterrupt() after uploadMedia() — the media update already notifies the agent.RN vs Web SDK
| Voice entry | VaniraCallBox or VaniraClient | VaniraCallBox or createReactNativeAI() |
|---|---|---|
| Headless | @vanira/sdk/headless | @vanira/sdk-react-native/headless |
| Preset UI | PresetRenderer or automatic in CallBox | Automatic in VaniraCallBox; or PresetHostProvider |
| Connect | client.connect() or client.start() | await ai.start() |
| Upload file type | File / Blob | { uri, type, name } |
| Session storage | localStorage / sessionStorage | Your AsyncStorage adapter |
| WebRTC setup | Browser APIs | registerGlobals() + native modules |
Template Agents
How it works
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_* keyMake your agent shareable
1https://vanira.io/import?agentId=YOUR_AGENT_IDFeatured templates
| Agent | Vertical | Platform | Import |
|---|---|---|---|
| Refund & Returns Agent | E-commerce | web | |
| Kisan Support Agent | Agriculture | react-native, web | |
| Maths Tutor Agent | Education | web | |
| Citizen Services Agent | Citizen access | web |
Starter Repositories
vanira-starter-web
- GitHub: https://github.com/VaniraAI/vanira-starter-web
- Deploy: One-click Vercel deploy
vanira-starter-rn
- GitHub: https://github.com/VaniraAI/vanira-starter-rn
agentId and pk_live_* from the dashboard.Developer Referral
1https://vanira.io/signup?ref=YOUR_CLIENT_ID&utm_source=referral- npm packages: @vanira/sdk · @vanira/react-native-sdk
- Docs: vanira.io/docs
- Community: Discord
- Gallery:
Built with Vanira
- Homepage showcase placement
- Backlink from docs
- Social promotion
Preset: Form
- *Dashboard:** Client tool → preset
vanira_form
- *LLM parameters (per call):**
reason,fields(comma-separated labels the agent chooses for this interaction), optionaltitle
- *client_fields:**
preset_idonly required; optionaltitle/fieldsas fallbacks when the model omits them.
PresetRenderer) and React Native (PresetHost) with zero custom UI code.| Preset ID | UI | Mode |
|---|---|---|
vanira_form | Data Collection Form | blocking |
vanira_phone | Mobile number | blocking |
vanira_mcq | Multiple Choice Question | blocking |
vanira_calendar | Date & Time Picker | blocking |
vanira_upload | File Upload | blocking |
vanira_camera | Camera Capture | fire_and_forget |
vanira_navigate | Navigate to Route — requires vanira:navigate listener on SPAs | blocking |
vanira_highlight_element | Highlight Element | blocking |
vanira_click_element | Click Element | blocking |
vanira_select_option | Select Dropdown Option | blocking |
vanira_set_date | Set Date Field | blocking |
vanira_type_text | DOM Typing Simulation | blocking |
vanira_write_latex_text | Chalkboard LaTeX Writer | blocking |
vanira_erase_text | Whiteboard / DOM Erase | blocking |
vanira_live_vision | Live Vision (Streaming Camera) | fire_and_forget |
vanira_close_live_camera | Stop Live Camera | blocking |
vanira_live_screen | Live Screen Share | fire_and_forget |
vanira_close_live_screen | Stop Live Screen Share | blocking |
vanira_clip_region | Page Region Clip | blocking |
vanira_screen_vision | Screen Vision | blocking |
vanira_point_at | Point At Screen | blocking |
vanira_draw_on_screen | Draw On Screen | blocking |
vanira_clear_screen_draw | Clear Screen Drawings | blocking |
vanira_highlight_on_screen | Highlight On Screen | blocking |
vanira_kyc_document_capture | KYC Document Capture | blocking |
vanira_kyc_selfie_capture | KYC Selfie Capture | blocking |
vanira_kyc_signature_capture | KYC Signature Capture | blocking |
Preset: Upload
- *Snapshot upload** — user picks one file during a call.
| Step | Behavior |
|---|---|
| Upload | client.uploadMedia() → WebRTC or HTTP |
| Notify | client_media_update with media_id, media_url, reason |
| Agent | Calls process_media and responds |
- *Web accept:**
image/*,application/pdf,text/plain,text/csv
- *React Native:** requires
react-native-image-picker+ document picker peer deps.
- *Routing:** set
reasoninclient_fields(e.g.kyc_document,general) for webhook/vision pipeline routing.
- *Web:** listen for
vanira:navigateor useonNavigateonVaniraCallBox.
- *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 (
useRouterin Next.js App Router). The widget custom element stays ondocument.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_urlor 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)
1open_live_camera2 → client_live_camera_started3 → uploadMediaFrame() per frame (HTTP)4 → client_media_frame (NOT client_media_update)5 → client_live_camera_stoppedTool / client_fields
| Field | Notes | ||
|---|---|---|---|
scope | full_call | until_call_end | timed |
target_fps | Default 1, max 3 | ||
max_width | Resize before upload (px) | ||
reason | Default camera_capture — media routing tag | ||
duration_sec | Required for timed scope |
- *Agent config:** Agent → Vision LLM → live vision scope & defaults.
- *Web auto-start:**
liveVision: { enabled: true, scope: 'full_call' }onVaniraClient.
- *React Native:**
react-native-vision-camerarequired. SeeLiveVisionCameraHost.
Preset: Live Screen
- *Live screen share stream** (~1 fps) — same protocol as live camera, different capture source.
Client sequence
1open_live_screen2 → client_live_screen_started { display_surface, … }3 → uploadMediaFrame() per frame4 → client_media_frame { source: 'screen', … }5 → client_live_screen_stoppeduploadMediaFrame() + client_media_frame only — never uploadMedia() / client_media_update.- *Web:**
getDisplayMediainWidgetPresetRenderer.
- *React Native:**
getDisplayMedia+ view-shot on preview (best-effort on mobile).
- *reason:** default
screen_capture.
https://api.vanira.io/discovery/providersRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/discovery/providers'Expected Response — 200 OK
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
nameREQUIREDProvider identifier used in agent config.
typeREQUIREDai | tts | stt.
HTTP Errors
UNAUTHORIZEDNo valid API key provided.
https://api.vanira.io/discovery/modelsmodel field. Only status: "active" models are returned.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/discovery/models'Expected Response — 200 OK
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
idREQUIREDInternal model UUID (not needed for API calls).
nameREQUIREDModel name to use in agent model.model field. e.g. gpt-4.1-mini
ai_providerREQUIREDProvider string to use in agent model.provider field. e.g. AZURE, AZURE_REALTIME, GROQ
statusREQUIREDactive | inactive. Only active models are returned.
HTTP Errors
UNAUTHORIZEDNo valid API key provided.
https://api.vanira.io/discovery/vision-modelsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/discovery/vision-models'Expected Response — 200 OK
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
nameREQUIREDModel name for vision_model field.
ai_providerREQUIREDProvider for vision_provider field.
is_activeREQUIREDWhether the model is currently available.
HTTP Errors
UNAUTHORIZEDNo valid API key provided.
https://api.vanira.io/discovery/voicesvoice field.demo_audio_url— legacy single sample (kept for backward compatibility)previews— array of language-specific samples fromtts_voice_previews({ language, audio_url }). Prefer this when picking a clip for a caller's language.
Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/discovery/voices'Expected Response — 200 OK
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
idREQUIREDInternal voice UUID (not needed for API calls).
nameREQUIREDVoice name to use in agent voice.name field. e.g. Riya Rao
tts_providerREQUIREDProvider to use in agent voice.provider field. e.g. ELEVENLABS, SARVAM
languagePrimary language of the voice. e.g. ENGLISH, HINDI, hi
genderMALE | FEMALE
statusREQUIREDactive | inactive. Only active voices are returned.
demo_audio_urlLegacy single demo clip URL. Still returned when set; prefer previews[] for language-specific audio.
previewsREQUIREDLanguage-specific preview clips. Each item: { language: string (e.g. hi, en, te), audio_url: string }. Empty array when none exist.
HTTP Errors
UNAUTHORIZEDNo valid API key provided.
https://api.vanira.io/discovery/transcription-modelstranscription field.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/discovery/transcription-models'Expected Response — 200 OK
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
idREQUIREDInternal model UUID (not needed for API calls).
nameREQUIREDModel name to use in agent transcription.model field. e.g. nova-2, saaras:v3
providerREQUIREDProvider to use in agent transcription.provider field. e.g. DEEPGRAM, SARVAM
statusREQUIREDactive | inactive. Only active models are returned.
HTTP Errors
UNAUTHORIZEDNo valid API key provided.
https://api.vanira.io/discovery/ambient-noise-typesambient_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
noneto disable ambient (volume treated as 0)
Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/discovery/ambient-noise-types'Expected Response — 200 OK
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
valueREQUIREDStable id for agent.ambient_noise_type.
labelREQUIREDSuggested UI label.
descriptionREQUIREDHelper text for the dashboard.
defaults.ambient_noise_typeREQUIREDPlatform default when agent field is null.
defaults.ambient_noise_volumeREQUIREDPlatform default volume in [0, 1].
HTTP Errors
UNAUTHORIZEDNo valid API key provided.
https://api.vanira.io/discovery/ice-serversRTCPeerConnection({ iceServers: [...] }) or use the SDK's VaniraClient.fetchIceServers(apiKey) helper which calls this endpoint automatically.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/discovery/ice-servers'Expected Response — 200 OK
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
urlsREQUIREDList of STUN/TURN URLs for this server.
usernameTURN username. null for STUN-only servers.
credentialTURN password/credential. null for STUN-only servers.
HTTP Errors
UNAUTHORIZEDNo valid API key provided.
https://api.vanira.io/discovery/industriesRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/discovery/industries'Expected Response — 200 OK
1[2 {3 "id": "ind-uuid-...",4 "name": "Healthcare",5 "description": "Clinics and hospitals",6 "icon_key": "healthcare"7 }8]HTTP Errors
UNAUTHORIZEDNo valid API key provided.
https://api.vanira.io/discovery/use-casesRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/discovery/use-cases'Expected Response — 200 OK
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
UNAUTHORIZEDNo valid API key provided.
https://api.vanira.io/api-keys/generatesk_live_*) or publishable (pk_live_*) API key. The full key is returned once.- *Authentication**
Authorization: Bearer <kinde_jwt> with scope keys:manage. Secret API keys typically cannot manage other keys.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
nameREQUIREDLabel for the key.
key_typeREQUIREDsecret | publishable.
allowed_originsCORS origins for publishable keys. Use ["*"] to allow all.
Implementation Example
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
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
keyREQUIREDFull API key value (shown once).
key_maskREQUIREDMasked form stored for listing.
key_typeREQUIREDsecret | publishable.
HTTP Errors
UNAUTHORIZEDMissing or invalid JWT.
INSUFFICIENT_SCOPEMissing keys:manage scope.
https://api.vanira.io/api-keys- *Authentication**
Authorization: Bearer <kinde_jwt> with scope keys:manage. Secret API keys typically cannot manage other keys.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/api-keys'Expected Response — 200 OK
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
UNAUTHORIZEDMissing or invalid JWT.
INSUFFICIENT_SCOPEMissing keys:manage scope.
https://api.vanira.io/api-keys/:key_id- *Authentication**
Authorization: Bearer <kinde_jwt> with scope keys:manage. Secret API keys typically cannot manage other keys.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
key_idREQUIREDAPI key UUID from list.
Implementation Example
1curl -X DELETE 'https://api.vanira.io/api-keys/<key_id>' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1{2 "revoked": true,3 "message": "API key revoked"4}HTTP Errors
KEY_NOT_FOUNDKey not found.
https://api.vanira.io/api-keys/:key_id/origins- *Authentication**
Authorization: Bearer <kinde_jwt> with scope keys:manage. Secret API keys typically cannot manage other keys.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
key_idREQUIREDAPI key UUID.
Body Parameters
allowed_originsREQUIREDOrigin allowlist. Use ["*"] for all.
Implementation Example
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
1{2 "id": "key-uuid-...",3 "allowed_origins": ["https://app.example.com"]4}HTTP Errors
KEY_NOT_FOUNDKey not found.
VALIDATION_ERRORInvalid origins array.
https://api.vanira.io/phone-numbersThis includes both bought numbers and numbers imported from external providers.
Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/phone-numbers'Expected Response — 200 OK
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
numberREQUIREDThe phone number in E.164 format (digits only).
country_codeREQUIREDISO 2-letter country code.
labelREQUIREDHuman-readable label for the number.
agent_idID of the agent currently handling calls for this number.
is_activeREQUIREDWhether the number is ready to receive and make calls.
is_vanira_internalREQUIREDIf true, this number belongs to the Vanira shared pool.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
BAD_REQUESTMissing client_id.
https://api.vanira.io/phone-numbers/vaniraRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Query Parameters
include_inactiveInclude inactive numbers. Default false.
Implementation Example
1curl -X GET 'https://api.vanira.io/phone-numbers/vanira?include_inactive=false'Expected Response — 200 OK
1{2 "numbers": [3 {4 "number": "+918071387205",5 "is_active": true,6 "label": "Vanira pool"7 }8 ]9}HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
https://api.vanira.io/phone-numbers/inventoryRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Query Parameters
countryISO country code. Default IN.
pagePage number.
per_pagePage size.
Implementation Example
1curl -X GET 'https://api.vanira.io/phone-numbers/inventory?country=IN&page=1&per_page=20'Expected Response — 200 OK
1{2 "numbers": [3 { "phone_number": "+9180XXXXXXX", "country": "IN", "monthly_price": "..." }4 ],5 "page": 16}HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
https://api.vanira.io/phone-numbers/buyRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
phone_numberREQUIREDE.164 number from inventory.
Implementation Example
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
1{2 "phone_number": "+918071387205",3 "purchased": true4}HTTP Errors
BAD_REQUESTNumber unavailable or invalid.
INSUFFICIENT_CREDITSBilling / credits issue.
https://api.vanira.io/phone-numbers/importRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
phone_numberREQUIREDE.164 phone number (e.g. +918071387205).
agent_idREQUIREDID of the agent who will handle calls.
vobiz_auth_idVoBiz X-Auth-ID. Required for first-time import.
vobiz_auth_tokenVoBiz X-Auth-Token. Required for first-time import.
use_existing_credentialsUse previously stored credentials for this client. Default: false.
credential_labelLabel for newly stored credentials.
Implementation Example
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
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
UNAUTHORIZEDInvalid API key.
MULTI_STATUSUpstream OK but secondary sync had non-fatal errors.
BAD_REQUESTNo credentials available or missing required fields.
CONFLICTNumber already exists in system — delete it first.
UNPROCESSABLE_ENTITYNumber not found on provider account or assignment failed.
BAD_GATEWAYUpstream failure (Provider unreachable).
https://api.vanira.io/phone-numbers/linkRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
phone_numberREQUIREDThe phone number to update.
agent_idREQUIREDID of the new agent to handle all call traffic.
Implementation Example
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
1{2 "success": true,3 "phone_number": "+918071387205",4 "agent_id": "5396166a-f107-4918-b108-ff97b5987178"5}HTTP Errors
PHONE_NUMBER_NOT_FOUNDPhone number not found.
AGENT_NOT_FOUNDAgent not found.
https://api.vanira.io/phone-numbers/:phone_number/active+ as %2B.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
phone_numberREQUIREDE.164 number (encode + as %2B).
Body Parameters
is_activeREQUIREDtrue to activate, false to deactivate.
Implementation Example
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
1{2 "phone_number": "+918071387205",3 "is_active": true4}HTTP Errors
PHONE_NUMBER_NOT_FOUNDPhone number not found.
https://api.vanira.io/phone-numbers/:numberRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
numberREQUIREDThe phone number to remove (E.164 format).
Implementation Example
1curl -X DELETE 'https://api.vanira.io/phone-numbers/%2B918071387205' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1{2 "phone_number": "+918071387205",3 "deleted": true,4 "unassigned": true5}HTTP Errors
UNAUTHORIZEDInvalid API key.
PHONE_NUMBER_NOT_FOUNDPhone number not found in system.
BAD_GATEWAYVoBiz unassign failed.
https://api.vanira.io/phone-numbers/vobiz/credentialsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/phone-numbers/vobiz/credentials'Expected Response — 200 OK
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
UNAUTHORIZEDMissing or invalid API key.
https://api.vanira.io/assistantRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/assistant'Expected Response — 200 OK
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
idREQUIREDAgent UUID.
nameREQUIREDDisplay name.
activeREQUIREDWhether the agent is active.
languageREQUIREDLanguage code e.g. en-US.
model{ provider, model } — LLM config. See GET /discovery/models.
voice{ provider, name } — TTS voice config. See GET /discovery/voices.
transcription{ provider, model } — STT config.
ambient_noise_typeAmbient bed: none | quiet_office | call_center | traffic.
ambient_noise_volumeAmbient mix level in [0, 1].
enable_lid_detectionWhether LID is enabled.
lid_allowed_languagesAllowed languages for pivoting.
client_idREQUIREDOwner client ID.
HTTP Errors
UNAUTHORIZEDNo valid API key or JWT provided.
DATABASE_ERRORInternal database error.
https://api.vanira.io/assistant/:id- *Ownership enforced** — returns 404 if the agent belongs to a different client.
Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the agent.
Implementation Example
1curl -X GET 'https://api.vanira.io/assistant/caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5'Expected Response — 200 OK
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
idREQUIREDAgent UUID.
nameREQUIREDDisplay name.
activeREQUIREDActive status.
model{ provider, model } — LLM. Use GET /discovery/models for valid values.
voice{ provider, name } — TTS voice. Use GET /discovery/voices for valid values.
transcription{ provider, model } — STT transcription.
ambient_noise_typeAmbient bed: none | quiet_office | call_center | traffic. Default traffic.
ambient_noise_volumeAmbient mix level in [0, 1]. Default 0.35.
agent_promptLLM system prompt.
welcome_messageFirst message spoken by the agent.
temperatureLLM temperature (0–2).
speedTTS speech speed multiplier.
enable_lid_detectionWhether LID is enabled.
lid_allowed_languagesAllowed languages for pivoting.
data_collectionCall outcome and scoring configuration.
HTTP Errors
UNAUTHORIZEDNo valid API key or JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
VALIDATION_ERRORInvalid UUID format for id.
https://api.vanira.io/assistantRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
nameREQUIREDDisplay name for the agent.
welcome_messageREQUIREDFirst message the agent speaks.
agent_promptREQUIREDLLM system prompt that defines the agent personality.
languageLanguage code. e.g. en-US, hi-IN.
modelLLM config. If omitted, defaults to AZURE / gpt-4.1-mini. See GET /discovery/models for structure.
voiceTTS voice config. If omitted, defaults to ELEVENLABS / Riya Rao. See GET /discovery/voices for structure.
transcriptionSTT transcription config. See GET /discovery/transcription for structure.
stt_modeSarvam STT output mode: translit | transcribe | codemix. Default: translit.
ambient_noise_typeBackground ambient bed under TTS. Default: traffic. Use none to disable. See GET /discovery/ambient-noise-types.
ambient_noise_volumeAmbient mix level in [0, 1]. Default: 0.35. Ignored when type is none.
data_collectionPost-call extraction config.
dutyAgent role: support | sales | hr etc.
enable_lid_detectionEnable LID system.
lid_allowed_languagesAllowed ISO 639-1 codes.
activeStart active.
Implementation Example
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
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
UNAUTHORIZEDNo valid API key or JWT.
VALIDATION_ERRORmodel/voice/transcription provider+name not found in active records. Check /discovery/models and /discovery/voices.
PERSISTENCE_ERRORFailed to persist the new agent.
https://api.vanira.io/assistant/:idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the agent to update.
Body Parameters
nameNew display name.
agent_promptUpdated system prompt.
welcome_messageUpdated opening message.
languageLanguage code.
modelUpdate LLM. { provider, model }. See GET /discovery/models.
voiceUpdate TTS voice. { provider, name }. See GET /discovery/voices.
transcriptionUpdate STT config. { provider, model }.
stt_modeSarvam STT output mode: translit | transcribe | codemix.
ambient_noise_typeAmbient bed: none | quiet_office | call_center | traffic.
ambient_noise_volumeAmbient mix level in [0, 1]. Use 0 when type is none.
temperatureLLM temperature (0–2).
speedTTS speed multiplier (0.25–4).
enable_lid_detectionToggle LID system.
lid_allowed_languagesUpdate allowed languages.
activeActivate or deactivate.
Implementation Example
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
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
UNAUTHORIZEDNo valid API key or JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
VALIDATION_ERRORInvalid model/voice/transcription config. Check /discovery/models and /discovery/voices for valid values.
https://api.vanira.io/assistant/:idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the agent to delete.
Implementation Example
1curl -X DELETE 'https://api.vanira.io/assistant/caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1{2 "id": "caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5",3 "name": "Deleted Agent"4}HTTP Errors
UNAUTHORIZEDNo valid API key or JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
VALIDATION_ERRORInvalid UUID format.
https://api.vanira.io/assistant/:id/widgetRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the agent.
Implementation Example
1curl -X GET 'https://api.vanira.io/assistant/caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5/widget'Expected Response — 200 OK
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
AGENT_NOT_FOUNDNo agent with this UUID.
https://api.vanira.io/assistant/widget/:widget_idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
widget_idREQUIREDWidget UUID (from Get Agent Widget response).
Body Parameters
modevoice_only | chat_only | chat_voice | avatar_only | chat_avatar.
primary_colorPrimary hex color. e.g. #6366f1.
secondary_colorSecondary hex color.
iconWidget icon identifier.
Implementation Example
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
1{2 "id": "widget-uuid",3 "mode": "chat_voice",4 "primary_color": "#ff0000",5 "updated_at": "2026-04-27T12:05:00Z"6}HTTP Errors
WIDGET_NOT_FOUNDWidget not found.
VALIDATION_ERRORInvalid field value.
https://api.vanira.io/assistant/:id/data-collectionRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the agent.
Implementation Example
1curl -X GET 'https://api.vanira.io/assistant/caaa5b2a-5fd9-4974-a59e-1c9c01c4c6f5/data-collection'Expected Response — 200 OK
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
AGENT_NOT_FOUNDAgent not found.
https://api.vanira.io/assistant/:id/data-collectionRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the agent.
Body Parameters
keyREQUIREDUnique key for this field in extraction results.
promptREQUIREDInstructions for the AI to extract this value.
data_typestring | boolean | number | enum. Default: string.
enum_valuesList of valid values if data_type is enum.
store_to_prospectWhether to store this value in the main prospect record.
prospect_column_nameThe specific column name in the prospect table to map to.
store_to_prospect_dataWhether to store in the custom prospect_data table (key-value storage).
prospect_data_keyThe key to use when storing in prospect_data.
store_directly_to_prospectFlag for direct storage logic.
is_activeWhether to enable this extraction parameter.
Implementation Example
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
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
BAD_REQUESTInvalid configuration.
AGENT_NOT_FOUNDAgent not found.
https://api.vanira.io/assistant/data-collection/:collection_idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
collection_idREQUIREDUUID of the collection parameter.
Body Parameters
promptUpdated extraction prompt.
data_typeUpdate the expected data type.
enum_valuesUpdate allowed enum values.
store_to_prospectUpdate main record storage setting.
is_activeEnable/disable this parameter.
Implementation Example
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
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
DATA_COLLECTION_NOT_FOUNDParameter not found.
https://api.vanira.io/assistant/data-collection/:collection_idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
collection_idREQUIREDUUID of the collection parameter.
Implementation Example
1curl -X DELETE 'https://api.vanira.io/assistant/data-collection/<collection_id>' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1{2 "success": true,3 "id": "766c8b9d-5a4e-4f3d-9c8b-7d6e5f4a3b2c"4}HTTP Errors
DATA_COLLECTION_NOT_FOUNDParameter not found.
https://api.vanira.io/assistant/:id/media-handlersRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the agent.
Implementation Example
1curl -X GET 'https://api.vanira.io/assistant/<id>/media-handlers'Expected Response — 200 OK
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
AGENT_NOT_FOUNDAgent not found.
https://api.vanira.io/assistant/:id/media-handlersRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the agent.
Body Parameters
reasonREQUIREDThe routing category/tag sent by the client SDK (e.g. kyc_photo).
routeMust be "vision". Media is processed in-session over WebRTC — not forwarded to external URLs.
inject_asREQUIRED"system" or "user". How the parsed media result is injected into the prompt context.
interruptREQUIREDWhether to interrupt the agent mid-sentence when media is processed.
Implementation Example
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
1{2 "id": "new-handler-uuid",3 "reason": "kyc_photo",4 "route": "vision",5 "inject_as": "system",6 "interrupt": true7}HTTP Errors
BAD_REQUESTInvalid handler configuration.
AGENT_NOT_FOUNDAgent not found.
https://api.vanira.io/assistant/media-handlers/:idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the media handler.
Body Parameters
reasonUpdated routing category.
inject_asUpdated prompt injection mode.
interruptUpdate interrupt behavior.
Implementation Example
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
1{2 "id": "handler-uuid",3 "reason": "updated_kyc_photo",4 "updated_at": "2026-05-09T12:05:00Z"5}HTTP Errors
MEDIA_HANDLER_NOT_FOUNDHandler not found.
https://api.vanira.io/assistant/media-handlers/:idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the media handler.
Implementation Example
1curl -X DELETE 'https://api.vanira.io/assistant/media-handlers/<id>' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1{2 "success": true3}HTTP Errors
MEDIA_HANDLER_NOT_FOUNDHandler not found.
https://api.vanira.io/assistant/outbound-setupRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
purposeREQUIREDHigh-level purpose of the agent.
product_serviceREQUIREDWhat you sell / offer.
call_goalREQUIREDDesired call outcome.
target_audienceWho is being called.
post_call_stepsWhat happens after the call.
company_nameYour company name.
Implementation Example
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
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
VALIDATION_ERRORMissing required fields.
https://api.vanira.io/assistant/duplicate-agentRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
agent_idREQUIREDSource agent UUID.
nameOptional name for the clone.
activeWhether the clone starts active.
make_publicWhether the clone is public.
Implementation Example
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
1{2 "id": "new-agent-uuid-...",3 "name": "Sales Rep (copy)",4 "active": true5}HTTP Errors
FORBIDDENAPI key auth not allowed — use dashboard JWT.
AGENT_NOT_FOUNDSource agent not found.
https://api.vanira.io/assistant/:id/import:id is the public agent UUID.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDPublic agent UUID to import.
Body Parameters
nameOptional override name for the imported agent.
activeWhether imported agent starts active.
Implementation Example
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
1{2 "id": "imported-agent-uuid-...",3 "name": "Imported Agent",4 "active": true5}HTTP Errors
FORBIDDENAPI key auth not allowed — use dashboard JWT.
AGENT_NOT_FOUNDPublic agent not found.
https://api.vanira.io/assistant/:id/toggle-publicRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDAgent UUID (must be owned).
Query Parameters
is_publicREQUIREDtrue to publish, false to unpublish.
Implementation Example
1curl -X PATCH 'https://api.vanira.io/assistant/<id>/toggle-public' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1{2 "id": "caaa5b2a-...",3 "is_public": true4}HTTP Errors
AGENT_NOT_FOUNDAgent not found or not owned.
https://api.vanira.io/assistant/public/listRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Query Parameters
limitPage size.
offsetOffset.
Implementation Example
1curl -X GET 'https://api.vanira.io/assistant/public/list?limit=20&offset=0'Expected Response — 200 OK
1{2 "agents": [3 { "id": "public-agent-uuid-...", "name": "KYC Demo", "active": true }4 ]5}https://api.vanira.io/assistant/public/:idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDPublic agent UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/assistant/public/<id>'Expected Response — 200 OK
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
AGENT_NOT_FOUNDPublic agent not found.
https://api.vanira.io/assistant/:agent_id/partsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/assistant/<agent_id>/parts'Expected Response — 200 OK
1{2 "parts": [3 { "key": "closing", "value": "Thanks for your time!", "agent_id": "caaa5b2a-..." }4 ]5}HTTP Errors
AGENT_NOT_FOUNDAgent not found.
https://api.vanira.io/assistant/:agent_id/partsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
Body Parameters
keyREQUIREDPart key.
valueREQUIREDPart value.
Implementation Example
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
1{2 "key": "closing",3 "value": "Thanks for your time!",4 "agent_id": "caaa5b2a-..."5}HTTP Errors
AGENT_NOT_FOUNDAgent not found.
https://api.vanira.io/assistant/:agent_id/parts/:keyRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
keyREQUIREDPart key.
Implementation Example
1curl -X DELETE 'https://api.vanira.io/assistant/<agent_id>/parts/closing' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1{ "status": "success" }HTTP Errors
NOT_FOUNDAgent or part not found.
https://api.vanira.io/assistant/:agent_id/vision-llm-optionsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/assistant/<agent_id>/vision-llm-options'Expected Response — 200 OK
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
AGENT_NOT_FOUNDAgent not found.
https://api.vanira.io/assistant/:agent_id/vision-llm-optionsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
Body Parameters
enabledREQUIREDEnable live vision.
vision_providerVision model provider.
vision_modelVision model name.
live_vision_scopeScope for live vision.
fpsCapture FPS.
Implementation Example
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
1{2 "enabled": true,3 "vision_provider": "AZURE",4 "vision_model": "gpt-4.1-mini"5}HTTP Errors
AGENT_NOT_FOUNDAgent not found.
VALIDATION_ERRORInvalid vision options.
https://api.vanira.io/calls/create- *Authentication**
X-API-Key header:sk_live_*— secret key (server-side). Can create bothwebandsipcalls.pk_live_*— publishable key (browser/widget). Can only createwebcalls. Use*to allow all origins, or set domains to restrict usage.
- *SIP vs Web**
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_numberis provided, it must be a provisioned number owned by the client. - Automated Fallback: If
sip_data.from_numberis 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).
prospect_id is optional — a new anonymous prospect is created if omitted.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
agent_idREQUIREDUUID of the voice agent that will handle the call.
typeREQUIRED"web" for an in-browser WebRTC session. "sip" for an outbound phone call. Note: pk_live_* keys can only create web calls.
sip_dataRequired when type is "sip". Nested object containing the call destination. See sip_data.to and sip_data.name below.
sip_data.toE.164 formatted destination phone number. Required when type is "sip". Example: +919182517283 (country code + number, no spaces or dashes).
sip_data.nameDisplay name of the person being called. Used for prospect creation and call logging. Defaults to "Unknown" if omitted.
sip_data.from_numberOptional. The provisioned phone number (E.164) to dial from. If omitted, Vanira uses its shared pool default.
prospect_idOptional. Link the call to an existing prospect record. If omitted for web calls, an anonymous prospect is created automatically.
welcome_messageOptional. First message spoken when the call connects. Stored on the call row; overrides the agent default when set.
Implementation Example
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
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_idREQUIREDUnique identifier for the created call record.
statusREQUIRED"in-progress" for web calls. "triggered" for SIP calls.
worker_urlWebRTC worker URL to connect to. Only returned for type="web". Pass this to the Vanira SDK.
HTTP Errors
UNAUTHORIZEDNo X-API-Key header provided.
INVALID_API_KEYAPI key is invalid, revoked, or the secret does not match.
INSUFFICIENT_CREDITSClient balance is below the overdraft floor (default -1000 credits), or Saathi soft overdraft floor exceeded.
INSUFFICIENT_SCOPEPublishable key (pk_live_*) attempted to create a SIP call.
AGENT_NOT_FOUNDNo agent exists with the provided agent_id.
PROSPECT_NOT_FOUNDThe provided prospect_id does not exist.
VALIDATION_ERRORInvalid E.164 format (7-15 digits) or missing required fields.
UPSTREAM_SERVICE_TIMEOUTSIP gateway is unreachable or returned an error.
DATABASE_ERRORUnexpected server error.
https://api.vanira.io/calls- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Publishable keys cannot access call history.- *Filtering**
Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Query Parameters
agent_idFilter calls by a specific agent UUID.
statusFilter by call status: triggered | in-progress | completed | failed.
limitNumber of results to return. Default 100, max 500.
offsetNumber of results to skip for pagination.
Implementation Example
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
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
callsREQUIREDArray of call objects.
totalREQUIREDTotal matching calls across all pages (use for pagination UI).
calls[].idREQUIREDCall UUID.
calls[].statusREQUIREDtriggered | in-progress | completed | failed.
calls[].directioninbound (web) or outbound (SIP).
calls[].typeweb_call or sip_call.
calls[].durationCall duration in seconds.
calls[].recording_urlURL to the call recording if available.
calls[].prospectLinked prospect name and phone.
calls[].agentAgent id and name.
calls[].call_dataStructured key/value output from the agent (sentiment, outcome, etc.).
HTTP Errors
UNAUTHORIZEDNo X-API-Key header provided.
INVALID_API_KEYAPI key is invalid or revoked.
INSUFFICIENT_SCOPEPublishable key (pk_live_*) cannot access call history.
DATABASE_ERRORUnexpected server error.
https://api.vanira.io/calls/:id- *Authentication**
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the call to retrieve. Returned by POST /calls/create as call_id.
Implementation Example
1curl -X GET 'https://api.vanira.io/calls/6fdc9111-2b35-4252-a85c-781c37470ac0'Expected Response — 200 OK
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
idREQUIREDCall UUID.
agent_idREQUIREDUUID of the agent that handled the call.
client_idREQUIREDUUID of the client who owns this call.
phone_fromCaller's phone number.
phone_toDialled phone number.
statusCall status: triggered | in-progress | completed | failed.
call_triggered_atISO 8601 timestamp when the call was initiated.
extra_detailsArbitrary metadata returned by the telephony provider (duration, recording_url, etc.).
provider_call_idProvider-side call identifier.
prospectLinked prospect with name, phone, and prospect_data key/value pairs.
agentAgent info including nested client name and base_prospect_group_id.
HTTP Errors
UNAUTHORIZEDNo X-API-Key header provided.
INVALID_API_KEYAPI key is invalid or revoked.
INSUFFICIENT_SCOPEPublishable key (pk_live_*) cannot access call details.
CALL_NOT_FOUNDCall not found, or the authenticated client does not own this call.
VALIDATION_ERRORid path parameter is not a valid UUID.
DATABASE_ERRORUnexpected server error.
https://api.vanira.io/calls/:id/media- *Authentication**
X-API-Key: sk_live_* or Bearer JWT with calls:read.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDCall UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/calls/6fdc9111-2b35-4252-a85c-781c37470ac0/media'Expected Response — 200 OK
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_idREQUIREDMedia row UUID.
blob_pathREQUIREDStorage path for the blob.
sourceCapture source (e.g. live_vision, upload).
media_urlSigned URL when available.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
CALL_NOT_FOUNDCall not found or not owned.
https://api.vanira.io/calls/:id/media-usage- *Authentication**
calls:read.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDCall UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/calls/<id>/media-usage'Expected Response — 200 OK
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
UNAUTHORIZEDMissing or invalid API key.
CALL_NOT_FOUNDCall not found or not owned.
https://api.vanira.io/calls/media-sas- *Authentication**
calls:read.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Query Parameters
blob_pathREQUIREDBlob path from call media.
Implementation Example
1curl -X GET 'https://api.vanira.io/calls/media-sas?blob_path=calls%2F...%2Fframe.jpg'Expected Response — 200 OK
1{2 "url": "https://storage.example.com/...?sv=..."3}Response Schema Details
urlREQUIREDTime-limited download URL.
HTTP Errors
BAD_REQUESTMissing blob_path.
UNAUTHORIZEDMissing or invalid API key.
NOT_FOUNDBlob path not found or not owned.
https://api.vanira.io/campaignsfrom_numbers or set use_vanira_managed to true; otherwise, creation will fail.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
nameREQUIREDThe name of the campaign
agent_idREQUIREDID of the voice agent to use
candidatesREQUIREDList of prospects including name and phone number
providerREQUIREDThe voice provider to use (e.g., vonage, twilio)
timezoneREQUIREDTimezone for the campaign scheduling
call_hours_startREQUIREDDaily start time for calls (HH:MM:SS)
call_hours_endREQUIREDDaily end time for calls (HH:MM:SS)
call_daysREQUIREDDays of the week to make calls
max_concurrent_callsREQUIREDMaximum number of simultaneous calls
call_timeout_secondsREQUIREDSeconds to wait before considering a call timed out
start_campaignREQUIREDWhether to start the campaign immediately after upload
from_numbersOptional list of E.164 phone numbers to use as Caller IDs. System will resolve and allocate them automatically.
use_vanira_managedOptional. If true, the campaign will also use Vanira internal managed numbers.
retry_failed_callsREQUIREDRetry calls that failed (e.g. error/network issue)
max_retries_failedREQUIREDMaximum number of retries for failed calls
retry_delay_failed_secondsREQUIREDSeconds to wait before retrying a failed call
retry_busy_callsREQUIREDRetry calls where the line was busy
max_retries_busyREQUIREDMaximum number of retries for busy calls
retry_delay_busy_secondsREQUIREDSeconds to wait before retrying a busy call
retry_no_answer_callsREQUIREDRetry calls where there was no answer
max_retries_no_answerREQUIREDMaximum number of retries for no-answer calls
retry_delay_no_answer_secondsREQUIREDSeconds to wait before retrying a no-answer call
Implementation Example
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
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
successREQUIREDAlways true on success.
campaign_idREQUIREDUUID of the created campaign.
total_prospectsREQUIREDNumber of prospects added.
messageREQUIREDHuman-readable status message.
startedREQUIREDTrue if campaign was auto-started.
HTTP Errors
validation_errorMore than 50 candidates provided.
bad_requestNo Caller IDs provided. You must either provide from_numbers or set use_vanira_managed to true.
BAD_REQUEST_FORMATMissing required fields (agent_id, name, candidates).
AGENT_NOT_FOUNDAgent not found or agent has no associated client.
INTERNAL_SERVER_ERRORFailed to create prospect group or insert prospects.
UPSTREAM_SERVICE_ERRORCampaign API or SIP gateway is unreachable.
https://api.vanira.io/campaigns/:id/startRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the campaign to start.
Implementation Example
1curl -X POST 'https://api.vanira.io/campaigns/1a817016-a3f5-41c1-995c-c74a5fb33720/start' \2 -H "Content-Type: application/json"Expected Response — 200 OK
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
successREQUIREDAlways true on success.
campaign_idREQUIREDUUID of the campaign.
statusNew campaign status returned by the Campaign API.
messageREQUIREDHuman-readable result.
extra_dataRaw upstream Campaign API response.
HTTP Errors
CAMPAIGN_NOT_FOUNDCampaign not found or not owned by the authenticated client.
BAD_REQUEST_FORMATCampaign ID is not a valid UUID.
gateway_errorCampaign API unreachable or returned an error.
https://api.vanira.io/campaigns/:id/pauseRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the campaign to pause.
Implementation Example
1curl -X POST 'https://api.vanira.io/campaigns/1a817016-a3f5-41c1-995c-c74a5fb33720/pause' \2 -H "Content-Type: application/json"Expected Response — 200 OK
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
successREQUIREDAlways true on success.
campaign_idREQUIREDUUID of the campaign.
statusNew status (paused).
messageREQUIREDHuman-readable result.
extra_dataRaw upstream Campaign API response.
HTTP Errors
CAMPAIGN_NOT_FOUNDCampaign not found or not owned by the authenticated client.
BAD_REQUEST_FORMATCampaign ID is not a valid UUID.
gateway_errorCampaign API unreachable or returned an error (e.g. already paused).
https://api.vanira.io/campaigns/:id/resumeRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the campaign to resume.
Implementation Example
1curl -X POST 'https://api.vanira.io/campaigns/1a817016-a3f5-41c1-995c-c74a5fb33720/resume' \2 -H "Content-Type: application/json"Expected Response — 200 OK
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
successREQUIREDAlways true on success.
campaign_idREQUIREDUUID of the campaign.
statusNew status (active).
messageREQUIREDHuman-readable result.
extra_dataRaw upstream Campaign API response.
HTTP Errors
CAMPAIGN_NOT_FOUNDCampaign not found or not owned by the authenticated client.
BAD_REQUEST_FORMATCampaign ID is not a valid UUID.
gateway_errorCampaign API unreachable or returned an error (e.g. not paused).
https://api.vanira.io/campaigns/:id/schedule-startRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the campaign to schedule.
Body Parameters
scheduled_start_timeREQUIREDISO 8601 datetime for the auto-start (must be in the future).
Implementation Example
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
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
successREQUIREDAlways true on success.
campaign_idREQUIREDUUID of the campaign.
scheduled_start_timeREQUIREDConfirmed scheduled start time.
statusCampaign status after scheduling.
messageREQUIREDHuman-readable result.
extra_dataRaw upstream Campaign API response.
HTTP Errors
CAMPAIGN_NOT_FOUNDCampaign not found or not owned by the authenticated client.
BAD_REQUEST_FORMATCampaign ID is not a valid UUID, or scheduled_start_time is blank/missing.
gateway_errorCampaign API unreachable or returned an error (e.g. time in the past).
https://api.vanira.io/campaignsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/campaigns'Expected Response — 200 OK
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
BAD_REQUEST_FORMATInvalid client_id format
https://api.vanira.io/campaigns/:idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the campaign to fetch.
Implementation Example
1curl -X GET 'https://api.vanira.io/campaigns/<id>'Expected Response — 200 OK
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
idREQUIREDUUID of the campaign.
nameREQUIREDCampaign name.
statusREQUIREDCurrent status (draft, active, paused, scheduled, completed).
allocated_didsList of phone numbers (Caller IDs) assigned to this campaign.
allocated_dids[].numberREQUIREDThe E.164 phone number.
total_prospectsTotal number of contacts in the campaign.
active_prospectsNumber of contacts currently being called.
HTTP Errors
CAMPAIGN_NOT_FOUNDCampaign not found
https://api.vanira.io/campaigns/:idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the campaign to update.
Body Parameters
nameNew name for the campaign
max_concurrent_callsMaximum concurrent calls allowed
allow_rescheduleWhether to allow rescheduling calls
max_reschedules_per_prospectMaximum reschedules allowed per prospect
Implementation Example
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
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
CAMPAIGN_NOT_FOUNDCampaign not found
BAD_REQUESTNo fields provided
VALIDATION_ERRORInvalid fields format
https://api.vanira.io/campaigns/imports202 with an import_id — poll status, then create a campaign from the import.- *Body** is
multipart/form-datawithfileandagent_id.
Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
agent_idREQUIREDAgent that will own the eventual campaign.
fileREQUIREDCSV or XLSX file (multipart form field named file).
Implementation Example
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
1{2 "import_id": "imp-uuid-...",3 "status": "queued",4 "message": "Import queued"5}HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
VALIDATION_ERRORMissing file or agent_id.
https://api.vanira.io/campaigns/imports/:import_idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
import_idREQUIREDImport job UUID from POST /campaigns/imports.
Implementation Example
1curl -X GET 'https://api.vanira.io/campaigns/imports/<import_id>'Expected Response — 200 OK
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
IMPORT_NOT_FOUNDImport job not found.
https://api.vanira.io/campaigns/imports/:import_id/campaignRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
import_idREQUIREDCompleted import job UUID.
Body Parameters
nameREQUIREDCampaign name.
providerREQUIREDVoice provider (e.g. vonage).
timezoneREQUIREDIANA timezone.
call_hours_startREQUIREDDaily start (HH:MM:SS).
call_hours_endREQUIREDDaily end (HH:MM:SS).
call_daysREQUIREDDays of week.
max_concurrent_callsREQUIREDMax simultaneous calls.
start_campaignStart immediately after create.
from_numbersCaller ID numbers (E.164).
use_vanira_managedAlso use Vanira managed DIDs.
Implementation Example
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
1{2 "success": true,3 "campaign_id": "camp-uuid-...",4 "total_prospects": 480,5 "message": "Campaign created",6 "started": false7}HTTP Errors
IMPORT_NOT_FOUNDImport not found or not ready.
VALIDATION_ERRORInvalid campaign settings.
https://api.vanira.io/campaigns/:campaign_id/add-prospectsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
campaign_idREQUIREDCampaign UUID.
Body Parameters
prospectsREQUIREDArray of { phone, name, extra_details? }.
Implementation Example
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
1{2 "success": true,3 "campaign_id": "camp-uuid-...",4 "status": "active",5 "message": "Prospects added"6}HTTP Errors
CAMPAIGN_NOT_FOUNDCampaign not found.
VALIDATION_ERRORInvalid prospect rows.
https://api.vanira.io/campaigns/:campaign_id/prospectsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
campaign_idREQUIREDCampaign UUID.
Query Parameters
limitPage size.
offsetOffset.
statusFilter by prospect status.
searchSearch name/phone.
is_successfulFilter by success flag.
Implementation Example
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
1{2 "prospects": [3 { "id": "p-uuid", "name": "John", "phone": "+919876543210", "status": "pending" }4 ],5 "total_count": 4806}HTTP Errors
CAMPAIGN_NOT_FOUNDCampaign not found.
https://api.vanira.io/whatsapp-campaigns- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
nameREQUIREDCampaign name.
inbox_idREQUIREDConnected WhatsApp inbox UUID.
message_templateREQUIREDMessage body template. Supports prospect placeholders.
candidatesREQUIREDProspects: name, phone, optional extra_details.
Implementation Example
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
1{2 "success": true,3 "campaign_id": "wa-camp-uuid-...",4 "total_prospects": 120,5 "message": "Campaign created"6}HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
INBOX_NOT_FOUNDInbox not found or not owned.
VALIDATION_ERRORInvalid candidates or missing fields.
https://api.vanira.io/whatsapp-campaigns- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/whatsapp-campaigns'Expected Response — 200 OK
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
UNAUTHORIZEDMissing or invalid API key.
https://api.vanira.io/whatsapp-campaigns/:campaign_id- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
campaign_idREQUIREDCampaign UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/whatsapp-campaigns/<campaign_id>'Expected Response — 200 OK
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
CAMPAIGN_NOT_FOUNDCampaign not found.
https://api.vanira.io/whatsapp-campaigns/:campaign_id/prospects- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
campaign_idREQUIREDCampaign UUID.
Query Parameters
limitPage size (1–100). Default 25.
offsetPagination offset. Default 0.
Implementation Example
1curl -X GET 'https://api.vanira.io/whatsapp-campaigns/<campaign_id>/prospects?limit=25&offset=0'Expected Response — 200 OK
1{2 "prospects": [3 { "id": "p-uuid", "name": "John", "phone": "+919876543210", "status": "pending" }4 ],5 "total_count": 1206}HTTP Errors
CAMPAIGN_NOT_FOUNDCampaign not found.
https://api.vanira.io/whatsapp-campaigns/:campaign_id/start- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
campaign_idREQUIREDCampaign UUID.
Implementation Example
1curl -X POST 'https://api.vanira.io/whatsapp-campaigns/<campaign_id>/start' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1{2 "success": true,3 "status": "active",4 "message": "Campaign started"5}HTTP Errors
CAMPAIGN_NOT_FOUNDCampaign not found.
BAD_REQUESTCampaign cannot be started from current status.
https://api.vanira.io/whatsapp-campaigns/:campaign_id/pause- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: campaigns:read / campaigns:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
campaign_idREQUIREDCampaign UUID.
Implementation Example
1curl -X POST 'https://api.vanira.io/whatsapp-campaigns/<campaign_id>/pause' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1{2 "success": true,3 "status": "paused",4 "message": "Campaign paused"5}HTTP Errors
CAMPAIGN_NOT_FOUNDCampaign not found.
https://api.vanira.io/inbox- *Authentication**
X-API-Key: sk_live_* or Bearer JWT. Scopes: messaging:read / messaging:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Query Parameters
typesComma-separated inbox types filter.
Implementation Example
1curl -X GET 'https://api.vanira.io/inbox?types=WHATSAPP_WEB%2CWHATSAPP_BUSINESS'Expected Response — 200 OK
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
idREQUIREDInbox UUID — use as inbox_id when sending.
inbox_typeREQUIREDInbox channel type.
inbox_nameDisplay name.
agent_idLinked agent if any.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
https://api.vanira.io/inbox/messages- *Authentication**
X-API-Key: sk_live_* or Bearer JWT. Scopes: messaging:read / messaging:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Query Parameters
inbox_idREQUIREDInbox UUID.
limitMax messages (default 50).
senderOptional filter by sender phone/id.
Implementation Example
1curl -X GET 'https://api.vanira.io/inbox/messages?inbox_id=%3Cinbox-uuid%3E&limit=50&sender=%3Csender%3E'Expected Response — 200 OK
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
BAD_REQUESTinbox_id missing.
UNAUTHORIZEDMissing or invalid API key.
INBOX_NOT_FOUNDInbox not found.
https://api.vanira.io/inbox/send- *Authentication**
X-API-Key: sk_live_* or Bearer JWT. Scopes: messaging:read / messaging:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
inbox_idREQUIREDUUID of the connected WhatsApp inbox.
toREQUIREDRecipient phone number in E.164 format.
messageREQUIREDMessage content to send.
conversation_idOptional existing conversation UUID.
Implementation Example
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
1{2 "success": true,3 "message_id": "<message-uuid>",4 "status": "sent"5}Response Schema Details
successREQUIREDtrue if the message was queued successfully.
message_idUnique identifier for the sent message.
statusMessage status: sent | queued | failed.
HTTP Errors
missing_fieldinbox_id, to, or message was not provided.
inbox_not_foundNo WhatsApp inbox exists with the provided inbox_id.
inbox_not_authenticatedThe inbox has not been authenticated (QR code not scanned).
whatsapp_unavailableWhatsApp service is unavailable or the number is unreachable.
https://api.vanira.io/leads/groups- *Authentication**
X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/leads/groups'Expected Response — 200 OK
1{2 "groups": [3 { "id": "group-uuid-...", "name": "Website inbound" }4 ]5}HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
https://api.vanira.io/leads/columns- *Authentication**
X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/leads/columns'Expected Response — 200 OK
1{2 "columns": [3 { "id": "col-uuid-...", "key": "company", "label": "Company" }4 ]5}HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
https://api.vanira.io/leads- *Authentication**
X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/leads'Expected Response — 200 OK
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
idREQUIREDUnique identifier for the lead.
client_idREQUIREDOwner organization ID.
nameFull name of the lead.
phone_numberPrimary phone number.
email_idPrimary email address.
lead_sourceSource of the lead (e.g., Website, Import).
statusCurrent status of the lead.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
DATABASE_ERRORDatabase connectivity issue.
https://api.vanira.io/leadsphone_number is required.- *Authentication**
X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
phone_numberREQUIREDPrimary phone (E.164 preferred).
nameLead name.
email_idPrimary email.
alternate_phone_numberSecondary phone.
alternate_email_idSecondary email.
lead_sourceSource label.
statusInitial status.
remarksFree-text notes.
Implementation Example
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
1{2 "id": "e30e70ab-7d43-4a11-b75c-3f2d2948cba4",3 "phone_number": "+919876543210",4 "name": "John Doe",5 "status": "New"6}HTTP Errors
VALIDATION_ERRORphone_number missing or invalid.
https://api.vanira.io/leads/:id- *Authentication**
X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the lead to retrieve.
Implementation Example
1curl -X GET 'https://api.vanira.io/leads/e30e70ab-7d43-4a11-b75c-3f2d2948cba4'Expected Response — 200 OK
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
idREQUIREDUnique identifier for the lead.
client_idREQUIREDOwner organization ID.
nameFull name of the lead.
phone_numberPrimary phone number.
email_idPrimary email address.
lead_sourceSource of the lead (e.g., Website, Import).
statusCurrent status of the lead.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
LEAD_NOT_FOUNDNo lead exists with the provided UUID.
VALIDATION_ERRORInvalid UUID format.
DATABASE_ERRORDatabase connectivity issue.
https://api.vanira.io/leads/:id- *Authentication**
X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDLead UUID.
Body Parameters
nameUpdated name.
phone_numberUpdated phone.
email_idUpdated email.
statusUpdated status.
remarksUpdated notes.
lead_sourceUpdated source.
Implementation Example
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
1{2 "id": "e30e70ab-7d43-4a11-b75c-3f2d2948cba4",3 "status": "Contacted",4 "updated_at": "2026-04-21T09:00:00Z"5}HTTP Errors
LEAD_NOT_FOUNDLead not found.
https://api.vanira.io/leads/:id/followup- *Authentication**
X-API-Key: sk_live_* or Bearer JWT. Scopes: leads:read / leads:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDLead UUID.
Body Parameters
date_timeREQUIREDISO 8601 follow-up datetime.
Implementation Example
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
1{2 "status": "success",3 "id": "followup-uuid-..."4}HTTP Errors
LEAD_NOT_FOUNDLead not found.
VALIDATION_ERRORInvalid date_time.
https://api.vanira.io/bookings- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: bookings:read / bookings:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/bookings'Expected Response — 200 OK
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
appointmentsREQUIREDAppointment objects, optionally with nested ticket.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
https://api.vanira.io/bookings/ticket/:ticket_id/status- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: bookings:read / bookings:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
ticket_idREQUIREDTicket UUID.
Body Parameters
statusREQUIREDNew ticket status.
Implementation Example
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
1{2 "id": "ticket-uuid-...",3 "status": "resolved",4 "priority": "medium"5}HTTP Errors
TICKET_NOT_FOUNDTicket not found.
VALIDATION_ERRORInvalid status.
https://api.vanira.io/bookings/ticket/:ticket_id/priority- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: bookings:read / bookings:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
ticket_idREQUIREDTicket UUID.
Body Parameters
priorityREQUIREDNew priority.
Implementation Example
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
1{2 "id": "ticket-uuid-...",3 "status": "open",4 "priority": "high"5}HTTP Errors
TICKET_NOT_FOUNDTicket not found.
VALIDATION_ERRORInvalid priority.
https://api.vanira.io/calendar/users- *Authentication**
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/calendar/users'Expected Response — 200 OK
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
UNAUTHORIZEDMissing or invalid API key.
https://api.vanira.io/calendar/users- *Authentication**
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
nameREQUIREDDisplay name.
user_typeREQUIREDUser type (e.g. human).
timezoneIANA timezone.
providerCalendar provider hint (e.g. google).
configured_availabilityWhether availability has been configured.
Implementation Example
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
1{2 "id": "u1a2b3c4-...",3 "name": "Priya Sharma",4 "user_type": "human",5 "timezone": "Asia/Kolkata"6}HTTP Errors
VALIDATION_ERRORInvalid timezone or missing required fields.
https://api.vanira.io/calendar/users/:user_id- *Authentication**
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
user_idREQUIREDCalendar user UUID.
Body Parameters
nameDisplay name.
email_idContact email.
timezoneIANA timezone.
integrator_account_idExternal integrator account ID.
configured_availabilityAvailability configured flag.
Implementation Example
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
1{2 "id": "u1a2b3c4-...",3 "name": "Priya Sharma",4 "timezone": "Asia/Kolkata"5}HTTP Errors
NOT_FOUNDCalendar user not found.
https://api.vanira.io/calendar/users/:user_id- *Authentication**
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
user_idREQUIREDCalendar user UUID.
Implementation Example
1curl -X DELETE 'https://api.vanira.io/calendar/users/<user_id>' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1{ "status": "success" }HTTP Errors
NOT_FOUNDCalendar user not found.
https://api.vanira.io/calendar/users/:user_id/availability- *Authentication**
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
user_idREQUIREDCalendar user UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/calendar/users/<user_id>/availability'Expected Response — 200 OK
1{2 "availability": [3 { "day": "Monday", "start": "09:00", "end": "17:00" }4 ]5}HTTP Errors
NOT_FOUNDCalendar user not found.
https://api.vanira.io/calendar/users/:user_id/availability- *Authentication**
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
user_idREQUIREDCalendar user UUID.
Body Parameters
availabilityREQUIREDArray of availability slot objects.
Implementation Example
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
1{ "status": "success", "affected_rows": 5 }HTTP Errors
NOT_FOUNDCalendar user not found.
VALIDATION_ERRORInvalid availability payload.
https://api.vanira.io/calendar/integrations- *Authentication**
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
calendar_user_idREQUIREDCalendar user UUID.
connection_idREQUIREDProvider connection ID.
providerREQUIREDProvider name (e.g. google).
integrator_user_idREQUIREDIntegrator-side user ID.
provider_metadataOptional provider metadata object.
Implementation Example
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
1{ "status": "success", "id": "int-uuid-..." }HTTP Errors
VALIDATION_ERRORMissing required fields.
https://api.vanira.io/calendar/users/:user_id/integrations/:provider/metadata- *Authentication**
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
user_idREQUIREDCalendar user UUID.
providerREQUIREDProvider key.
Body Parameters
metadataREQUIREDMetadata object to merge/store.
Implementation Example
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
1{ "status": "success", "affected_rows": 1 }HTTP Errors
NOT_FOUNDUser or integration not found.
https://api.vanira.io/calendar/agent/:agent_id- *Authentication**
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/calendar/agent/<agent_id>'Expected Response — 200 OK
1{2 "calendar_user_ids": ["u1a2b3c4-...", "u5d6e7f8-..."]3}HTTP Errors
AGENT_NOT_FOUNDAgent not found or not owned.
https://api.vanira.io/calendar/agent/:agent_id- *Authentication**
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
Body Parameters
calendar_user_idsREQUIREDArray of calendar user UUIDs.
Implementation Example
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
1{2 "calendar_user_ids": ["u1a2b3c4-..."]3}HTTP Errors
AGENT_NOT_FOUNDAgent not found or not owned.
VALIDATION_ERRORInvalid calendar_user_ids.
https://api.vanira.io/webhooks- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/webhooks'Expected Response — 200 OK
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
idREQUIREDWebhook UUID.
urlREQUIREDHTTPS delivery URL.
statusREQUIREDactive | inactive.
eventsREQUIREDSubscribed event types: NEW_LEAD | CALL_COMPLETED | CALL_ANALYSIS_COMPLETED | NEW_BOOKING | NEW_TICKET.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
INSUFFICIENT_SCOPEMissing webhooks:read scope.
https://api.vanira.io/webhooks- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
urlREQUIREDHTTPS URL that will receive POST deliveries.
eventsREQUIREDEvent types to subscribe to: NEW_LEAD | CALL_COMPLETED | CALL_ANALYSIS_COMPLETED | NEW_BOOKING | NEW_TICKET.
Implementation Example
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
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_secretREQUIREDHMAC signing secret. Shown only on create / regenerate.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
INSUFFICIENT_SCOPEMissing webhooks:write scope.
VALIDATION_ERRORURL must be HTTPS, or events invalid.
https://api.vanira.io/webhooks/:id- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDWebhook UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890'Expected Response — 200 OK
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
WEBHOOK_NOT_FOUNDWebhook not found or not owned by client.
https://api.vanira.io/webhooks/:id- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDWebhook UUID.
Body Parameters
statusactive | inactive.
eventsReplace the subscribed event list.
Implementation Example
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
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
WEBHOOK_NOT_FOUNDWebhook not found.
VALIDATION_ERRORInvalid status or events.
https://api.vanira.io/webhooks/:id- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDWebhook UUID.
Implementation Example
1curl -X DELETE 'https://api.vanira.io/webhooks/<id>' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1// 204 No ContentHTTP Errors
WEBHOOK_NOT_FOUNDWebhook not found.
https://api.vanira.io/webhooks/:id/regenerate-secret- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDWebhook UUID.
Implementation Example
1curl -X POST 'https://api.vanira.io/webhooks/<id>/regenerate-secret' \2 -H "Content-Type: application/json"Expected Response — 200 OK
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
WEBHOOK_NOT_FOUNDWebhook not found.
https://api.vanira.io/webhooks/:id/deliveries- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDWebhook UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/webhooks/<id>/deliveries'Expected Response — 200 OK
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_typeREQUIREDEvent that was delivered.
http_statusHTTP status from your endpoint.
successREQUIREDWhether the delivery succeeded.
duration_msRound-trip latency in milliseconds.
HTTP Errors
WEBHOOK_NOT_FOUNDWebhook not found.
https://api.vanira.io/webhooks/:id/ping- *Authentication**
X-API-Key: sk_live_* or Authorization: Bearer <token>. Scopes: webhooks:read / webhooks:write.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDWebhook UUID.
Query Parameters
event_typeOptional event type; defaults to first subscribed event.
Implementation Example
1curl -X POST 'https://api.vanira.io/webhooks/<id>/ping' \2 -H "Content-Type: application/json"Expected Response — 200 OK
1{2 "success": true,3 "event_type": "CALL_COMPLETED",4 "payload": { "event": "CALL_COMPLETED", "data": {} }5}HTTP Errors
WEBHOOK_NOT_FOUNDWebhook not found.
BAD_REQUESTevent_type not in webhook subscriptions.
Overview
- *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):
| Page | What it covers |
|---|---|
| Preset Tools | Built-in UI — form, calendar, navigate, DOM actions, screen overlay, … |
| Custom Client Tools | Your own handler — popups, API calls, custom logic |
- *Server tools — HTTP webhooks; see Create Tool** for
POST /toolspayload shape.
{{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
onCustomToolhandler needed.
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)
POST /tools — copy a body below (set client_fields.preset_id)2.
POST /assistant/{agent_id}/tools — attach with { "tool_id": "<uuid>" }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 ID | UI | Mode |
|---|---|---|
vanira_form | Data Collection Form | blocking |
vanira_phone | Mobile number | blocking |
vanira_mcq | Multiple Choice Question | blocking |
vanira_calendar | Date & Time Picker | blocking |
vanira_upload | File Upload | blocking |
vanira_camera | Camera Capture | fire_and_forget |
vanira_navigate | Navigate to Route — requires vanira:navigate listener on SPAs | blocking |
vanira_highlight_element | Highlight Element | blocking |
vanira_click_element | Click Element | blocking |
vanira_select_option | Select Dropdown Option | blocking |
vanira_set_date | Set Date Field | blocking |
vanira_type_text | DOM Typing Simulation | blocking |
vanira_write_latex_text | Chalkboard LaTeX Writer | blocking |
vanira_erase_text | Whiteboard / DOM Erase | blocking |
vanira_live_vision | Live Vision (Streaming Camera) | fire_and_forget |
vanira_close_live_camera | Stop Live Camera | blocking |
vanira_live_screen | Live Screen Share | fire_and_forget |
vanira_close_live_screen | Stop Live Screen Share | blocking |
vanira_clip_region | Page Region Clip | blocking |
vanira_screen_vision | Screen Vision | blocking |
vanira_point_at | Point At Screen | blocking |
vanira_draw_on_screen | Draw On Screen | blocking |
vanira_clear_screen_draw | Clear Screen Drawings | blocking |
vanira_highlight_on_screen | Highlight On Screen | blocking |
vanira_kyc_document_capture | KYC Document Capture | blocking |
vanira_kyc_selfie_capture | KYC Selfie Capture | blocking |
vanira_kyc_signature_capture | KYC Signature Capture | blocking |
- *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
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
vanira_navigate, the SDK dispatches a browser event instead of forcing a full page reload:| Target | SDK 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:navigatelistener** that routes with your framework and setsevent.detail.handled = true. Without it, same-origin navigation fails withstatus: cancelledand 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 (
useRouterin Next.js App Router). The widget custom element stays ondocument.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
fields (comma-separated labels) per call; optional title fallback in client_fields.- *Create tool body** (
POST /tools):
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
mobile_number, country_code, national_number).- *Create tool body** (
POST /tools):
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 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):
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
slots_api_url for live availability. blocking.- *Create tool body** (
POST /tools):
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
client_tool_result includes media_id when upload succeeds.- *Create tool body** (
POST /tools):
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
- *Create tool body** (
POST /tools):
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
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):
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}vanira_navigate, the SDK dispatches a browser event instead of forcing a full page reload:| Target | SDK 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:navigatelistener** that routes with your framework and setsevent.detail.handled = true. Without it, same-origin navigation fails withstatus: cancelledand 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 (
useRouterin Next.js App Router). The widget custom element stays ondocument.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):
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
- *Create tool body** (
POST /tools):
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
id (no #). route required — SDK navigates first when the user is on another page. blocking.- *Create tool body** (
POST /tools):
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> or custom dropdown by HTML id. route required — SDK navigates first. blocking.- *Create tool body** (
POST /tools):
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
id. Agent passes ISO date; SDK formats per text_format. route required. blocking.- *Create tool body** (
POST /tools):
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
typing_mode: append (boards) or replace (search bars). route only when CSS selector / element id is set. blocking.- *Create tool body** (
POST /tools):
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
latex_text can be static in client_fields or overridden per call. blocking.- *Create tool body** (
POST /tools):
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
route only when element id is set. blocking — call sendToolResult() when done.- *Create tool body** (
POST /tools):
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)
- *Create tool body** (
POST /tools):
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
- *Create tool body** (
POST /tools):
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
- *Create tool body** (
POST /tools):
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
- *Create tool body** (
POST /tools):
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
- *Create tool body** (
POST /tools):
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
- *Create tool body** (
POST /tools):
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
- *Create tool body** (
POST /tools):
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
- *Create tool body** (
POST /tools):
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
- *Create tool body** (
POST /tools):
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
- *Create tool body** (
POST /tools):
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
reason. Optional title / description (instructions) on the popup.- *Create tool body** (
POST /tools):
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
reason. Optional title / description (instructions) on the popup.- *Create tool body** (
POST /tools):
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
reason. Optional title / description (instructions) on the popup.- *Create tool body** (
POST /tools):
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
Step 1 — Agent parameters
customer_name(string, required) — "Person's name from the conversation"
Step 2 — Frontend payload
{{param_name}}— substituted with the AI-extracted agent parameter- a static string — always the same value
client_fields in the API and resolves to arguments at runtime.| Payload key | Value |
|---|---|
name | {{customer_name}} |
source | website |
{ "name": "Teja", "source": "website" }Step 3 — Execution mode
| Dashboard label | API value | When to use |
|---|---|---|
| Blocking | blocking | AI should wait (form submit, user confirmation) — call sendToolResult() |
| Async | fire_and_forget | Fire-and-forget UI (popup, toast, map pan) |
Step 4 — Wire in the SDK
VaniraCallBox, handle custom tools in onCustomTool (presets are automatic):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}}POST /tools payload.end_callThe 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.
In the API response, it appears with the following properties:
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
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();https://api.vanira.io/toolsIn voice calls, calling this tool triggers an immediate SIP Transfer to your configured fallback number or the
to_number parameter.Creation Payload
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X POST 'https://api.vanira.io/tools' \2 -H "Content-Type: application/json"https://api.vanira.io/toolsTransferring a user from a "Lead Qualification" agent to a "Support" agent once their identity is verified.
Creation Payload
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-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X POST 'https://api.vanira.io/tools' \2 -H "Content-Type: application/json"https://api.vanira.io/toolsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Implementation Example
1curl -X GET 'https://api.vanira.io/tools'Expected Response — 200 OK
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
idREQUIREDTool UUID.
nameREQUIREDTool name — used as the function name the AI calls.
descriptionREQUIREDWhat the tool does — AI uses this to decide when to call it.
typeREQUIRED"server" | "client".
execution_modeREQUIRED"blocking" | "fire_and_forget". For client tools only.
channelsREQUIREDWhich channels this tool is active on.
parametersREQUIREDParameter schema — what the AI extracts from the conversation.
server{ url, method } — present for server tools only.
request{ body, headers, query } with {{param}} notation.
client_fieldsFields sent to the client-side action with {{param}} notation.
HTTP Errors
UNAUTHORIZEDNo valid API key.
https://api.vanira.io/tools/:idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDThe unique ID of the tool.
Implementation Example
1curl -X GET 'https://api.vanira.io/tools/e2705199-b431-4091-ad7c-ca1110b8e025'Expected Response — 200 OK
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
UNAUTHORIZEDNo valid API key.
TOOL_NOT_FOUNDTool not found or not owned by the authenticated client.
https://api.vanira.io/toolsPOST /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:
parameters — agent parameters (what the AI collects from chat)- *Client tools — two kinds:**
- Preset — see Preset Tools for every
preset_idand copy-pastePOST /toolsbody - Custom — see Custom Client Tools for agent parameters + frontend payload mapping
client_fields is omitted for a custom client tool, each parameter auto-maps to the same key in arguments.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
nameREQUIREDTool name — becomes the function name the AI calls.
descriptionREQUIREDWhat the tool does. The AI reads this to decide when to call it.
ref_codeOptional reference code (slug). If omitted, one is generated from the name.
typeREQUIRED"server" — HTTP webhook. "client" — UI action in the browser.
execution_mode"blocking" = AI waits for result. "fire_and_forget" = AI continues. Default: blocking for server, fire_and_forget for client.
channelsvoice_web | voice_telephony | chat | whatsapp. Defaults to [voice_web, voice_telephony].
parametersWhat the AI extracts from the conversation. Each item: { name, type, description, required, enum? }.
serverRequired when type is "server". { url, method: POST|GET|PUT|DELETE }
requestHTTP fields. If omitted, parameters auto-map to body by name. Use {{param}} for dynamic values.
client_fieldsFrontend payload for client tools. Use {{param}} for agent values or static strings. Presets use preset_id and preset config keys.
Implementation Example
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
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
UNAUTHORIZEDNo valid API key.
VALIDATION_ERRORMissing required fields, or server.url not provided for type="server".
https://api.vanira.io/tools/:idrequest fields, the full body/headers/query object is replaced. Parameters are preserved from the existing tool unless explicitly re-sent.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the tool to update.
Body Parameters
nameNew tool name.
descriptionUpdated description.
ref_codeUpdated reference code (slug).
serverUpdated server config { url, method }.
requestUpdated request body/headers/query mapping. {{param}} notation supported.
client_fieldsUpdated client-side fields.
channelsUpdated channel list.
parametersUpdated parameters list. Replaces existing ones.
Implementation Example
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
UNAUTHORIZEDNo valid API key.
TOOL_NOT_FOUNDTool not found or not owned by the authenticated client.
https://api.vanira.io/tools/:idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDUUID of the tool to delete.
Implementation Example
1curl -X DELETE 'https://api.vanira.io/tools/e2705199-b431-4091-ad7c-ca1110b8e025' \2 -H "Content-Type: application/json"HTTP Errors
TOOL_NOT_FOUNDTool not found or not owned by the authenticated client.
https://api.vanira.io/assistant/:id/toolsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDAgent UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/assistant/28c591f1-f17c-4c46-82ac-4054a843007a/tools'Expected Response — 200 OK
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
idREQUIREDagent_actions join record ID — use this to detach the tool.
tool_idREQUIREDbase_actions ID — use this to reference the tool definition.
is_activeREQUIREDWhether the tool is active for this agent.
HTTP Errors
UNAUTHORIZEDNo valid API key.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
https://api.vanira.io/assistant/:id/toolsPOST /tools first.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDAgent UUID.
Body Parameters
tool_idREQUIREDUUID of the tool to attach (from GET /tools).
Implementation Example
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
1{2 "id": "7ccfd8ea-8c99-4022-82e3-7c68bdb8d02b",3 "is_active": true4}HTTP Errors
UNAUTHORIZEDNo valid API key.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
TOOL_NOT_FOUNDTool not found or not owned by the authenticated client.
https://api.vanira.io/assistant/:id/tools/:tool_idid from GET /assistant/{id}/tools (the agent_actions ID, not the tool_id).Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
idREQUIREDAgent UUID.
tool_idREQUIREDThe agent_actions.id from GET /assistant/{id}/tools — NOT the base tool ID.
Implementation Example
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
UNAUTHORIZEDNo valid API key.
AGENT_NOT_FOUNDAgent or attachment not found.
https://api.vanira.io/knowledge/crawl- *Rate limited** (heavy). Requires
knowledge:write.
Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Body Parameters
urlREQUIREDSite URL to crawl.
purposeREQUIREDWhat the agent should accomplish.
deploymentREQUIREDweb | app.
Implementation Example
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
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_idREQUIREDCrawl job identifier.
suggested_agent_nameSuggested agent display name.
agent_promptGenerated system prompt.
welcome_messageSuggested first message.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key.
VALIDATION_ERRORInvalid url / purpose / deployment.
UPSTREAM_SERVICE_ERRORCrawl provider failure.
https://api.vanira.io/knowledge/agents/:agent_id/status- *Ownership enforced** — agent must belong to the authenticated client. Proxies coreinfra
GET /knowledge/agents/{agent_id}/status.
Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/knowledge/agents/3a607fa1-5beb-46a6-beb3-c8118392980e/status'Expected Response — 200 OK
1{2 "agent_id": "3a607fa1-5beb-46a6-beb3-c8118392980e",3 "has_vectors": true,4 "faq_count": 15}Response Schema Details
agent_idREQUIREDAgent UUID.
has_vectorsREQUIREDWhether Qdrant has vectors for this agent.
faq_countREQUIREDNumber of FAQ rows.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key / JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
UPSTREAM_SERVICE_ERRORcoreinfra / Hasura / Cohere / Qdrant failure.
https://api.vanira.io/knowledge/agents/:agent_id/faqs- *Ownership enforced.** Proxies coreinfra list (embed/index side effects already applied at write time).
Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
Query Parameters
limitPage size (1–500). Default 100.
offsetPagination offset. Default 0.
qOptional search on question/answer.
Implementation Example
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
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_idREQUIREDAgent UUID.
faqsREQUIREDFAQ objects.
totalREQUIREDTotal matching FAQs.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key / JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
UPSTREAM_SERVICE_ERRORcoreinfra / Hasura / Cohere / Qdrant failure.
https://api.vanira.io/knowledge/agents/:agent_id/faqs/:faq_idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
faq_idREQUIREDFAQ UUID.
Implementation Example
1curl -X GET 'https://api.vanira.io/knowledge/agents/3a607fa1-5beb-46a6-beb3-c8118392980e/faqs/48071789-080a-4b9a-8442-fc55e1e68314'Expected Response — 200 OK
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
idREQUIREDFAQ UUID.
agent_idREQUIREDOwning agent UUID.
questionREQUIREDFAQ question text.
answerREQUIREDFAQ answer text.
qdrant_idVector store point ID (coreinfra / Qdrant).
document_idOptional linked document ID.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key / JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
UPSTREAM_SERVICE_ERRORcoreinfra / Hasura / Cohere / Qdrant failure.
FAQ_NOT_FOUNDFAQ does not exist for this agent.
https://api.vanira.io/knowledge/agents/:agent_id/faqsfaq_data, and updates agent.knowledge_base_vector_count.- *Ownership enforced.**
Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
Body Parameters
questionREQUIREDFAQ question.
answerREQUIREDFAQ answer.
Implementation Example
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
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
idREQUIREDFAQ UUID.
agent_idREQUIREDOwning agent UUID.
questionREQUIREDFAQ question text.
answerREQUIREDFAQ answer text.
qdrant_idVector store point ID (coreinfra / Qdrant).
document_idOptional linked document ID.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key / JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
UPSTREAM_SERVICE_ERRORcoreinfra / Hasura / Cohere / Qdrant failure.
VALIDATION_ERRORquestion or answer missing / invalid.
https://api.vanira.io/knowledge/agents/:agent_id/faqs/bulk- *Request body (canonical):**
1{ "items": [ { "question": "...", "answer": "..." } ] }question,answer.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
Body Parameters
itemsREQUIREDArray of { question, answer } (max 100). Canonical wrapper: { "items": [...] }.
Implementation Example
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
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_idREQUIREDAgent UUID.
createdREQUIREDCreated FAQ objects.
countREQUIREDNumber created.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key / JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
UPSTREAM_SERVICE_ERRORcoreinfra / Hasura / Cohere / Qdrant failure.
VALIDATION_ERRORitems empty, >100, or invalid entries.
https://api.vanira.io/knowledge/agents/:agent_id/faqs/:faq_idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
faq_idREQUIREDFAQ UUID.
Body Parameters
questionREQUIREDUpdated question.
answerREQUIREDUpdated answer.
Implementation Example
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
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
idREQUIREDFAQ UUID.
agent_idREQUIREDOwning agent UUID.
questionREQUIREDFAQ question text.
answerREQUIREDFAQ answer text.
qdrant_idVector store point ID (coreinfra / Qdrant).
document_idOptional linked document ID.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key / JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
UPSTREAM_SERVICE_ERRORcoreinfra / Hasura / Cohere / Qdrant failure.
FAQ_NOT_FOUNDFAQ does not exist for this agent.
https://api.vanira.io/knowledge/agents/:agent_id/faqs/:faq_idRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
faq_idREQUIREDFAQ UUID.
Implementation Example
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
UNAUTHORIZEDMissing or invalid API key / JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
UPSTREAM_SERVICE_ERRORcoreinfra / Hasura / Cohere / Qdrant failure.
FAQ_NOT_FOUNDFAQ does not exist for this agent.
https://api.vanira.io/knowledge/agents/:agent_id/faqsRequired Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Path Parameters
agent_idREQUIREDAgent UUID.
Implementation Example
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
1{2 "agent_id": "3a607fa1-5beb-46a6-beb3-c8118392980e",3 "deleted_count": 24}Response Schema Details
agent_idREQUIREDAgent UUID.
deleted_countREQUIREDNumber of FAQs deleted.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key / JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
UPSTREAM_SERVICE_ERRORcoreinfra / Hasura / Cohere / Qdrant failure.
https://api.vanira.io/knowledge/search/knowledgeSearch.Required Headers
X-API-KeyREQUIREDYour Sovereign API key. Securely authorizes all requests.
Content-TypeREQUIREDMust be application/json
Query Parameters
queryREQUIREDSearch text.
agent_idREQUIREDAgent UUID.
thresholdScore threshold. Default 0.
limitMax hits (1–50). Default 5.
Implementation Example
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
1{2 "results": "Question: which courses do you support Answer: we support finance to tech to life style courses"3}Response Schema Details
resultsREQUIREDJoined retrieval hits, or empty string.
HTTP Errors
UNAUTHORIZEDMissing or invalid API key / JWT.
AGENT_NOT_FOUNDAgent not found or not owned by the authenticated client.
UPSTREAM_SERVICE_ERRORcoreinfra / Hasura / Cohere / Qdrant failure.
VALIDATION_ERRORquery or agent_id missing.