RunScenario
RunScenario enqueues a scenario job on scenario-queue:pending. PRO-gated. Async job pattern: a successful enqueue returns HTTP 202 Accepted with a Location header pointing at GetScenarioStatus; poll it (or the statusUrl body field) with the returned jobId until status is “done” or “failed”. The scenario-worker (scripts/scenario-worker.mjs) pulls jobs off the queue via BLMOVE and writes results under scenario-result:. Requires entitlement tier >= 1.
Authorizations
User-issued WorldMonitor API key.
Headers
Optional client-generated idempotency key. Retrying a POST with the same key and an identical request body replays the original response (only the status, body, and Content-Type are reproduced) instead of re-executing; reusing the key with a different body is rejected with 422. For mutations this avoids duplicating the side effect, while for batch-read POSTs it replays a cached snapshot that can be up to 24 hours stale. Keys are scoped per authenticated caller (falling back to the source IP for unauthenticated endpoints) and retained for 24 hours.
1 - 255^[\x21-\x7E]{1,255}$Body
RunScenarioRequest enqueues a scenario job on the scenario-queue:pending Upstash list for the async scenario-worker to pick up.
Scenario template id — must match an entry in SCENARIO_TEMPLATES.
1 - 128Optional 2-letter ISO country code to scope the impact computation. When absent, v1 computes only the seeded reporter set: US, CN, RU, IR, IN, TW.
^([A-Z]{2})?$Response
Accepted — scenario job enqueued. The body carries the job id (jobId), the initial status (always pending) and a poll URL (statusUrl); the Location header points at the same GetScenarioStatus endpoint. Poll it until status is done or failed.
RunScenarioResponse carries the enqueued job id. Clients poll GetScenarioStatus with this id until status != "pending".
NOTE: a successful enqueue returns HTTP 202 Accepted with a Location header pointing at GetScenarioStatus — the legacy (pre-sebuf) contract, restored. The sebuf-generated server still emits 200 for every success (no per-RPC status-code annotation exists), so the gateway upgrades the status via the setSuccessStatusOverride side-channel (server/_shared/response-headers.ts). Treat any 2xx as success; the interim guidance to branch on response body shape instead of the status code remains valid.
Generated job id of the form scenario:{epoch_ms}:{8-char-suffix}.
Always "pending" at enqueue time.
Convenience URL the caller can use to poll this job's status.
Server-computed as /api/scenario/v1/get-scenario-status?jobId=<job_id>.
Restored after the v1 → v1 sebuf migration because external callers
may key off this field.
