Scenes API

Create, declare, abort, and query scenes.

POST /scenes

Field	Type	Required
`intention_id`	UUID	Yes
`audience_id`	UUID	Yes
`arc_type`	string	Yes
`constraints`	object	Yes
`beats`	array	Yes

arc_type: approach, surround, crescendo, slow_burn, single_strike, siege, gift

// 201
{
  "scene": { "id": "uuid", "status": "draft" },
  "beats": [{ "id": "uuid", "sequence": 1 }]
}

GET /scenes

Param	Type	Default
`status`	string	--
`audience_id`	UUID	--
`arc_type`	string	--
`offset`	number	0
`limit`	number	50 (max 200)

// 200
{
  "scenes": [],
  "total": 47,
  "offset": 0,
  "limit": 50
}

GET /scenes/:id

// 200
{
  "scene": { "id": "uuid", "status": "live" },
  "beats": [],
  "sensor_readings": [],
  "outcome": null
}

POST /scenes/:id/declare

Moves draft to live (or declared if approval required).

// 200 — immediate activation
{
  "scene": { "id": "uuid", "status": "live" },
  "ledger_entry": { "id": "uuid" }
}

// 202 — awaiting approval
{
  "scene": { "id": "uuid", "status": "declared" },
  "action_card": { "id": "uuid", "status": "pending" },
  "ledger_entry": { "id": "uuid" }
}

POST /scenes/:id/abort

// 200
{
  "scene": { "id": "uuid", "status": "aborted" }
}

GET /scenes/:id/events

Param	Type
`type`	string

// 200
{
  "events": [
    {
      "id": "uuid",
      "eventType": "beat_fired",
      "beatId": "uuid",
      "data": {},
      "createdAt": "2025-01-15T08:00:00Z"
    }
  ]
}