Events API

Event routes are world-scoped.

Endpoints

List Events

GET /api/worlds/:worldAddress/events?page=1&limit=20

Create Event

POST /api/worlds/:worldAddress/events

Request Body

{
  "name": "race_result",
  "description": "Resolves a race and updates horse stats",
  "firstVersion": {
    "inputSchema": { "raceId": "string" },
    "outputSchema": { "winner": "string", "time": "string" },
    "readEntities": [{ "schema": "horse" }],
    "stateChanges": { "horse": "partial" },
    "behaviorPrompt": "Determine the race winner based on horse speed ratings.",
    "mutationSettings": { "mode": "ai" },
    "executionSettings": { "visibility": "admin" }
  }
}

Field	Type	Required	Description
`name`	`string`	Yes	Event name, unique within world.
`description`	`string`	No	Event description.
`firstVersion`	`object`	Yes	Initial event-version definition.
`firstVersion.inputSchema`	`object`	No	Execution input contract.
`firstVersion.outputSchema`	`object`	No	Public result contract.
`firstVersion.readEntities`	`object[]`	No	Read access config.
`firstVersion.readEntities[].schema`	`string`	Yes	Entity schema name to read.
`firstVersion.readEntities[].filter`	`string[]`	No	Filter expressions (see below).
`firstVersion.stateChanges`	`object`	No	Per-schema mode map.
`firstVersion.behaviorPrompt`	`string`	No	Prompt for AI mode.
`firstVersion.mutationSettings.mode`	`enum`	No	`ai` or `direct`.
`firstVersion.mutationSettings.template`	`object`	Conditionally	Required when mode is `direct`.
`firstVersion.executionSettings.visibility`	`enum`	No	`admin`, `public`, or `cron`.
`firstVersion.executionSettings.priceUsd`	`number`	No	Price for public execution.
`firstVersion.executionSettings.cron.schedule`	`string`	Conditionally	Required for cron visibility; must be valid cron.
`firstVersion.executionSettings.cron.input`	`object`	No	Cron input template.

Get Event

GET /api/worlds/:worldAddress/events/:eventName

Update Event

PUT /api/worlds/:worldAddress/events/:eventName

Request Body

{
  "name": "race_result",
  "description": "Updated event description"
}

Field	Type	Required	Description
`name`	`string`	No	Event name.
`description`	`string`	No	Event description.

Delete Event

DELETE /api/worlds/:worldAddress/events/:eventName

List Event Versions

GET /api/worlds/:worldAddress/events/:eventName/event-versions?page=1&limit=20

Create Event Version

POST /api/worlds/:worldAddress/events/:eventName/event-versions

Request Body

{
  "inputSchema": { "raceId": "string", "weather": "string" },
  "outputSchema": { "winner": "string", "time": "string", "weather": "string" },
  "readEntities": [{ "schema": "horse", "filter": ["eq:instanceId:HORSE_1"] }],
  "stateChanges": { "horse": "partial" },
  "behaviorPrompt": "Consider weather conditions.",
  "mutationSettings": {
    "mode": "direct",
    "template": { "result": { "winner": "{{input.winner}}" } }
  },
  "executionSettings": {
    "visibility": "cron",
    "cron": { "schedule": "*/5 * * * *", "input": { "tick": "{{counter}}" } }
  }
}

Field	Type	Required	Description
`inputSchema`	`object`	No	Execution input contract.
`outputSchema`	`object`	No	Public result contract.
`readEntities`	`object[]`	No	Read access config.
`readEntities[].schema`	`string`	Yes	Entity schema name to read.
`readEntities[].filter`	`string[]`	No	Filter expressions.
`stateChanges`	`object`	No	Per-schema mode map (`partial`, `full`, `append`).
`behaviorPrompt`	`string`	No	Prompt for AI mode.
`mutationSettings.mode`	`enum`	No	`ai` or `direct`.
`mutationSettings.template`	`object`	Conditionally	Required when mode is `direct`.
`executionSettings.visibility`	`enum`	No	`admin`, `public`, or `cron`.
`executionSettings.priceUsd`	`number`	No	Price for public execution.
`executionSettings.cron.schedule`	`string`	Conditionally	Required for cron visibility; must be valid cron.
`executionSettings.cron.input`	`object`	No	Cron input template.

