API reference

https://avatarx.net/api

curl -X POST https://avatarx.net/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"••••••••"}'

# {
#   "session_id": "…",
#   "token_type": "bearer",
#   "expires_at": "2026-10-21T09:12:00",
#   "user": { "id": "…", "email": "you@example.com", "is_superuser": false }
# }

curl https://avatarx.net/api/agents/ \
  -H 'Authorization: Bearer YOUR_SESSION_ID'

{ "detail": "Agent not found" }

{
  "name": "Support desk",
  "system_prompt": "You help visitors with billing and account questions.",
  "personality": "Friendly and Professional",
  "agent_role": "Customer support specialist",
  "language": "en",
  "voice_id": "db6b0ed5-d5d3-463d-ae85-518a07d3c2b4",
  "musetalk_avatar_id": "ava",
  "llm_provider": "openai",
  "llm_model": "gpt-4o",
  "creativity": 0.4,
  "knowledge_mode": "strict",
  "greeting": "Hi! How can I help today?",
  "conversation_starters": ["Where is my order?", "How do I cancel?"],
  "topics_to_avoid": ["competitor pricing"],
  "max_response_words": 80,
  "is_public": true
}

{ "messages": [{ "role": "user", "content": "do you ship to Spain?" }] }

# {
#   "reply": "Yes — standard delivery to Spain takes 3–5 days.",
#   "media": { "id": "…", "kind": "image", "title": "Shipping rates", "url": "/api/media/…/file" },
#   "used_knowledge": true
# }

{
  "text": "We ship worldwide. Returns accepted within 30 days.",
  "urls": ["https://example.com/faq"],
  "restrict_to_knowledge": true
}

# 202 { "kb_id": "…", "created": { "text": true, "urls": ["https://example.com/faq"] }, "errors": [] }

curl -X POST https://avatarx.net/api/agents/AGENT_ID/media \
  -H 'Authorization: Bearer YOUR_SESSION_ID' \
  -F 'file=@spring-flyer.png' \
  -F 'title=Spring flyer' \
  -F 'trigger_keywords=flyer,offers,discount' \
  -F 'show_by_default=false'

{
  "name": "check_order_status",
  "description": "Look up an order by its number. Call this whenever a caller asks where their order is.",
  "method": "POST",
  "url": "https://api.example.com/orders/status",
  "auth_type": "bearer",
  "auth_config": { "token": "•••" },
  "timeout_seconds": 10,
  "parameters": {
    "type": "object",
    "properties": { "order_number": { "type": "string" } },
    "required": ["order_number"]
  }
}

{
  "enable_lead_capture": true,
  "enable_appointments": true,
  "enable_human_handoff": true,
  "meet_link": "meet.google.com/abc-defg-hij",
  "appointment_config": {
    "timezone": "Europe/Madrid",
    "slot_minutes": 30,
    "buffer_minutes": 10,
    "min_notice_minutes": 60,
    "max_days_ahead": 14,
    "business_hours": {
      "mon": [["09:00", "13:00"], ["14:00", "17:00"]],
      "tue": [["09:00", "17:00"]],
      "sat": [], "sun": []
    }
  }
}

BASE=https://avatarx.net/api

# 1. sign in
SID=$(curl -s -X POST $BASE/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"••••••••"}' | jq -r .session_id)
AUTH="Authorization: Bearer $SID"

# 2. create the agent
AID=$(curl -s -X POST $BASE/agents/ -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{
        "name":"Support desk",
        "system_prompt":"You help visitors with billing and account questions.",
        "knowledge_mode":"strict",
        "greeting":"Hi! How can I help today?",
        "is_public":true
      }' | jq -r .id)

# 3. give it something to know
curl -s -X POST $BASE/knowledge/agents/$AID/bootstrap -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"text":"Refunds are issued within 30 days of purchase.","urls":[]}'

# 4. see what it would retrieve (indexing takes a moment)
curl -s -G $BASE/knowledge/agents/$AID/search -H "$AUTH" --data-urlencode 'q=refund window'

# 5. talk to it
curl -s -X POST $BASE/agents/$AID/chat -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"can I get a refund after 3 weeks?"}]}'