> ## Documentation Index
> Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Catalog of documented World Monitor REST service groups. Every endpoint follows /api/<service>/v1/<rpc-name> and returns consistent envelopes.

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](/docs/usage-auth) 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](/docs/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](/docs/agent-discovery) for the full walkthrough.

The single bundled spec is at [`/openapi.yaml`](https://www.worldmonitor.app/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](/docs/api-versioning).

## 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:

```bash theme={null}
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](/docs/mcp-jmespath) 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](/docs/mcp-overview), 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](/docs/mcp-overview#api-coverage) 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](https://www.worldmonitor.app/openapi.yaml) for REST path names, parameters, and response shapes, and against [MCP API coverage](/docs/mcp-overview#api-coverage) for MCP exposure.

## Platform endpoints

Bootstrap, health, version, and cache-purge live outside the per-service catalog — see [Platform Endpoints](/docs/api-platform).

## 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.