​
Overview

An AI Character is the complete definition of a voice agent: its persona (system prompt, name, avatar), voice settings, tool integrations, allowed embed origins, and widget appearance. Characters are identified by a stable slug. All character endpoints require JWT authentication.

​
List characters

GET /api/ai-characters/

curl https://api.oshara.ai/api/ai-characters/ \
  -H "Authorization: Bearer <token>"
Response: Array of character objects (see schema below).

​
Create a character

POST /api/ai-characters/

curl -X POST https://api.oshara.ai/api/ai-characters/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "support-bot",
    "name": "Support Bot",
    "system_prompt": "You are a helpful support agent for Acme Inc...",
    "greeting": "Hi! How can I help you today?",
    "language": "en",
    "allowed_origins": ["https://acme.com"],
    "llm_model": "gpt-4o-mini"
  }'

​
Retrieve a character

GET /api/ai-characters/{slug}/

curl https://api.oshara.ai/api/ai-characters/support-bot/ \
  -H "Authorization: Bearer <token>"

​
Update a character

PUT /api/ai-characters/{slug}/
PATCH /api/ai-characters/{slug}/
Use PUT to replace the full object, PATCH for partial updates. 
# Add a new allowed origin
curl -X PATCH https://api.oshara.ai/api/ai-characters/support-bot/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"allowed_origins": ["https://acme.com", "https://staging.acme.com"]}'

​
Delete a character

DELETE /api/ai-characters/{slug}/

curl -X DELETE https://api.oshara.ai/api/ai-characters/support-bot/ \
  -H "Authorization: Bearer <token>"

​
Character object schema

FieldTypeDescription
slugstringURL-friendly identifier (unique). Used in widget data-agent.
namestringDisplay name for the character.
character_typestringCategory tag (e.g. PODCAST_HOST, STORY_TELLER, SUPPORT_AGENT).
imagefile / URLAvatar image.
system_promptstringLLM system prompt — the agent’s instructions and persona.
greetingstringThe first utterance the agent speaks when the call starts.
voiceobjectVoice configuration (audio_file, voice_url).
languagestringDefault BCP-47 language code for STT/TTS (e.g. "en").
background_audiostringAmbient audio mixed into agent audio. Options: "", "office", "crowded room", "cafe", "nature".
allowed_originsstring[]URL prefixes allowed to embed this character. Empty list = blocked everywhere.
handoff_targets{slug: string}[]Characters this agent can hand off to mid-call.
widget_appearanceobjectAppearance overrides — see Appearance.
stt_modelstringSTT model override (e.g. "whisper-en-large").
tts_modelstringTTS model override (e.g. "chatterbox-en-v1").
llm_providerstringLLM provider (currently "openai").
llm_modelstringLLM model ID (e.g. "gpt-4o-mini", "gpt-4o").
llm_api_keystringOptional per-character LLM API key (encrypted at rest).
documentsarrayKnowledge base documents attached to this character.

​
Example: full character with tools and appearance

{
  "slug": "sales-agent",
  "name": "Sales Assistant",
  "system_prompt": "You are an enthusiastic sales assistant for Acme Inc. Help prospects understand our products and book demos.",
  "greeting": "Hi there! I'm the Acme sales assistant. How can I help you today?",
  "language": "en",
  "llm_model": "gpt-4o",
  "background_audio": "office",
  "allowed_origins": ["https://acme.com"],
  "handoff_targets": [{ "slug": "support-bot" }],
  "widget_appearance": {
    "name": "Acme Sales",
    "theme": { "primary_color": "#FF6B35" },
    "forms": [
      {
        "id": "book-demo",
        "title": "Book a demo",
        "submit_url": null,
        "fields": [
          { "name": "name",  "label": "Your name",  "type": "text",  "required": true },
          { "name": "email", "label": "Work email", "type": "email", "required": true }
        ]
      }
    ]
  }
}