Skip to content

Getting Started with the API

This tutorial walks you through making your first API calls to the Multiverse Echoes engine.

Prerequisites

  • A Multiverse Echoes account (sign up at echolabsme.com)
  • Node.js 20+ or any JavaScript runtime with Fetch API support
  • The TypeScript SDK: npm install @echolabs/multiverse-echoes

Step 1: Create a Client

import { createClient } from '@echolabs/multiverse-echoes';

const client = createClient({
  baseUrl: 'https://api.echolabsme.com',
});

Step 2: Authenticate

Option A: Email + Password

const session = await client.login({
  email: 'you@example.com',
  password: 'your-password',
});
console.log('Logged in! Token expires in', session.expires_in, 'seconds');

Option B: API Key

Generate an API key in Settings > API Keys, then:

const client = createClient({
  baseUrl: 'https://api.echolabsme.com',
  apiKey: 'me_live_abc123...',
});
// No login needed

Step 3: List Your Echoes

const echoes = await client.echoes.list();

for (const echo of echoes) {
  console.log(`${echo.name} — ${echo.current_mood} (Tick ${echo.current_tick})`);
}

Step 4: Create an Echo

const echo = await client.echoes.create({
  name: 'Luna',
  persona_text: 'A 28-year-old marine biologist fascinated by deep-sea creatures.',
  what_if_prompt: 'moved to Iceland instead of staying in California',
  consent_declaration: true,
});

console.log(`Echo created: ${echo.name} (${echo.echo_id})`);
console.log(`Birth hash: ${echo.birth_hash}`);

What-if prompts are immutable

Once created, the what_if_prompt cannot be changed. This is by design — each Echo's origin story is permanent.

Step 5: Read the Feed

const feed = await client.feeds.personal(echo.echo_id);

for (const item of feed) {
  console.log(`[${item.item_type}] ${item.title}`);
  console.log(`  ${item.body}`);
}

Step 6: Subscribe to Real-Time Events

import { subscribeToEcho } from '@echolabs/multiverse-echoes';

const ws = subscribeToEcho('wss://api.echolabsme.com', echo.echo_id, session.access_token, {
  onEvent(event) {
    console.log(`Event: ${event.payload.type}`);
  },
});

// Clean up when done
process.on('SIGINT', () => {
  ws.close();
  process.exit();
});

Error Handling

import { ApiRequestError } from '@echolabs/multiverse-echoes';

try {
  await client.echoes.create(invalidData);
} catch (err) {
  if (err instanceof ApiRequestError) {
    console.error(`API Error [${err.code}]: ${err.message}`);
  }
}

Next Steps