API Reference

SmarterAvatar exposes several API endpoints for integration.

Endpoints Overview

Endpoint	Method	Purpose
/api/chat	POST	Send message, get response
/api/get-access-token	POST	Get avatar session token
/api/health	GET	Health check
/api/conversations/log	POST	Log conversation data

---

Chat Endpoint

Send a message and receive an AI response.

Request

POST /api/chat
Content-Type: application/json

{
  "message": "What products do you offer?",
  "sessionId": "optional-session-id",
  "history": []
}

Response

{
  "response": "We offer a range of products including...",
  "sources": [
    {
      "title": "Product Catalog",
      "url": "https://example.com/catalog.pdf"
    }
  ],
  "sessionId": "generated-session-id"
}

Parameters

Field	Type	Required	Description
message	string	Yes	User's message
sessionId	string	No	Existing session ID
history	array	No	Previous messages

---

Avatar Token Endpoint

Get a token for avatar streaming.

Request

POST /api/get-access-token
Content-Type: application/json

{
  "avatarId": "Pedro_Blue_Shirt_public",
  "voiceId": "voice-id"
}

Response

{
  "token": "eyJ...",
  "sessionId": "session-123",
  "expiresAt": "2024-01-01T12:00:00Z"
}

Security

This endpoint should be called server-side. The token is short-lived and scoped to a single session.

---

Health Check

Verify the service is running.

Request

GET /api/health

Response

{
  "status": "ok",
  "timestamp": "2024-01-01T12:00:00Z",
  "providers": {
    "llm": "connected",
    "stt": "connected",
    "avatar": "connected"
  }
}

---

Conversation Logging

Log conversation data for analytics.

Request

POST /api/conversations/log
Content-Type: application/json

{
  "sessionId": "session-123",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    },
    {
      "role": "assistant",
      "content": "Hi there!"
    }
  ],
  "metadata": {
    "duration": 180,
    "source": "web"
  }
}

Response

{
  "success": true,
  "conversationId": "conv-456"
}

---

Error Handling

All endpoints return consistent error format:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: message"
  }
}

Error Codes

Code	HTTP Status	Description
INVALID_REQUEST	400	Malformed request
UNAUTHORIZED	401	Invalid/missing auth
RATE_LIMITED	429	Too many requests
PROVIDER_ERROR	502	Upstream provider failed
INTERNAL_ERROR	500	Server error

---

Hybrid Integration

For hybrid architectures, replace the /api/chat endpoint with your backend:

Your Backend Requirements

Your API should accept:

POST /your-api/chat
Content-Type: application/json

{
  "message": "User question",
  "sessionId": "session-id",
  "context": {}
}

And return:

{
  "response": "AI response text",
  "sources": []
}

Configure SmarterAvatar

Point the frontend to your backend:

NEXT_PUBLIC_CHAT_API_URL=https://your-backend.com/api/chat

The frontend will route chat requests to your backend while handling avatar/STT locally.

---

Rate Limits

Default rate limits (configurable):

Endpoint	Limit
/api/chat	60/min
/api/get-access-token	10/min
/api/health	100/min

For higher limits, contact us.