Appearance Endpoint

Get appearance


GET /api/agents/{slug}/appearance/

Returns the full appearance configuration for a character. The widget calls this on boot to load branding, theme, forms, and labels. You can also call it server-side to inspect or cache the configuration.

This endpoint is public (no auth required) but is gated by the character’s allowed_origins list — requests must come from a whitelisted origin.

Path parameters

Parameter	Description
`slug`	The character’s URL-friendly slug (e.g. `support-bot`).

Request


curl https://api.oshara.ai/api/agents/support-bot/appearance/ \
  -H "Origin: https://yoursite.com"

Response


{
  "name": "Support Bot",
  "subtitle": "Here to help 24/7",
  "logo_url": "https://cdn.yoursite.com/bot-avatar.png",
  "fab_label": "Chat with us",
  "fab_sublabel": "",
  "start_button_text": "Start Call",
  "powered_by_text": "Powered by Oshara",
  "powered_by_url": "https://oshara.ai",
 
  "theme": {
    "primary_color": "#6366F1",
    "accent_color": "#22D3EE",
    "background_color": "#FFFFFF",
    "text_color": "#0F172A",
    "user_bubble_color": "#6366F1",
    "user_bubble_text_color": "#FFFFFF",
    "agent_bubble_color": "#F1F5F9",
    "agent_bubble_text_color": "#0F172A"
  },
 
  "dimensions": {
    "fab_size": 64,
    "panel_width": 380,
    "panel_height": 620,
    "border_radius": 24
  },
 
  "layout": {
    "position": "bottom-right",
    "font_family": ""
  },
 
  "labels": {
    "idle": "Idle",
    "connecting": "Connecting…",
    "listening": "Listening",
    "speaking": "Speaking…",
    "muted": "Microphone muted",
    "call_ended": "Call ended",
    "transcript_placeholder": "Your conversation will appear here",
    "language_label": "Language"
  },
 
  "languages": [
    { "code": "en", "label": "English", "native_label": "English" }
  ],
  "default_language": "en",
  "max_call_seconds": 0,
  "terms_url": "",
  "terms_label": "Terms & Conditions",
  "consent_text": "By starting the call you agree to our",
  "show_audio_settings": true,
 
  "forms": [
    {
      "id": "book-demo",
      "title": "Book a demo",
      "submit_url": null,
      "fields": [ ... ]
    }
  ]
}

See Appearance & Theming for the full field reference.

Caching

The response is safe to cache. The widget fetches it fresh on every page load, but for server-side rendering you can cache it with a short TTL (e.g. 60 seconds) to reduce latency.