Turn

The Turn endpoint is the core of molroo API. Send a message (or a full event), and get back the computed emotional state with LLM-ready prompt_data.

Process Turn

POST /v1/turn

Request Body

Simplified Input (recommended)

Field	Type	Required	Description
`sessionId`	`string`	Yes	Session ID from persona creation
`message`	`string`	Yes	The user's message text

Full Event Input

Field	Type	Required	Description
`sessionId`	`string`	Yes	Session ID
`event`	`object`	Yes	The event to process
`event.description`	`string`	Yes	Natural language description of the event
`event.source`	`string`	Yes	`"user"`, `"system"`, or `"internal"`
`elapsedSeconds`	`number`	No	Seconds since last interaction (for idle decay)
`event_context`	`string`	No	Additional context for LLM response enrichment

Tip: Use simplified input for chatbot-style interactions. Use full event input when you need to specify the event source or provide elapsed time.

Response

Field	Type	Description
`appraisal`	`object`	Cognitive appraisal result (6-dimensional vector)
`new_emotion`	`object`	Updated emotional state `{ V, A, D }`
`emotion_intensity`	`number`	Overall intensity `[0, 1]`
`discrete_emotion`	`object`	`{ primary, secondary, intensity }` — human-readable labels
`stage_transition`	`boolean`	Whether a soul stage transition occurred
`body_budget`	`number`	Psychological energy level `[0, 1]`
`soul_stage`	`object`	`{ id, name }` — current psychological stage (1-15)
`proactive_hint`	`object`	Next proactive check time and pending actions
`prompt_data`	`object`	LLM-ready structured prompts (see below)

prompt_data Structure

Every response includes prompt_data with pre-built text blocks for your LLM:

{
  "prompt_data": {
    "system": { ... },
    "context": {
      "emotion": { "primary": "concerned", "intensity_level": "strong" },
      "energy": { "level": "good", "budget_percentage": 82 },
      "stage": { "name": "Attentive", "behavioral_tendency": "..." },
      "needs": { "autonomy": 0.6, "competence": 0.7, "relatedness": 0.5 },
      "interpersonal": { "trust": 0.68, "attachment_style": "secure" },
      "formatted": { "context_block": "..." }
    },
    "instruction": {
      "stage_instruction": "Show active interest...",
      "expression_guide": "Speak with measured concern...",
      "formatted": { "instruction_block": "..." }
    },
    "formatted": {
      "system_prompt": "You are Mira, a warm...",
      "context_block": "[Emotion: concerned (strong)]...",
      "instruction_block": "Show genuine care..."
    }
  }
}

Use prompt_data.formatted.system_prompt, .context_block, and .instruction_block as system messages in your LLM call. See prompt_data concept for details.

AppraisalVector Fields

The appraisal object contains the cognitive appraisal of the event:

Field	Range	Description
`goal_relevance`	`[0, 1]`	How relevant to the character's goals
`goal_congruence`	`[-1, 1]`	Helps (+) or hinders (-) goals
`expectedness`	`[0, 1]`	How expected (0 = surprise, 1 = anticipated)
`controllability`	`[0, 1]`	How much control the character has
`agency`	`[-1, 1]`	Who caused it (-1 = external, 1 = self)
`norm_compatibility`	`[-1, 1]`	Alignment with character's values

Examples

Simplified Input

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 really missed you today"
  }'

const response = 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 really missed you today",
  }),
});
 
const result = await response.json();
// result.discrete_emotion = { primary: "touched", intensity: "moderate" }
// result.new_emotion = { V: 0.72, A: 0.58, D: 0.31 }
// result.prompt_data.formatted.system_prompt = "You are Mira, a warm..."

Full Event Input

const response = 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",
    event: {
      description: "The user told Luna they got promoted at work",
      source: "user",
    },
    elapsedSeconds: 3600, // 1 hour since last interaction
  }),
});

Errors

Code	Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`VALIDATION_ERROR`	400	Invalid request body
`NOT_FOUND`	404	Session not found
`RATE_LIMIT`	429	Too many requests

Turn

On this page