REST API endpoints for api.molroo.io — world management and persona interactions.

World API Endpoints

The World API is available at https://api.molroo.io. All 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/worlds \
  -H "X-API-Key: mk_live_xxxxx"

The World API shares the same API key system as the persona API.

Method	Path	Description
`POST`	`/worlds`	Create a new world
`GET`	`/worlds`	List worlds (cursor-based pagination)
`GET`	`/worlds/{id}`	Get world details
`PATCH`	`/worlds/{id}`	Update world config
`DELETE`	`/worlds/{id}`	Soft-delete a world

Method	Path	Description
`POST`	`/worlds/{id}/personas`	Add a persona to the world
`GET`	`/worlds/{id}/personas`	List personas in the world
`GET`	`/worlds/{id}/personas/{pid}`	Get persona details and current emotional state
`DELETE`	`/worlds/{id}/personas/{pid}`	Remove a persona from the world

Method	Path	Description
`POST`	`/worlds/{id}/actions`	Create a custom action for the world
`GET`	`/worlds/{id}/actions`	List available actions (defaults + custom)
`DELETE`	`/worlds/{id}/actions/{aid}`	Delete a custom action

Method	Path	Description
`POST`	`/worlds/{id}/interact`	Execute an action against a persona (billable)
`GET`	`/worlds/{id}/events`	Get the world event log

Method	Path	Description
`PUT`	`/worlds/{id}/relationships`	Upsert a relationship between an actor and a persona
`GET`	`/worlds/{id}/relationships`	List all relationships in the world
`DELETE`	`/worlds/{id}/relationships/{rid}`	Delete a relationship

All successful responses are wrapped in a result envelope:

{
  "result": {
    // response data
  }
}

Error responses use a standard error format:

{
  "error": {
    "code": "WORLD_NOT_FOUND",
    "message": "World abc123 not found"
  }
}

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

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