ScenarioService

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:{job_id}. Requires entitlement tier >= 1.

post/api/scenario/v1/run-scenario

Request

  • Base URL: https://api.worldmonitor.app
  • URL: https://api.worldmonitor.app/api/scenario/v1/run-scenario
  • Auth: one of:
    • API key in header X-WorldMonitor-Key
    • API key in header X-Api-Key
    • HTTP bearer

Headers

Idempotency-Keystring

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.

Request body

scenarioIdstring required

Scenario template id — must match an entry in SCENARIO_TEMPLATES.

iso2string

Optional 2-letter ISO country code to scope the impact computation. When absent, use the bounded country/sector manifest in existing seed metadata. Missing or old manifest means unknown coverage.

disruptionPctinteger

Physical scenarios only. Omitted preserves the template default; zero is valid.

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.

jobIdstring

Generated job id of the form scenario:{epoch_ms}:{8-char-suffix}.

statusstring

Always "pending" at enqueue time.

statusUrlstring

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.

Changes

No recorded changes to this operation across all 1 revision of this API.