Run a multi-edit Scenario (staged or applied)

POST

/v1/scenarios/run

curl --request POST \
  --url https://api.aerandil.com/v1/scenarios/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "commit": false, "steps": [ { "action": "example", "params": {}, "target": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "object_type": "example" } } ] }'

• Production API

Replays steps in order inside one transaction through the same guards, validation, and handlers as /apply, so later steps see earlier steps’ writes. commit=false (default) stages the scenario: the response carries per-step effect sets plus the merged diff a real apply would produce, then everything rolls back — zero durable trace. commit=true applies the whole scenario atomically; any step’s failure aborts every step. A step may target an object created by an earlier step via {"created_by_step": k, "object_type": ...} — positional, resolved at replay time. Requires the apply scope of every step’s action; internal-runner actions are rejected. Bounded at 100 steps. commit=true accepts Idempotency-Key.

Authorizations

• aerandil_oauth

Request Body^required

Media typeapplication/json

object

commit

false stages (diff + rollback); true applies atomically.

boolean

steps

required

Array<object>

>= 1 items <= 100 items

object

action

required

Registered action api-name (e.g. hospitality.action.check_in).

string

params

The step action’s parameters — same flat canonical JSON as that action’s /apply schema.

object

key

additional properties

any

target

One of:

object

object

id

required

string format: uuid

object_type

required

string

object

object

created_by_step

required

integer

object_type

required

string

Responses

200

The scenario outcome: per-step effect sets, the merged diff, commit-time warnings, and whether it committed.

Media typeapplication/json

object

commit_warnings

required

Array<object>

object

committed

required

boolean

diff

required

Merged object diff across all steps (Created+Modified→Created, Created+Deleted→net nothing, Modified+Deleted→Deleted).

Array<object>

object

id

required

string format: uuid

kind

required

string

Allowed values: created modified deleted

object_type

required

string

idempotent_replay

Present and true when a committed run was replayed from the idempotency cache.

boolean

steps

required

Per-step apply responses, in step order.

Array<object>

object

Example

{
  "diff": [
    {
      "kind": "created"
    }
  ]
}

Headers

Cache-Control

string

Allowed value: no-store

Always no-store — live, per-run data.

403

A step’s apply scope is missing, or a step names an internal-runner action.

422

A step failed validation — nothing was applied.