API Endpoints

The molroo API is available at https://api.molroo.io. All persona endpoints require authentication via the X-API-Key header.

Base URL

https://api.molroo.io

Include your API key in every request:

curl https://api.molroo.io/personas \
  -H "X-API-Key: mk_live_xxxxx"

Method	Path	Description
`POST`	`/personas`	Create a new persona
`GET`	`/personas`	List all personas (cursor-based pagination)
`GET`	`/personas/:id`	Get persona info + config
`PATCH`	`/personas/:id`	Update persona config
`DELETE`	`/personas/:id`	Soft-delete a persona
`POST`	`/personas/:id/restore`	Restore a deleted persona

Method	Path	Description
`POST`	`/personas/:id/perceive`	Process event through emotion pipeline
`POST`	`/personas/:id/tick`	Advance time (mood decay, body recovery)
`POST`	`/personas/:id/emotion`	Direct VAD override
`POST`	`/personas/:id/annotate`	Append text to next LLM prompt
`POST`	`/personas/:id/next-response`	Force next response text
`GET`	`/personas/:id/state`	Get current emotional state
`POST`	`/personas/:id/prompt-context`	Get assembled system prompt

Method	Path	Description
`GET`	`/personas/:id/snapshot`	Get full persona snapshot
`PUT`	`/personas/:id/snapshot`	Restore from snapshot

All successful responses are wrapped in a result envelope:

{
  "ok": true,
  "result": {
    // response data
  }
}

Error responses use a standard error format:

{
  "error": {
    "code": "PERSONA_NOT_FOUND",
    "message": "Persona not found"
  }
}

The full OpenAPI specification is auto-generated from engine Zod schemas and available at:

https://api.molroo.io/openapi.json