Skip to content

Getting Started

Get your first API call working in under 5 minutes.

Prerequisites

  • A Multiverse Echoes account (sign up at echolabsme.com)
  • Either email/password credentials, or a Multiverse Echoes session cookie from the app
  • curl or any HTTP client; the API mounts at the root of api.echolabsme.com (no /api/v1/ URL prefix)

Your First API Call

# Step 1: log in to obtain a JWT access token
curl -X POST https://api.echolabsme.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"YOUR_PASSWORD"}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

# Step 2: fetch your Echoes (response is a bare EchoResponse[] array — not paginated)
export ACCESS_TOKEN="<paste access_token here>"

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.echolabsme.com/echoes

Response:

[
  {
    "echo_id": "0192a1b3-2c4d-4e5f-9a0b-1c2d3e4f5a6b",
    "name": "Luna",
    "current_mood": "Curious",
    "current_shard_id": "0192a1b3-2c4d-4e5f-9a0b-1c2d3e4f5a6c",
    "current_tick": 142,
    "persona_text": "...",
    "what_if_prompt": "...",
    "birth_hash": "9b8a...",
    "status": "Active",
    "created_at": "2026-04-01T08:30:00Z"
  }
]

Authentication

JWT is the only authentication path the API surface accepts today. Pass Authorization: Bearer <jwt> on every authenticated request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Access tokens are short-lived (expires after expires_in seconds — typically 1 hour). When you receive 401 AUTH_REQUIRED for an expired token, refresh:

curl -X POST https://api.echolabsme.com/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"YOUR_REFRESH_TOKEN"}'

The response contains a new access_token AND a new refresh_token (rotation per RFC 6819 §5.2.2.3 — discard the old refresh token).

API keys are creatable via POST /account/me/api-keys for tier-gated key inventory (per ME-MIS-001 §3.1: Starter 1, Core 2, Creator 10, GodMode unlimited; Free 0). The live API does not currently accept API keys as bearer tokens.

Rate Limits

Authenticated requests are rate-limited based 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 the ErrorEnvelope body (error.retry_after_seconds) and a Retry-After header.

WebSocket Events

Subscribe to real-time Echo events via WebSocket. JWT is passed as a query parameter (?token=<jwt>) because browsers cannot set custom headers on the WebSocket handshake.

const ws = new WebSocket(
  `wss://api.echolabsme.com/ws/echoes/${ECHO_ID}/stream?token=${accessToken}`,
);

ws.addEventListener('message', (frame) => {
  const event = JSON.parse(frame.data);

  // First frame is the handshake
  if (event.type === 'ConnectionEstablished') {
    console.log(`Subscribed to ${event.echo_id}`);
    return;
  }

  // Subsequent frames are WsEchoEvent — top-level `type` discriminator (no payload wrapper)
  console.log(event.type, event);
});

Subscription is implicit from the URL path — there is no {action: "subscribe"} message. The server does not parse client-sent action frames. See WebSocket Events for the full frame catalogue.

Next Steps