readEntities Filter

The filter field in readEntities specifies which entity instance IDs to load from the event input.

filter is an array of input paths that tells the system which specific entity instance IDs to load from the event input (e.g., ["raceId"] looks up eventInput.raceId to find the target instance).

Examples

1. Simple input key

Event input: { "raceId": "RACE_001" }

[{ "schema": "horse", "filter": ["raceId"] }]

Loads instances where instanceId === "RACE_001"

2. Nested input key

Event input: { "data": { "raceId": "RACE_001" } }

[{ "schema": "horse", "filter": ["data.raceId"] }]

Uses dot notation to access nested values

3. Multiple filters (OR logic)

Event input: { "horse1": "HORSE_1", "horse2": "HORSE_2" }

[{ "schema": "horse", "filter": ["horse1", "horse2"] }]

Loads both HORSE_1 and HORSE_2 instances

4. Schema-prefixed instance IDs

If instance IDs are prefixed with schema name (e.g., "horse:HORSE_1"):

Event input: { "winnerId": "horse:HORSE_1" }

[{ "schema": "horse", "filter": ["winnerId"] }]

Matches instanceId === "horse:HORSE_1" exactly

5. Multiple schemas with different filters

Event input: { "raceId": "RACE_001", "betId": "BET_001" }

[
  { "schema": "race", "filter": ["raceId"] },
  { "schema": "bet", "filter": ["betId"] }
]

6. No filter (load all instances)

[{ "schema": "horse" }]

Loads all instances of schema (useful for listing queries)

Lock Event Version

POST /api/worlds/:worldAddress/events/:eventName/event-versions/:version/lock

Get Event Version

GET /api/worlds/:worldAddress/events/:eventName/event-versions/:version

Update Event Version

PUT /api/worlds/:worldAddress/events/:eventName/event-versions/:version

Request Body

{
  "inputSchema": { "raceId": "string", "weather": "string" },
  "outputSchema": { "winner": "string", "time": "string" },
  "readEntities": [{ "schema": "horse", "filter": ["raceId"] }],
  "stateChangeSchema": { "horse": "partial" },
  "behaviorPrompt": "Updated behavior prompt.",
  "mutationSettings": {
    "mode": "ai",
    "behaviorPrompt": "New prompt"
  },
  "executionSettings": {
    "visibility": "admin"
  }
}

Field	Type	Required	Description
`inputSchema`	`object`	No	Execution input contract.
`outputSchema`	`object`	No	Public result contract.
`readEntities`	`object[]`	No	Read access config.
`readEntities[].schema`	`string`	Yes	Entity schema name to read.
`readEntities[].filter`	`string[]`	No	Filter expressions.
`stateChangeSchema`	`object`	No	Per-schema mode map (`partial`, `full`, `append`).
`behaviorPrompt`	`string`	No	Prompt for AI mode.
`mutationSettings`	`object`	No	Mutation configuration. Set to `null` to remove.
`mutationSettings.mode`	`enum`	No	`ai` or `direct`.
`mutationSettings.template`	`object`	Conditionally	Required when mode is `direct`.
`mutationSettings.behaviorPrompt`	`string`	No	Prompt for AI mode.
`executionSettings`	`object`	No	Execution settings. Set to `null` to remove.
`executionSettings.visibility`	`enum`	No	`admin`, `public`, or `cron`.
`executionSettings.priceUsd`	`number`	No	Price for public execution.
`executionSettings.cron.schedule`	`string`	Conditionally	Required for cron visibility.
`executionSettings.cron.input`	`object`	No	Cron input template.

Delete Event Version

DELETE /api/worlds/:worldAddress/events/:eventName/event-versions/:version