Oshara Docs

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

Field	Type	Description
`slug`	string	URL-friendly identifier (unique). Used in widget `data-agent`.
`name`	string	Display name for the character.
`character_type`	string	Category tag (e.g. `PODCAST_HOST`, `STORY_TELLER`, `SUPPORT_AGENT`).
`image`	file / URL	Avatar image.
`system_prompt`	string	LLM system prompt — the agent’s instructions and persona.
`greeting`	string	The first utterance the agent speaks when the call starts.
`voice`	object	Voice configuration (`audio_file`, `voice_url`).
`language`	string	Default BCP-47 language code for STT/TTS (e.g. `"en"`).
`background_audio`	string	Ambient audio mixed into agent audio. Options: `""`, `"office"`, `"crowded room"`, `"cafe"`, `"nature"`.
`allowed_origins`	string[]	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_appearance`	object	Appearance overrides — see Appearance.
`stt_model`	string	STT model override (e.g. `"whisper-en-large"`).
`tts_model`	string	TTS model override (e.g. `"chatterbox-en-v1"`).
`llm_provider`	string	LLM provider (currently `"openai"`).
`llm_model`	string	LLM model ID (e.g. `"gpt-4o-mini"`, `"gpt-4o"`).
`llm_api_key`	string	Optional per-character LLM API key (encrypted at rest).
`documents`	array	Knowledge 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 }
        ]
      }
    ]
  }
}