​
When to use the API directly

Use API integration (instead of the drop-in widget) when you need to:
  • Start voice sessions from your own backend — inject user context, keep credentials server-side
  • Render forms in your own UI — your design system, your component library
  • Configure noise cancellation programmatically per character
  • Control forms dynamically by voice — agent opens, watches, and submits forms in real time
  • Pre-fill forms from your database before the call starts
  • Connect your APIs as tools the agent can call
  • Build a native mobile app or custom front-end

​
Pages in this section

PageWhat it covers
SessionsMint a LiveKit token from your backend, inject user metadata
Noise CancellationConfigure NC engines via the appearance API, set defaults, self-host models
Form HandlingDefine forms via API, receive submissions at your endpoint or fetch from managed storage
Voice Form ControlAgent opens, tracks, and submits forms over the LiveKit data channel — implement in your own UI
Form Pre-fillFour ways to fill form fields via API: defaults, session metadata, agent tool args, direct POST
Agent ToolsExpose your REST endpoints as callable tools the agent invokes mid-call
Session HistoryList past sessions for a character with usage totals, durations, and inline transcripts
Chat HistoryRetrieve a single session’s full transcript and recording

​
Authentication

All endpoints documented in this section use JWT bearer auth: 
Authorization: Bearer <access-token>
Get a token by logging in: 
curl -X POST https://api.oshara.ai/api/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yoursite.com", "password": "yourpassword"}'
Tokens last 10 days. See Authentication for refresh, signup, and Google OAuth. The single exception is POST /api/agents/agent-session/ — gated by Origin whitelisting instead of JWT so browsers can call it directly. If you proxy it through your backend (recommended), the Origin header from your server must still be on the character’s allowed_origins list.

​
Base URL

https://api.oshara.ai

​
High-level flow

Your backend ──┐
               │  POST /api/agents/agent-session/      (mint token)
               ├─────────────────────────────────────► Oshara API
               │  PATCH /api/ai-characters/{slug}/     (configure forms, NC, tools)
               ├─────────────────────────────────────► Oshara API
               │  GET   /api/agents/{slug}/appearance/ (fetch form + theme schema)
               ▼─────────────────────────────────────► Oshara API
Your browser/app
               │  WebRTC + LiveKit data channel
               ├─────────────────────────────────────► LiveKit SFU
               │     • Audio in/out
               │     • Form open/close/state/submit messages
               │     • Tool calls / client events