API Reference
Endpoints
REST API endpoints for api.molroo.io.
API Endpoints
The molroo API is available at https://api.molroo.io. All endpoints require authentication via the X-API-Key header.
Base URL
https://api.molroo.ioAuthentication
Include your API key in every request:
curl https://api.molroo.io/worlds \
-H "X-API-Key: mk_live_xxxxx"Endpoint Groups
World Configuration
| Method | Path | Description |
|---|---|---|
POST | /worlds | Create a new world |
GET | /worlds | List all worlds |
GET | /worlds/:id | Get world details |
PATCH | /worlds/:id | Update world definition |
DELETE | /worlds/:id | Soft-delete a world |
POST | /worlds/:id/restore | Restore a deleted world |
World Runtime
| Method | Path | Description |
|---|---|---|
POST | /worlds/:id/chat | Send a chat message |
POST | /worlds/:id/events | Dispatch a world event |
POST | /worlds/:id/tick | Advance world time |
POST | /worlds/:id/time-jump | Jump forward in time |
POST | /worlds/:id/mutate | Execute mutations |
POST | /worlds/:id/context | Get entity context |
POST | /worlds/:id/query | Query world state |
GET | /worlds/:id/personas | Get persona configs |
World Data
| Method | Path | Description |
|---|---|---|
GET | /worlds/:id/snapshot | Get full snapshot |
PUT | /worlds/:id/snapshot | Restore from snapshot |
Response Format
All successful responses are wrapped in a result envelope:
{
"result": {
// response data
}
}Error responses use a standard error format:
{
"error": {
"code": "ENTITY_NOT_FOUND",
"message": "Entity \"unknown\" not found in world"
}
}OpenAPI Specification
The full OpenAPI specification is available at:
https://api.molroo.io/openapi.jsonDetailed per-endpoint documentation with request/response schemas will be auto-generated from this specification. Run npm run generate:api in the docs-site to update.