Deployments API

Deployment routes are world-scoped.

Endpoints

List Deployments

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

Create Deployment

POST /api/worlds/:worldAddress/deployments

Request Body

{
  "name": "Season 1",
  "description": "Runtime deployment",
  "mode": "upgradable",
  "aiModelId": "openai/gpt-oss-120b",
  "isLLMPublic": false,
  "payToAddress": "6Q2...wallet",
  "bindings": [
    {
      "event": "race_result",
      "eventVersion": 1,
      "targetChains": ["near-testnet"],
      "onchain": {
        "stateChanges": ["wins", "speed_rating"],
        "result": ["winner"]
      }
    }
  ],
  "sourceDeployment": "0x123...abc"
}

Field	Type	Required	Description
`name`	`string`	Yes	Deployment name.
`description`	`string`	No	Description.
`mode`	`enum`	No	`upgradable` or `locked` (default `upgradable`).
`aiModelId`	`string`	No	Selected model ID.
`isLLMPublic`	`boolean`	No	Whether LLM prompt/response data is public.
`payToAddress`	`string`	No	Payment receiver Solana address for paid public execution.
`bindings`	`object[]`	Yes	Initial event bindings (array).
`bindings[].event`	`string`	Yes	Event name.
`bindings[].eventVersion`	`number`	Yes	Relative version number.
`bindings[].targetChains`	`enum[]`	No	Chain networks for on-chain push (per binding).
`bindings[].onchain`	`object`	No	Field filter for on-chain push (per binding).
`bindings[].onchain.stateChanges`	`string[]`	No	Allowed state-change keys.
`bindings[].onchain.result`	`string[]`	No	Allowed result keys.
`sourceDeployment`	`string`	No	Clone entity state and bindings from source deployment (address).

Get Deployment

GET /api/worlds/:worldAddress/deployments/:address

Update Deployment

PUT /api/worlds/:worldAddress/deployments/:address

Request Body

{
  "name": "Season 1 Updated",
  "description": "Updated description",
  "aiModelId": "openai/gpt-oss-120b",
  "isLLMPublic": true,
  "payToAddress": "6Q2...wallet"
}

Field	Type	Required	Description
`name`	`string`	No	Deployment name.
`description`	`string`	No	Description.
`aiModelId`	`string`	No	Selected model ID. Set to `null` to remove.
`isLLMPublic`	`boolean`	No	Whether LLM prompt/response data is public.
`payToAddress`	`string`	No	Payment receiver Solana address. Set to `null` to remove.

Delete Deployment

DELETE /api/worlds/:worldAddress/deployments/:address

Execute Event

POST /api/worlds/:worldAddress/deployments/:address/execute

Request Body

{
  "event": "race_result",
  "input": { "raceId": "RACE_001" }
}

Field	Type	Required	Description
`event`	`string`	Yes	Event name to execute.
`input`	`object`	No	Event input payload.

Lock Deployment

POST /api/worlds/:worldAddress/deployments/:address/lock

Publish Deployment

POST /api/worlds/:worldAddress/deployments/:address/publish

Makes the deployment public, enabling public execution. This endpoint is idempotent — calling it on an already public deployment returns success.

Response:

{
  "success": true,
  "data": { "isPublic": true },
  "message": "Deployment published successfully"
}

Or if already public:

{
  "success": true,
  "data": { "isPublic": true },
  "message": "Deployment is already public"
}

List Event History

GET /api/worlds/:worldAddress/deployments/:address/history?page=1&limit=10

List Event Bindings

GET /api/worlds/:worldAddress/deployments/:address/event-bindings

Get Event Binding

GET /api/worlds/:worldAddress/deployments/:address/event-bindings?event=race_result

Query parameters:

event - Event name (required)

Create Event Bindings

POST /api/worlds/:worldAddress/deployments/:address/event-bindings

Request Body

[
  {
    "event": "race_result",
    "eventVersion": 2
  }
]

Field	Type	Required	Description
`event`	`string`	Yes	Event name to bind.
`eventVersion`	`number`	Yes	Relative version number to bind.

Request body must be an array. Duplicate events are rejected.

Update Event Bindings

PUT /api/worlds/:worldAddress/deployments/:address/event-bindings

Request Body

[
  {
    "event": "race_result",
    "eventVersion": 3,
    "targetChains": ["solana-devnet"],
    "onchain": {
      "stateChanges": ["wins"],
      "result": ["winner"]
    }
  }
]

Field	Type	Required	Description
`event`	`string`	Yes	Event name to update.
`eventVersion`	`number`	No	New version number to bind.
`targetChains`	`enum[]`	No	Chain networks for on-chain push.
`onchain`	`object`	No	Field filter for on-chain push.
`onchain.stateChanges`	`string[]`	No	Allowed state-change keys.
`onchain.result`	`string[]`	No	Allowed result keys.

Request body must be an array. Duplicate events are rejected.

Delete Event Binding

DELETE /api/worlds/:worldAddress/deployments/:address/event-bindings?event=race_result

Query parameters:

event - Event name to unbind (required)

List Entity Instances

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

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	Unique per deployment+schema.
`state`	`object`	No	Initial state. Defaults to `{}`.

Public Execution

Public execution is available via app route:

POST /app/deployments/:address/execute

Request Body

{
  "event": "race_result",
  "input": { "raceId": "RACE_001" },
  "wallet": "<solana-wallet>",
  "signature": "<base58-signature>",
  "message": "narrativeprotocol:<deploymentAddress>:<eventName>:<timestamp>"
}

Field	Type	Required	Description
`event`	`string`	Yes	Event name to execute.
`input`	`object`	No	Event input payload.
`wallet`	`string`	Yes	Signer wallet (base58 public key).
`signature`	`string`	Yes	Signature over `message`.
`message`	`string`	Yes	`narrativeprotocol:{deploymentAddress}:{eventName}:{timestamp}`.

Rules:

Event must allow public execution.
If executionSettings.priceUsd > 0, provide valid X-Payment header (x402).