Skip to main content
POST
TriggerSimulation

Authorizations

X-WorldMonitor-Key
string
header
required

User-issued WorldMonitor API key.

Headers

Idempotency-Key
string

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.

Required string length: 1 - 255
Pattern: ^[\x21-\x7E]{1,255}$

Body

application/json

TriggerSimulationRequest enqueues a run for the current simulation package.

clientVersion
string

Optional client version, such as "mcp-client/0.2". Logged, never stored.

Response

Successful response

TriggerSimulationResponse is the HTTP 200 result of an enqueue attempt. Errors return a non-200 status instead.

queued
boolean

True when the task was newly enqueued; false on idempotency hit or no_package.

runId
string

Server-derived runId from SIMULATION_PACKAGE_LATEST_KEY. Empty string when reason='no_package' (no package pointer was available).

pkgFingerprint
string

Opaque fingerprint of the package key; it changes when the key changes. Empty when reason='no_package'.

reason
string

'' when queued, 'no_package' when no package exists, or 'already-handled' when this cycle's run is already queued or done.