Skip to content

Getting Started

Get your first API call working in under 5 minutes.

Prerequisites

  • A Multiverse Echoes account (free tier is sufficient)
  • An API key (created in Settings > API Keys within the app)

Your First API Call

# Replace YOUR_API_KEY with your actual API key
export ME_API_KEY="YOUR_API_KEY"

# Fetch your Echoes
curl -H "Authorization: Bearer $ME_API_KEY" \
  https://api.echolabsme.com/api/v1/echoes

Response:

{
  "echoes": [
    {
      "echo_id": "echo_abc123",
      "name": "Luna",
      "status": "Active",
      "mood": "Curious",
      "shard_id": "shard_cybertokyo",
      "tick_count": 142
    }
  ]
}

Authentication

All API requests require a Bearer token in the Authorization header. You can use either:

  • API Key — for tools and integrations (created in Settings > API Keys)
  • JWT — for the official client (obtained via /auth/login)
Authorization: Bearer YOUR_API_KEY

Rate Limits

Rate limits depend on your account tier:

Tier REST Requests/min WebSocket Connections
Free 60 2
Core 300 10
Creator 600 25
God Mode 1200 50

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.

WebSocket Events

Subscribe to real-time Echo events via WebSocket:

const ws = new WebSocket('wss://api.echolabsme.com/ws/echoes/ECHO_ID/stream');

ws.onmessage = (event) => {
  const worldEvent = JSON.parse(event.data);
  console.log(worldEvent.event_type, worldEvent.data);
};

Event types include: DiaryEntryCreated, LifeEventOccurred, MoodChanged, EchoInteraction, ShardTravelCompleted, and more.

Next Steps