API Reference - World Monitor

WorldMonitor exposes its data through a family of versioned REST services. Every endpoint follows the same shape:

https://api.worldmonitor.app/api/<service>/v1/<rpc-name>

<rpc-name> is kebab-case (e.g. list-acled-events, get-resilience-ranking). Auth is the same on every service — pass a user API key such as X-WorldMonitor-Key: wm_0123456789abcdef0123456789abcdef01234567, an operator-issued enterprise key, or use the dashboard’s browser session where supported. See Authentication for details. The grouped pages in the left sidebar render OpenAPI specs — request parameters, response schemas, and try-it-out — for the documented service groups. The bundled spec remains the complete machine-readable source. Prefer the terminal? The official worldmonitor CLI hits any of these paths (worldmonitor get /api/<service>/v1/<rpc-name>) and lists the live catalog with worldmonitor list.

Machine-readable discovery

Building an agent or codegen pipeline? Point at https://www.worldmonitor.app/ and follow the Link: header — every OpenAPI spec, MCP server card, OAuth endpoint, and agent-skill bundle is discoverable from one root URL via standard .well-known paths. See Agent Discovery for the full walkthrough. The single bundled spec is at /openapi.yaml — feed it to any OpenAPI generator to produce typed clients for the generated domain services in one pass. Platform endpoints documented in prose only (/api/bootstrap, /api/health, /api/product-catalog, the brief/notification/commerce routes, …) are not in the bundle. CompanyMonitoringService is a further exception: it is published as a contract only and is not routed yet, so generated clients for its operations will not receive a response. For compatibility guarantees, advance-notice periods, and the response headers used when a version is retired, see API versioning and deprecation.

Service catalog

Geopolitical — Conflicts, Military, Unrest, Intelligence, Displacement, Cyber, Sanctions Natural events — Natural Disasters, Seismology, Climate, Wildfires, Radiation, Thermal Economy and markets — Economic (FRED / IMF / BIS / country macro), Markets (quotes / indices / FX / commodities), Trade, Supply Chain, Consumer Prices, Predictions (prediction markets), Forecasts Infrastructure and transport — Aviation (aircraft tracking, flight search), Maritime (vessels, density zones), Infrastructure, Resilience (country resilience score and ranking) Health and environment — Public Health, Imagery, Webcams Other — News (feed digest, article summaries), Research, Positive Events, Giving, Batch (bulk read fan-out), Leads (contact and Pro-waitlist mutations documented under Platform Endpoints) Open any group in the sidebar to browse its operations.

Batch requests

Acting on many items? POST /api/batch/v1/execute accepts an array of operations and runs up to 20 documented GET endpoints concurrently in a single request, returning per-operation statuses and bodies:

curl -X POST https://api.worldmonitor.app/api/batch/v1/execute \
  -H "X-WorldMonitor-Key: wm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "id": "fear-greed", "path": "/api/market/v1/get-fear-greed-index" },
      { "id": "risk-de",    "path": "/api/intelligence/v1/get-country-risk?country_code=DE&jmespath=score" }
    ]
  }'

Each operation runs with the batch request’s own credentials and counts against your rate limits individually — batching saves round trips, not quota. Query strings pass through untouched, so per-operation jmespath projections keep the combined response small. Responses over 1 MB per operation are rejected with response_too_large; nested batches are refused.

MCP equivalents

If you’re moving between REST and the MCP server, treat them as related but distinct catalogs. REST coverage is defined by OpenAPI. MCP coverage is narrower: an endpoint is MCP-exposed only when the exact METHOD /api/... path is declared in a tool’s registry _apiPaths entry. Use the MCP API coverage table as the human-facing reverse lookup. It maps each MCP tool to the REST endpoints it explicitly serves. If a REST route is not in that table, it is REST-only as an API equivalence, even if a cache-backed MCP tool returns similar domain data. Common shapes:

Declared REST-backed tools — the tool’s registry names one or more exact REST paths, such as get_market_data covering market quote and sector endpoints.
Bundled cache reads — the tool reads one or more pre-seeded Redis keys and may not have a single REST equivalent, such as get_country_macro, the EU macro tools, get_aviation_status, and get_cyber_threats.
Live/composite tools — the tool fans out, filters geographically, or invokes LLM analysis; use the coverage table for the exact REST paths it claims.

Important non-equivalences:

REST endpoint	MCP status
`GET /api/conflict/v1/list-acled-events`	REST-only. `get_conflict_events` covers `list-iran-events`, `list-ucdp-events`, and `list-unrest-events`, not ACLED.
`GET /api/cyber/v1/list-cyber-threats`	REST-only for now. `get_cyber_threats` is a cache-backed MCP tool with no declared REST path.
`GET /api/infrastructure/v1/list-service-statuses`	REST-only. `get_infrastructure_status` declares `list-internet-outages` only.
`GET /api/supply-chain/v1/get-critical-minerals`	REST-only. `get_supply_chain_data` declares shipping stress and customs revenue only.
`GET /api/research/v1/list-arxiv-papers`, `GET /api/research/v1/list-trending-repos`, `GET /api/research/v1/list-hackernews-items`	REST-only. `get_research_signals` declares `list-tech-events` only.
`GET /api/aviation/v1/list-airport-delays`, `GET /api/aviation/v1/get-flight-status`	REST-only. MCP aviation coverage is via `get_airspace`, flight-search tools, and cache-backed `get_aviation_status`, not these routes.

Always cross-check against the bundled OpenAPI spec for REST path names, parameters, and response shapes, and against MCP API coverage for MCP exposure.

Platform endpoints

Bootstrap, health, version, and cache-purge live outside the per-service catalog — see Platform Endpoints.

Displacement snapshot years

GET /api/displacement/v1/get-displacement-summary reads the current Railway snapshot only. Omit year or use 0 for the latest available data; summary.year reports its actual data year, which can precede the calendar year. Explicit years must be integers from 1951 through the current year. Invalid years return 400 before a cache read. A valid year is available only when it matches the seed’s actual data year; this endpoint does not provide a historical archive. Missing, unreadable, or nonmatching snapshots return dataAvailable: false, fetchedAt: 0, and an empty summary. The gateway disables caching for these responses. Existing seeds remain readable with their original fetched timestamp; requests never fetch UNHCR or create query cache entries, even when the former SEED_FALLBACK_DISPLACEMENT flag is set. Country and flow limits still apply to the response without changing the shared seed. Desktop requests use the existing cloud proxy because the local sidecar does not hold Railway seeds.

ACLED conflict snapshot

GET /api/conflict/v1/list-acled-events reads the Railway snapshot only; requests never fetch ACLED on demand. The producer targets the latest 30 days. Country and date filters cannot retrieve history outside the available snapshot. Omit country, start, and end (or use empty country and zero timestamps) for the full geographic snapshot. Filter by ISO alpha-2 country code or country name. Non-default queries use inclusive Unix-millisecond bounds; an unset start defaults to midnight UTC 30 days ago and an unset end defaults to now. page_size and cursor remain accepted no-ops. Rows without valid coordinates are omitted, including GDELT fallback rows that carry no location. A missing or unreadable seed returns events: [] with caching disabled. Composed map embeds mark that conflict layer unavailable and disable frame caching until a seed read succeeds. An empty result does not establish that no conflict occurred. Browser sessions and API credentials retain their existing access; credentialless direct RPC calls are rejected.

​Machine-readable discovery

​Service catalog

​Batch requests

​MCP equivalents

​Platform endpoints

​Displacement snapshot years

​ACLED conflict snapshot