Public API

Authentication

Send your key on every request (server-to-server recommended):

Authorization: Bearer mp_live_xxxxxxxx
# or
X-API-Key: mp_live_xxxxxxxx

Quickstart

# 1) Start a voice conversation
curl -X POST https://api.metapresence.co/public-api/v1/conversation/start \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_id": "AVT12AB3C",
    "persona_id": "PRS45DE6F",
    "conversation_type": "voice",
    "language": "en"
  }'

# Response includes: token, wsUrl, roomName, conversationId
# 2) Join with livekit-client (browser or Node)
# 3) End and meter usage
curl -X POST https://api.metapresence.co/public-api/v1/conversation/end \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "conversation_id": "<uuid>" }'

Video (live avatars)

For curated live video avatars, pass the avatar id and matching face id:

curl -X POST https://api.metapresence.co/public-api/v1/conversation/start \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_id": "rtf-kate",
    "conversation_type": "video",
    "rtf_face_id": "d2a5c7c6-fed9-4f55-bcb3-062f7cd20103",
    "language": "en"
  }'

Endpoints

• GET /public-api/v1/health — health (no auth)
• GET /public-api/v1/avatars — list avatars
• GET /public-api/v1/personas — list personas
• POST /public-api/v1/conversation/start — mint LiveKit token
• POST /public-api/v1/conversation/end — end + usage
• GET /public-api/v1/conversations/:id — status
• GET /public-api/v1/usage — plan usage

Limits and security

• Plan minute limits and optional per-key caps are enforced on start.
• Per-key rate limits apply per minute and per hour.
• Optional allowed_origins on the key block browser Origin misuse.
• Usage metering uses server elapsed time when the session ends.
• Keep API keys on your backend. Do not embed production keys in client apps.