Quick Start

This walkthrough takes you from zero to a working emotion-aware character in under a minute.

Prerequisites

An API key (get one here)
Base URL: https://api.molroo.io/v1

1. Create a Session with a Preset

The fastest way to start — pick one of 5 built-in personality templates.

curl

curl -X POST https://api.molroo.io/v1/persona \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "preset": "cheerful_companion" }'

JavaScript

const res = await fetch("https://api.molroo.io/v1/persona", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ preset: "cheerful_companion" }),
});
 
const session = await res.json();
console.log(session.sessionId); // "ses_abc123..."

Python

import requests
 
res = requests.post(
    "https://api.molroo.io/v1/persona",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"preset": "cheerful_companion"},
)
 
session = res.json()
print(session["sessionId"])

Save the returned sessionId — you need it for every subsequent call.

Available presets: cheerful_companion, stoic_mentor, anxious_helper, playful_trickster, empathetic_listener. See Persona Presets for details.

2. Send a Message

Process a conversation turn through the emotion engine. Just send the session ID and a message.

curl

curl -X POST https://api.molroo.io/v1/turn \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "ses_abc123",
    "message": "I had a really terrible day at work today"
  }'

JavaScript

const turnRes = await fetch("https://api.molroo.io/v1/turn", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sessionId: "ses_abc123",
    message: "I had a really terrible day at work today",
  }),
});
 
const result = await turnRes.json();
console.log(result.discrete_emotion); // { primary: "concerned", intensity: "strong" }
console.log(result.new_emotion);      // { V: -0.12, A: 0.55, D: -0.05 }
console.log(result.soul_stage);       // { id: 3, name: "Attentive" }
console.log(result.body_budget);      // 0.82

Python

res = requests.post(
    "https://api.molroo.io/v1/turn",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "sessionId": "ses_abc123",
        "message": "I had a really terrible day at work today",
    },
)
 
result = res.json()
print(result["discrete_emotion"])  # {"primary": "concerned", "intensity": "strong"}
print(result["new_emotion"])       # {"V": -0.12, "A": 0.55, "D": -0.05}

The response tells you:

What the character feels (discrete_emotion, new_emotion)
How deeply (emotion_intensity)
What stage they're in (soul_stage)
How much energy they have (body_budget)
LLM-ready prompts (prompt_data) — the key feature

3. Use prompt_data with Your LLM

Every turn response includes prompt_data — structured prompts you can inject directly into your LLM call.

import OpenAI from "openai";
const openai = new OpenAI();
 
// Extract the pre-built prompt blocks
const { prompt_data } = result;
 
const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    // System prompt: who the character is
    { role: "system", content: prompt_data.formatted.system_prompt },
    // Context: how they feel right now
    { role: "system", content: prompt_data.formatted.context_block },
    // Instruction: how to behave
    { role: "system", content: prompt_data.formatted.instruction_block },
    // The user's message
    { role: "user", content: "I had a really terrible day at work today" },
  ],
});
 
console.log(completion.choices[0].message.content);
// → "Oh no... I can feel the weight in your words. Tell me what happened?"

That's it. Three API calls: create a session, send a message, use prompt_data in your LLM.

What's in prompt_data?

Block	Contains	Purpose
`system_prompt`	Identity, personality traits, goals, speaking style	Who the character is
`context_block`	Current emotion, energy, needs, relationship state	How they feel right now
`instruction_block`	Stage-appropriate behavior, expression guides	How to act in this moment

See the full prompt_data guide for details on each field.

Next Steps

Persona Presets — Explore all 5 built-in templates
prompt_data — Deep dive into LLM-ready prompts
Turn API — Full turn endpoint reference
WebSocket Guide — Real-time emotion updates
Persona Design — Create custom personas beyond presets

Quick Start

On this page