Entity Instances API

Entity instance routes are deployment-scoped under worlds.

Endpoints

List Entity Instances

GET /api/worlds/:worldAddress/deployments/:address/entity-instances?entitySchema=horse&page=1&limit=20

Query parameters:

entitySchema - Filter by entity schema name (optional)

Create Entity Instance

POST /api/worlds/:worldAddress/deployments/:address/entity-instances

Request Body

{
  "entitySchema": "horse",
  "instanceId": "HORSE_1",
  "state": {
    "name": "Midnight Comet",
    "speed_rating": 0.85
  }
}

Field	Type	Required	Description
`entitySchema`	`string`	Yes	Entity schema name.
`instanceId`	`string`	Yes	Instance key unique in deployment+schema.
`state`	`object`	No	Initial state. Defaults to `{}`.

Get Entity Instance

GET /api/worlds/:worldAddress/deployments/:address/entity-instances/:instanceId

Update Entity Instance

PUT /api/worlds/:worldAddress/deployments/:address/entity-instances/:instanceId

Request Body

{
  "state": {
    "name": "Midnight Comet",
    "speed_rating": 0.9,
    "wins": 5
  }
}

Field	Type	Required	Description
`state`	`object`	Yes	Updated state object (replaces existing state).

Delete Entity Instance

DELETE /api/worlds/:worldAddress/deployments/:address/entity-instances/:instanceId

Example

curl -X POST https://api.narrativeprotocol.com/api/worlds/0x123.../deployments/0xabc.../entity-instances \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "entitySchema": "horse",
    "instanceId": "HORSE_1",
    "state": {
      "name": "Midnight Comet",
      "speed_rating": 0.85
    }
  }'