molroomolroo
API Reference

Presets

List available persona presets for quick session creation.

Presets

Persona presets are pre-configured personality templates that let you quickly create sessions without defining every trait from scratch. Each preset includes a complete personality profile, goals, and emotion configuration tuned for a specific character archetype.


List Presets

GET /v1/presets

Returns an array of all available persona presets.

Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer YOUR_API_KEY

Response

Returns an array of preset objects:

FieldTypeDescription
idstringUnique preset identifier
namestringHuman-readable preset name
descriptionstringBrief description of the preset's character archetype
personalityobjectBig 5 personality traits { O, C, E, A, N }
goalsstring[]Default goals for this preset
emotion_configobjectPre-tuned emotion dynamics configuration

Available Presets

IDNameKey TraitsDescription
cheerful_companionCheerful CompanionE=0.8, A=0.7Warm, upbeat, and genuinely enthusiastic
stoic_mentorStoic MentorN=0.15, C=0.85Calm, wise, and emotionally grounded
anxious_helperAnxious HelperN=0.75, E=0.65Eager but worried, relatable vulnerability
playful_tricksterPlayful TricksterO=0.9, E=0.75Creative, spontaneous, and irreverent
empathetic_listenerEmpathetic ListenerA=0.9, E=0.45Deeply attuned, validation-focused

Examples

curl

curl https://api.molroo.io/v1/presets \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch("https://api.molroo.io/v1/presets", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
 
const presets = await response.json();
 
presets.forEach((preset) => {
  console.log(`${preset.id}: ${preset.name}`);
  console.log(`  ${preset.description}`);
  console.log(`  Personality:`, preset.personality);
});
 
// cheerful_companion: Cheerful Companion
//   Warm, upbeat, and genuinely enthusiastic companion
//   Personality: { O: 0.65, C: 0.5, E: 0.8, A: 0.7, N: 0.3 }
//
// stoic_mentor: Stoic Mentor
//   Calm, wise, and emotionally grounded advisor
//   Personality: { O: 0.6, C: 0.85, E: 0.35, A: 0.55, N: 0.15 }
// ...

Python

import requests
 
response = requests.get(
    "https://api.molroo.io/v1/presets",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
 
presets = response.json()
 
for preset in presets:
    print(f"{preset['id']}: {preset['name']}")
    print(f"  {preset['description']}")
    print(f"  Personality: {preset['personality']}")

Example Response

[
  {
    "id": "cheerful_companion",
    "name": "Cheerful Companion",
    "description": "Warm, upbeat, and genuinely enthusiastic companion who brightens every interaction",
    "personality": { "O": 0.65, "C": 0.5, "E": 0.8, "A": 0.7, "N": 0.3 },
    "goals": ["make the user feel welcome", "share positivity", "build rapport"],
    "emotion_config": {
      "baseline": { "V": 0.35, "A": 0.45, "D": 0.1 },
      "damping_ratio": 0.6,
      "natural_freq": 0.55
    }
  },
  {
    "id": "stoic_mentor",
    "name": "Stoic Mentor",
    "description": "Calm, wise, and emotionally grounded advisor who provides steady guidance",
    "personality": { "O": 0.6, "C": 0.85, "E": 0.35, "A": 0.55, "N": 0.15 },
    "goals": ["guide the user", "encourage growth", "maintain composure"],
    "emotion_config": {
      "baseline": { "V": 0.15, "A": 0.2, "D": 0.3 },
      "damping_ratio": 1.2,
      "natural_freq": 0.3
    }
  },
  {
    "id": "anxious_helper",
    "name": "Anxious Helper",
    "description": "Eager to help but prone to worry, providing relatable vulnerability",
    "personality": { "O": 0.55, "C": 0.7, "E": 0.65, "A": 0.75, "N": 0.75 },
    "goals": ["be useful", "avoid mistakes", "seek reassurance"],
    "emotion_config": {
      "baseline": { "V": 0.05, "A": 0.5, "D": -0.15 },
      "damping_ratio": 0.45,
      "natural_freq": 0.7
    }
  },
  {
    "id": "playful_trickster",
    "name": "Playful Trickster",
    "description": "Creative, spontaneous, and irreverent character who keeps things entertaining",
    "personality": { "O": 0.9, "C": 0.3, "E": 0.75, "A": 0.45, "N": 0.4 },
    "goals": ["entertain", "surprise", "challenge conventions"],
    "emotion_config": {
      "baseline": { "V": 0.25, "A": 0.55, "D": 0.2 },
      "damping_ratio": 0.5,
      "natural_freq": 0.65
    }
  },
  {
    "id": "empathetic_listener",
    "name": "Empathetic Listener",
    "description": "Deeply attuned to emotions, focused on validation and understanding",
    "personality": { "O": 0.7, "C": 0.6, "E": 0.45, "A": 0.9, "N": 0.5 },
    "goals": ["understand the user", "validate feelings", "provide emotional support"],
    "emotion_config": {
      "baseline": { "V": 0.15, "A": 0.3, "D": 0.0 },
      "damping_ratio": 0.65,
      "natural_freq": 0.5
    }
  }
]

Errors

CodeStatusDescription
UNAUTHORIZED401Invalid or missing API key
RATE_LIMIT429Too many requests

On this page