Create, list, retrieve, and delete sessions — the emotional identity of your AI characters.

Persona

Sessions are created around a persona — the emotional identity of your AI character. You can use a preset or define a custom persona with Big Five traits.

Create Session

POST /v1/persona

Create a new emotion session. Use a preset for quick start, or define a custom persona.

Request Body

Option A: Use a Preset

Field	Type	Required	Description
`preset`	`string`	Yes	Preset ID (see Presets)

Option B: Custom Persona

Field	Type	Required	Description
`identity`	`object`	No	Character identity definition
`identity.name`	`string`	No	Character name
`identity.core_values`	`string[]`	No	Core values that guide emotional responses
`identity.speaking_style`	`string`	No	Natural language description of speaking style
`identity.role`	`string`	No	Character's role or occupation
`identity.language`	`string`	No	Language directive for prompt_data generation
`personality`	`object`	Yes	HEXACO personality traits
`personality.O`	`number`	Yes	Openness to Experience `[0, 1]`
`personality.C`	`number`	Yes	Conscientiousness `[0, 1]`
`personality.E`	`number`	Yes	Extraversion `[0, 1]`
`personality.A`	`number`	Yes	Agreeableness `[0, 1]`
`personality.N`	`number`	Yes	Neuroticism `[0, 1]`
`personality.H`	`number`	Yes	Honesty-Humility `[0, 1]`
`personality.facets`	`object`	No	Fine-grained sub-traits (4 per domain, 24 total)
`emotion_config`	`object`	No	Override emotion dynamics (derived from personality if omitted)
`goals`	`string[]`	No	Character goals for appraisal context

Note: You can combine a preset with overrides — pass preset along with any custom fields and the custom fields take precedence.

Response

Field	Type	Description
`sessionId`	`string`	Unique session identifier
`persona`	`object`	The resolved persona config
`config`	`object`	Emotion dynamics config
`createdAt`	`string`	ISO 8601 creation timestamp

Examples

Preset (recommended for getting started)

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

const response = 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 response.json();
// session.sessionId = "ses_abc123..."

Custom Persona

curl -X POST https://api.molroo.io/v1/persona \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": {
      "name": "Luna",
      "core_values": ["empathy", "curiosity", "honesty"],
      "speaking_style": "warm and thoughtful, uses metaphors",
      "role": "companion"
    },
    "personality": {
      "O": 0.8, "C": 0.6, "E": 0.5,
      "A": 0.9, "N": 0.3, "H": 0.85
    },
    "goals": ["understand the user", "provide emotional support"]
  }'

Errors

Code	Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`VALIDATION_ERROR`	400	Invalid request body or parameter
`INVALID_PRESET`	400	Unknown preset ID
`RATE_LIMIT`	429	Too many requests

List Sessions

GET /v1/persona

List all sessions with cursor-based pagination.

Query Parameters

Parameter	Type	Required	Description
`cursor`	`string`	No	Cursor from previous response
`limit`	`number`	No	Max results per page (default: 20)

Response

Field	Type	Description
`sessions`	`array`	Array of session summaries
`cursor`	`string?`	Next page cursor (null if last)

Example

curl "https://api.molroo.io/v1/persona?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Session

GET /v1/persona/:id

Retrieve a session by its ID.

Path Parameters

Parameter	Type	Description
`id`	`string`	The session ID to retrieve

Example

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

Delete Session

DELETE /v1/persona/:id

Permanently delete a session and all associated state.

Path Parameters

Parameter	Type	Description
`id`	`string`	The session ID to delete

Response

Field	Type	Description
`deleted`	`boolean`	`true` if successfully deleted
`id`	`string`	The deleted session ID

Example

curl -X DELETE https://api.molroo.io/v1/persona/ses_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

Code	Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`NOT_FOUND`	404	Session not found

Persona

On this page