docs/api/worldmonitor.openapi.yaml
Rama main · réplica de lectura del repositorio original.
openapi: 3.1.0
info:
title: WorldMonitor API
description: 'Unified OpenAPI bundle spanning all WorldMonitor services. Versioning and deprecation policy: https://www.worldmonitor.app/api-versioning.md (HTML: https://www.worldmonitor.app/docs/api-versioning)'
contact:
name: WorldMonitor
email: support@worldmonitor.app
version: 1.0.0
servers:
- url: https://api.worldmonitor.app
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
paths:
/api/aviation/v1/list-aircraft-emergencies:
get:
tags:
- AviationService
summary: ListAircraftEmergencies
description: |-
ListAircraftEmergencies returns reported 7500, 7600 and 7700 signals independently of military classification.
The 200 schema describes the unprojected response. With jmespath, the result may instead be any JSON value, including an array, scalar, or null.
operationId: ListAircraftEmergencies
parameters:
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"feeds":
- "fetchedAt": 1717200000000
"message": "Synthetic example."
"source": "adsb.lol"
"squawk": "7500"
"status": "available"
- "fetchedAt": 1717200000000
"message": "Synthetic example."
"source": "adsb.lol"
"squawk": "7600"
"status": "available"
- "fetchedAt": 1717200000000
"message": "Synthetic example."
"source": "adsb.lol"
"squawk": "7700"
"status": "available"
"observations":
- "address": "a00001"
"callsign": "SYNTHETIC"
"description": "Synthetic example. No observed incident."
"militaryFlag": "unknown"
"observedAt": 0
"source": "adsb.lol"
"squawk": "7500"
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_ListAircraftEmergenciesResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/aviation/v1/list-airport-delays:
get:
tags:
- AviationService
summary: ListAirportDelays
description: ListAirportDelays returns delay status for each monitored airport from seeded FAA and AviationStack data plus NOTAM closures, marking unreported hubs unknown.
operationId: ListAirportDelays
parameters:
- name: page_size
in: query
description: |-
Maximum items per page (1-100).
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: 25
schema:
type: integer
format: int32
- name: cursor
in: query
description: |-
Cursor for next page.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: "next-page-token"
schema:
type: string
- name: region
in: query
description: |-
Optional region filter.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: "AIRPORT_REGION_AMERICAS"
schema:
type: string
enum:
- 'AIRPORT_REGION_AMERICAS'
- 'AIRPORT_REGION_EUROPE'
- 'AIRPORT_REGION_APAC'
- 'AIRPORT_REGION_MENA'
- 'AIRPORT_REGION_AFRICA'
- name: min_severity
in: query
description: |-
Optional minimum severity filter.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: "FLIGHT_DELAY_SEVERITY_NORMAL"
schema:
type: string
enum:
- 'FLIGHT_DELAY_SEVERITY_NORMAL'
- 'FLIGHT_DELAY_SEVERITY_MINOR'
- 'FLIGHT_DELAY_SEVERITY_MODERATE'
- 'FLIGHT_DELAY_SEVERITY_MAJOR'
- 'FLIGHT_DELAY_SEVERITY_SEVERE'
- 'FLIGHT_DELAY_SEVERITY_UNKNOWN'
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"alerts":
- "avgDelayMinutes": 1
"cancelledFlights": 1
"city": "example"
"country": "US"
"delayType": "FLIGHT_DELAY_TYPE_GROUND_STOP"
"id": "example-id"
"pagination":
"nextCursor": "next-page-token"
"totalCount": 1
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_ListAirportDelaysResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/aviation/v1/get-airport-ops-summary:
get:
tags:
- AviationService
summary: GetAirportOpsSummary
description: GetAirportOpsSummary returns watched-airport operational health, including delay percentages, average delay minutes, cancellation rates and closure status.
operationId: GetAirportOpsSummary
parameters:
- name: airports
in: query
description: IATA airport codes to query (e.g., ["IST", "ESB", "LHR"]).
required: false
style: form
explode: true
example:
- "JFK"
schema:
type: array
items:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"cacheHit": true
"summaries":
- "avgDelayMinutes": 1
"cancellationRate": 75.25
"closureStatus": true
"delayPct": 1.5
"iata": "JFK"
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_GetAirportOpsSummaryResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/aviation/v1/list-airport-flights:
get:
tags:
- AviationService
summary: ListAirportFlights
description: ListAirportFlights returns recent arrivals and departures with direction and limit filters, status and carrier. PRO-gated. Requires an active Pro subscription.
operationId: ListAirportFlights
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: airport
in: query
description: IATA airport code (e.g., "IST").
required: true
example: "JFK"
schema:
type: string
- name: direction
in: query
description: Direction filter.
required: false
example: "FLIGHT_DIRECTION_DEPARTURE"
schema:
type: string
enum:
- 'FLIGHT_DIRECTION_DEPARTURE'
- 'FLIGHT_DIRECTION_ARRIVAL'
- 'FLIGHT_DIRECTION_BOTH'
- name: limit
in: query
description: Maximum number of flights to return (1-100).
required: false
example: 25
schema:
type: integer
format: int32
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"flights":
- "actualArrival": 1
"actualDeparture": 1
"aircraftIcao24": "a835af"
"aircraftType": "all"
"cancelled": true
"source": "example"
"totalAvailable": 1
"updatedAt": 1717200000000
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_ListAirportFlightsResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: Pro subscription required.
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/aviation/v1/get-carrier-ops:
get:
tags:
- AviationService
summary: GetCarrierOps
description: GetCarrierOps returns delay and cancellation metrics grouped by carrier. PRO-gated. Requires an active Pro subscription.
operationId: GetCarrierOps
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: airports
in: query
description: IATA airport codes to aggregate carrier metrics from.
required: false
style: form
explode: true
example:
- "JFK"
schema:
type: array
items:
type: string
- name: min_flights
in: query
description: |-
Minimum number of flights required to include a carrier (default: 3).
The generated GET decoder emits 0 when the query param is absent, and 0
means "use the default" in the handler — an explicit 0 is not a usable
filter (every group has >= 1 flight).
required: false
example: 1
schema:
type: integer
format: int32
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"carriers":
- "airport": "JFK"
"avgDelayMinutes": 1
"cancellationRate": 75.25
"cancelledCount": 1
"carrier":
"iataCode": "JFK"
"icaoCode": "example"
"name": "WorldMonitor Analyst"
"source": "example"
"updatedAt": 1717200000000
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_GetCarrierOpsResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: Pro subscription required.
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/aviation/v1/get-flight-status:
get:
tags:
- AviationService
summary: GetFlightStatus
description: GetFlightStatus looks up the current status of a specific flight. PRO-gated. Requires an active Pro subscription.
operationId: GetFlightStatus
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: flight_number
in: query
description: IATA flight number (e.g., "TK1952").
required: true
example: "JFK"
schema:
type: string
- name: date
in: query
description: Departure date in ISO 8601 format (e.g., "2026-03-05").
required: true
example: "2026-01-15"
schema:
type: string
- name: origin
in: query
description: Optional origin airport IATA code to disambiguate.
required: false
example: "JFK"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"cacheHit": true
"flights":
- "actualArrival": 1
"actualDeparture": 1
"aircraftIcao24": "a835af"
"aircraftType": "all"
"cancelled": true
"source": "example"
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_GetFlightStatusResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: Pro subscription required.
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/aviation/v1/track-aircraft:
get:
tags:
- AviationService
summary: TrackAircraft
description: Track an aircraft by ICAO24 hex or callsign within map bounds, returning position observations, altitude, speed, source and update time for flight monitoring.
operationId: TrackAircraft
parameters:
- name: icao24
in: query
description: ICAO 24-bit transponder address (hex, e.g., "4b1805").
required: false
example: "a835af"
schema:
type: string
- name: callsign
in: query
description: ATC callsign (e.g., "THY7CX").
required: false
example: "example"
schema:
type: string
- name: sw_lat
in: query
description: Optional bounding box south-west latitude.
required: false
example: 40.7128
schema:
type: number
format: double
- name: sw_lon
in: query
description: Optional bounding box south-west longitude.
required: false
example: -74.006
schema:
type: number
format: double
- name: ne_lat
in: query
description: Optional bounding box north-east latitude.
required: false
example: 40.7128
schema:
type: number
format: double
- name: ne_lon
in: query
description: Optional bounding box north-east longitude.
required: false
example: -74.006
schema:
type: number
format: double
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"positions":
- "altitudeM": 1.5
"callsign": "example"
"groundSpeedKts": 1.5
"icao24": "a835af"
"lat": 40.7128
"source": "example"
"updatedAt": 1717200000000
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_TrackAircraftResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/aviation/v1/get-youtube-live-stream-info:
get:
tags:
- AviationService
summary: GetYoutubeLiveStreamInfo
description: 'GetYoutubeLiveStreamInfo names a YouTube video (title and channel name) through YouTube oEmbed. Channel live detection is retired: a channel-only query returns error "channel_live_detection_retired", and the channel, is_live and hls_url fields are deprecated.'
operationId: GetYoutubeLiveStreamInfo
parameters:
- name: channel
deprecated: true
in: query
description: 'Deprecated: YouTube channel handle or ID. Channel live detection is retired; a channel-only query returns error "channel_live_detection_retired".'
required: false
example: "example"
schema:
type: string
- name: video_id
in: query
description: YouTube video ID to name.
required: false
example: "example-id"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"channelExists": true
"channelName": "DW News"
"error": ""
"hlsUrl": ""
"isLive": false
"title": "DW News livestream"
"videoId": "LuKwFajn37U"
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_GetYoutubeLiveStreamInfoResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/aviation/v1/search-flight-prices:
get:
tags:
- AviationService
summary: SearchFlightPrices
description: Search per-person flight price offers by route, dates and cabin, with indicative-price and provider status. PRO-gated. Requires an active Pro subscription.
operationId: SearchFlightPrices
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: origin
in: query
description: Origin airport IATA code.
required: true
example: "JFK"
schema:
type: string
- name: destination
in: query
description: Destination airport IATA code.
required: true
example: "LHR"
schema:
type: string
- name: departure_date
in: query
description: Outbound departure date (ISO 8601).
required: true
example: "2026-01-15"
schema:
type: string
- name: return_date
in: query
description: Return date (ISO 8601), empty for one-way.
required: false
example: "2026-01-15"
schema:
type: string
- name: adults
in: query
description: |-
Number of adult passengers (1-9).
Accepted but currently ignored; quotes are per-person and the count does not filter.
required: false
example: 1
schema:
type: integer
format: int32
- name: cabin
in: query
description: Desired cabin class.
required: false
example: "CABIN_CLASS_ECONOMY"
schema:
type: string
enum:
- 'CABIN_CLASS_ECONOMY'
- 'CABIN_CLASS_PREMIUM_ECONOMY'
- 'CABIN_CLASS_BUSINESS'
- 'CABIN_CLASS_FIRST'
- name: nonstop_only
in: query
description: Whether to restrict to nonstop flights only.
required: false
example: true
schema:
type: boolean
- name: max_results
in: query
description: Maximum number of quotes to return (1-50).
required: false
example: 1
schema:
type: integer
format: int32
- name: currency
in: query
description: ISO 4217 currency code for prices (e.g., "usd", "eur", "try").
required: false
example: "USD"
schema:
type: string
- name: market
in: query
description: Market/locale code (e.g., "us", "tr").
required: false
example: "example"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"degraded": true
"error": "example"
"isDemoMode": true
"isIndicative": true
"provider": "worldmonitor"
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_SearchFlightPricesResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: Pro subscription required.
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/aviation/v1/list-aviation-news:
get:
tags:
- AviationService
summary: ListAviationNews
description: ListAviationNews returns articles from nine aviation RSS feeds such as FlightGlobal and Aviation Week, filtered by up to 10 entities over a 1-168 hour window.
operationId: ListAviationNews
parameters:
- name: entities
in: query
description: Entities to filter by (airline names, airport codes, route strings).
required: false
style: form
explode: true
example:
- "example"
schema:
type: array
items:
type: string
- name: window_hours
in: query
description: Time window in hours to look back (1-168).
required: false
example: 1
schema:
type: integer
format: int32
- name: max_items
in: query
description: Maximum number of news items to return (1-50).
required: false
example: 1
schema:
type: integer
format: int32
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"items":
- "id": "example-id"
"imageUrl": "https://example.com/worldmonitor"
"matchedEntities":
- "example"
"publishedAt": 1717200000000
"snippet": "example"
"source": "example"
"updatedAt": 1717200000000
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_ListAviationNewsResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/aviation/v1/search-google-flights:
get:
tags:
- AviationService
summary: SearchGoogleFlights
description: Search Google Flights itineraries by route and dates, with cabin, stops, airline and passenger filters, returning flight legs, duration and availability status.
operationId: SearchGoogleFlights
parameters:
- name: origin
in: query
description: Departure airport IATA code (e.g. "JFK").
required: false
example: "JFK"
schema:
type: string
- name: destination
in: query
description: Arrival airport IATA code (e.g. "LHR").
required: false
example: "LHR"
schema:
type: string
- name: departure_date
in: query
description: Departure date in YYYY-MM-DD format.
required: false
example: "2026-01-15"
schema:
type: string
- name: return_date
in: query
description: Return date in YYYY-MM-DD format; omit for one-way.
required: false
example: "2026-01-15"
schema:
type: string
- name: cabin_class
in: query
description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.'
required: false
example: "ECONOMY"
schema:
type: string
- name: max_stops
in: query
description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.'
required: false
example: "ANY"
schema:
type: string
- name: departure_window
in: query
description: Departure time window in HH-HH format (e.g. "6-20").
required: false
example: "6-20"
schema:
type: string
- name: airlines
in: query
description: Airline IATA codes to filter by (e.g. ["BA", "AA"]).
required: false
style: form
explode: true
example:
- "BA"
schema:
type: array
items:
type: string
- name: sort_by
in: query
description: 'Sort order: CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME.'
required: false
example: "CHEAPEST"
schema:
type: string
- name: passengers
in: query
description: Number of adult passengers (1-9).
required: false
example: 1
schema:
type: integer
format: int32
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"degraded": true
"error": "example"
"flights":
- "durationMinutes": 42
"legs":
- "airlineCode": "example"
"arrivalAirport": "example"
"arrivalDatetime": "2026-01-15"
"departureAirport": "example"
"departureDatetime": "2026-01-15"
"price": 75.25
"stops": 1
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_SearchGoogleFlightsResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/aviation/v1/search-google-dates:
get:
tags:
- AviationService
summary: SearchGoogleDates
description: SearchGoogleDates returns the cheapest Google Flights fare per departure date over up to 31 days, one-way or round trip, with cabin and stop filters.
operationId: SearchGoogleDates
parameters:
- name: origin
in: query
description: Departure airport IATA code (e.g. "JFK").
required: false
example: "JFK"
schema:
type: string
- name: destination
in: query
description: Arrival airport IATA code (e.g. "LHR").
required: false
example: "LHR"
schema:
type: string
- name: start_date
in: query
description: Start of date range in YYYY-MM-DD format.
required: false
example: "2026-01-15"
schema:
type: string
- name: end_date
in: query
description: End of date range in YYYY-MM-DD format.
required: false
example: "2026-01-15"
schema:
type: string
- name: trip_duration
in: query
description: Trip duration in days (required for round-trip searches).
required: false
example: 42
schema:
type: integer
format: int32
- name: is_round_trip
in: query
description: Whether to search for round-trip flights.
required: false
example: true
schema:
type: boolean
- name: cabin_class
in: query
description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.'
required: false
example: "ECONOMY"
schema:
type: string
- name: max_stops
in: query
description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.'
required: false
example: "ANY"
schema:
type: string
- name: departure_window
in: query
description: Departure time window in HH-HH format (e.g. "6-20").
required: false
example: "6-20"
schema:
type: string
- name: airlines
in: query
description: Airline IATA codes to filter by (e.g. ["BA", "AA"]).
required: false
style: form
explode: true
example:
- "BA"
schema:
type: array
items:
type: string
- name: sort_by_price
in: query
description: Whether to sort results by price (lowest first).
required: false
example: true
schema:
type: boolean
- name: passengers
in: query
description: Number of adult passengers (1-9).
required: false
example: 1
schema:
type: integer
format: int32
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"dates":
- "date": "2026-01-15"
"price": 75.25
"returnDate": "2026-01-15"
"degraded": true
"error": "example"
schema:
$ref: '#/components/schemas/worldmonitor_aviation_v1_SearchGoogleDatesResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/batch/v1/execute:
post:
parameters:
- name: Idempotency-Key
in: header
description: 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: false
example: "4f8b9c2e-1a3d-4b6f-8e0a-2c5d7f9b1e34"
schema:
type: string
minLength: 1
maxLength: 255
pattern: "^[\\x21-\\x7E]{1,255}$"
tags:
- BatchService
summary: ExecuteBatch
description: ExecuteBatch runs a bulk batch of up to 20 read (GET) operations concurrently in one round trip and returns per-operation statuses and bodies. Use it instead of looping single calls when acting on many items; add a per-operation ?jmespath= projection to keep each body small.
operationId: ExecuteBatch
requestBody:
content:
application/json:
example:
"operations":
- "id": "example-id"
"path": "/api/market/v1/get-fear-greed-index"
schema:
$ref: '#/components/schemas/worldmonitor_batch_v1_ExecuteBatchRequest'
required: true
responses:
"200":
description: Successful response
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key echoed from the request. Present only when the client opted into idempotency.
Idempotent-Replayed:
schema:
type: boolean
description: true when this response was replayed from an earlier request with the same key, false on the first (original) request. Present only when the client opted into idempotency.
content:
application/json:
example:
"failed": 1
"results":
- "body":
{}
"error": "example"
"id": "example-id"
"status": 1
"succeeded": 1
schema:
$ref: '#/components/schemas/worldmonitor_batch_v1_ExecuteBatchResponse'
"400":
description: Validation error, invalid Idempotency-Key header, or malformed JSON request body
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
- $ref: '#/components/schemas/InvalidRequestBodyError'
"409":
description: A request with this Idempotency-Key is still being processed
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key supplied by the client.
Retry-After:
schema:
type: string
description: Seconds to wait before retrying the in-flight request.
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
"422":
description: The Idempotency-Key was already used with a different request body
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key supplied by the client.
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/climate/v1/list-climate-anomalies:
get:
tags:
- ClimateService
summary: ListClimateAnomalies
description: ListClimateAnomalies returns 7-day temperature and precipitation departures from 1991-2020 monthly normals per climate zone, using Open-Meteo ERA5 data.
operationId: ListClimateAnomalies
parameters:
- name: page_size
in: query
description: |-
Maximum items per page (1-100).
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: 25
schema:
type: integer
format: int32
- name: cursor
in: query
description: |-
Cursor for next page.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: "next-page-token"
schema:
type: string
- name: min_severity
in: query
description: |-
Optional filter by anomaly severity.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: "ANOMALY_SEVERITY_NORMAL"
schema:
type: string
enum:
- 'ANOMALY_SEVERITY_NORMAL'
- 'ANOMALY_SEVERITY_MODERATE'
- 'ANOMALY_SEVERITY_EXTREME'
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"anomalies":
- "location":
"latitude": 40.7128
"longitude": -74.006
"period": "daily"
"precipDelta": 1.5
"severity": "ANOMALY_SEVERITY_NORMAL"
"tempDelta": 1.5
"type": "ANOMALY_TYPE_WARM"
"zone": "example"
"pagination":
"nextCursor": "next-page-token"
"totalCount": 1
schema:
$ref: '#/components/schemas/worldmonitor_climate_v1_ListClimateAnomaliesResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/climate/v1/list-climate-disasters:
get:
tags:
- ClimateService
summary: ListClimateDisasters
description: ListClimateDisasters returns recent floods, cyclones, droughts, heatwaves, wildfires and volcanoes from ReliefWeb, GDACS, EONET and FIRMS, up to 100 per page.
operationId: ListClimateDisasters
parameters:
- name: page_size
in: query
description: Maximum items per page (1-100).
required: false
example: 25
schema:
type: integer
format: int32
- name: cursor
in: query
description: Cursor for next page.
required: false
example: "next-page-token"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"disasters":
- "affectedPopulation": 1
"country": "US"
"countryCode": "US"
"id": "example-id"
"lat": 40.7128
"pagination":
"nextCursor": "next-page-token"
"totalCount": 1
schema:
$ref: '#/components/schemas/worldmonitor_climate_v1_ListClimateDisastersResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/climate/v1/get-co2-monitoring:
get:
tags:
- ClimateService
summary: GetCo2Monitoring
description: GetCo2Monitoring returns NOAA GML Mauna Loa CO2 readings (current, year-ago, 12-month trend) with global methane and nitrous oxide levels, refreshed every 3 days.
operationId: GetCo2Monitoring
parameters:
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"monitoring":
"annualGrowthRate": 75.25
"currentPpm": 1.5
"measuredAt": "1717200000000"
"methanePpb": 1.5
"monthlyAverage": 1.5
schema:
$ref: '#/components/schemas/worldmonitor_climate_v1_GetCo2MonitoringResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/climate/v1/get-ocean-ice-data:
get:
tags:
- ClimateService
summary: GetOceanIceData
description: GetOceanIceData returns NSIDC Arctic sea ice extent and anomaly with a 12-month trend, NASA sea level rise, NOAA 0-700m ocean heat content and SST anomaly.
operationId: GetOceanIceData
parameters:
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"data":
"arcticExtentAnomalyMkm2": 1.5
"arcticExtentMkm2": 1.5
"arcticTrend": "example"
"iceTrend12m":
- "anomalyMkm2": 1.5
"extentMkm2": 1.5
"month": "example"
"measuredAt": 1717200000000
schema:
$ref: '#/components/schemas/worldmonitor_climate_v1_GetOceanIceDataResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/climate/v1/list-air-quality-data:
get:
tags:
- ClimateService
summary: ListAirQualityData
description: ListAirQualityData returns PM2.5 station readings from the last two hours from OpenAQ, plus WAQI when configured, with a US EPA AQI and risk level each.
operationId: ListAirQualityData
parameters:
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"fetchedAt": 1717200000000
"stations":
- "aqi": 1
"city": "example"
"countryCode": "US"
"lat": 40.7128
"lng": -74.006
schema:
$ref: '#/components/schemas/worldmonitor_climate_v1_ListAirQualityDataResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/climate/v1/list-climate-news:
get:
tags:
- ClimateService
summary: ListClimateNews
description: |-
ListClimateNews retrieves latest climate/environment intelligence headlines from seeded RSS feeds.
Empty items with fetched_at=0 or data_available=false means the seed snapshot
is unavailable/degraded, not that there are confirmed zero headlines.
operationId: ListClimateNews
parameters:
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"dataAvailable": true
"fetchedAt": 1717200000000
"items":
- "id": "example-id"
"publishedAt": 1717200000000
"sourceName": "WorldMonitor Analyst"
"summary": "Example WorldMonitor observation."
"title": "example"
schema:
$ref: '#/components/schemas/worldmonitor_climate_v1_ListClimateNewsResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/company-monitoring/v1/create-monitored-company:
post:
parameters:
- name: Idempotency-Key
in: header
description: 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: false
example: "4f8b9c2e-1a3d-4b6f-8e0a-2c5d7f9b1e34"
schema:
type: string
minLength: 1
maxLength: 255
pattern: "^[\\x21-\\x7E]{1,255}$"
tags:
- CompanyMonitoringService
summary: CreateMonitoredCompany
description: 'Creates an account-scoped monitored-company record. Requires company_monitoring:write; runtime remains disabled until dependency #6003 passes.'
operationId: CreateMonitoredCompany
requestBody:
content:
application/json:
example:
"clientRequestId": "example-id"
"company":
"aliases":
- "example"
"customerReference": "example"
"domains":
- "example.com"
"domicileCountry": "DOMICILE_COUNTRY_US"
"identifiers":
- "example-id"
"locations":
- "example"
"name": "WorldMonitor Analyst"
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_CreateMonitoredCompanyRequest'
required: true
responses:
"200":
description: Successful response
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key echoed from the request. Present only when the client opted into idempotency.
Idempotent-Replayed:
schema:
type: boolean
description: true when this response was replayed from an earlier request with the same key, false on the first (original) request. Present only when the client opted into idempotency.
content:
application/json:
example:
"company":
"canonicalUrl": "https://example.com/worldmonitor"
"claims":
- "allowedUses":
- "COMPANY_CLAIM_ALLOWED_USE_DISCOVERY"
"claimId": "cm_claim_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"expiresAt": "2026-01-15T12:00:00Z"
"provenance": "example"
"trustState": "COMPANY_CLAIM_TRUST_STATE_DECLARED"
"companyId": "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"coverage": "COMPANY_COVERAGE_STATE_AWAITING_FIRST_SCAN"
"createdAt": "2026-01-15T12:00:00Z"
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_CreateMonitoredCompanyResponse'
"400":
description: Validation error, invalid Idempotency-Key header, or malformed JSON request body
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
- $ref: '#/components/schemas/InvalidRequestBodyError'
"409":
description: A request with this Idempotency-Key is still being processed
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key supplied by the client.
Retry-After:
schema:
type: string
description: Seconds to wait before retrying the in-flight request.
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
"422":
description: The Idempotency-Key was already used with a different request body
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key supplied by the client.
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/company-monitoring/v1/update-monitored-company:
post:
parameters:
- name: Idempotency-Key
in: header
description: 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: false
example: "4f8b9c2e-1a3d-4b6f-8e0a-2c5d7f9b1e34"
schema:
type: string
minLength: 1
maxLength: 255
pattern: "^[\\x21-\\x7E]{1,255}$"
tags:
- CompanyMonitoringService
summary: UpdateMonitoredCompany
description: 'Applies a bounded patch to an account-scoped monitored-company record. Requires company_monitoring:write; runtime remains disabled until dependency #6003 passes.'
operationId: UpdateMonitoredCompany
requestBody:
content:
application/json:
example:
"companyId": "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"patch":
"addClaims":
- "type": "COMPANY_CLAIM_TYPE_ALIAS"
"value": "example"
"customerReference": "example"
"domicileCountry": "DOMICILE_COUNTRY_US"
"name": "WorldMonitor Analyst"
"removeClaimIds":
- "cm_claim_01ARZ3NDEKTSV4RRFFQ69G5FAV"
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_UpdateMonitoredCompanyRequest'
required: true
responses:
"200":
description: Successful response
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key echoed from the request. Present only when the client opted into idempotency.
Idempotent-Replayed:
schema:
type: boolean
description: true when this response was replayed from an earlier request with the same key, false on the first (original) request. Present only when the client opted into idempotency.
content:
application/json:
example:
"company":
"canonicalUrl": "https://example.com/worldmonitor"
"claims":
- "allowedUses":
- "COMPANY_CLAIM_ALLOWED_USE_DISCOVERY"
"claimId": "cm_claim_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"expiresAt": "2026-01-15T12:00:00Z"
"provenance": "example"
"trustState": "COMPANY_CLAIM_TRUST_STATE_DECLARED"
"companyId": "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"coverage": "COMPANY_COVERAGE_STATE_AWAITING_FIRST_SCAN"
"createdAt": "2026-01-15T12:00:00Z"
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_UpdateMonitoredCompanyResponse'
"400":
description: Validation error, invalid Idempotency-Key header, or malformed JSON request body
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
- $ref: '#/components/schemas/InvalidRequestBodyError'
"409":
description: A request with this Idempotency-Key is still being processed
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key supplied by the client.
Retry-After:
schema:
type: string
description: Seconds to wait before retrying the in-flight request.
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
"422":
description: The Idempotency-Key was already used with a different request body
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key supplied by the client.
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/company-monitoring/v1/set-monitored-company-state:
post:
parameters:
- name: Idempotency-Key
in: header
description: 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: false
example: "4f8b9c2e-1a3d-4b6f-8e0a-2c5d7f9b1e34"
schema:
type: string
minLength: 1
maxLength: 255
pattern: "^[\\x21-\\x7E]{1,255}$"
tags:
- CompanyMonitoringService
summary: SetMonitoredCompanyState
description: 'Transitions an account-scoped monitored company between active, paused, and removed states. Requires company_monitoring:write; runtime remains disabled until dependency #6003 passes.'
operationId: SetMonitoredCompanyState
requestBody:
content:
application/json:
example:
"companyId": "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"targetLifecycle": "MONITORED_COMPANY_LIFECYCLE_ACTIVE"
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_SetMonitoredCompanyStateRequest'
required: true
responses:
"200":
description: Successful response
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key echoed from the request. Present only when the client opted into idempotency.
Idempotent-Replayed:
schema:
type: boolean
description: true when this response was replayed from an earlier request with the same key, false on the first (original) request. Present only when the client opted into idempotency.
content:
application/json:
example:
"company":
"canonicalUrl": "https://example.com/worldmonitor"
"claims":
- "allowedUses":
- "COMPANY_CLAIM_ALLOWED_USE_DISCOVERY"
"claimId": "cm_claim_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"expiresAt": "2026-01-15T12:00:00Z"
"provenance": "example"
"trustState": "COMPANY_CLAIM_TRUST_STATE_DECLARED"
"companyId": "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"coverage": "COMPANY_COVERAGE_STATE_AWAITING_FIRST_SCAN"
"createdAt": "2026-01-15T12:00:00Z"
"snapshotRequired": true
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_SetMonitoredCompanyStateResponse'
"400":
description: Validation error, invalid Idempotency-Key header, or malformed JSON request body
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
- $ref: '#/components/schemas/InvalidRequestBodyError'
"409":
description: A request with this Idempotency-Key is still being processed
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key supplied by the client.
Retry-After:
schema:
type: string
description: Seconds to wait before retrying the in-flight request.
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
"422":
description: The Idempotency-Key was already used with a different request body
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key supplied by the client.
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/company-monitoring/v1/import-monitored-company-batch:
post:
tags:
- CompanyMonitoringService
summary: ImportMonitoredCompanyBatch
description: 'Imports up to 100 normalized account-scoped company rows with deterministic per-row outcomes. Requires company_monitoring:write; runtime remains disabled until dependency #6003 passes.'
operationId: ImportMonitoredCompanyBatch
requestBody:
content:
application/json:
example:
"clientImportId": "example-id"
"contractVersion": "cm-import-v1"
"rows":
- "company":
"aliases":
- "example"
"customerReference": "example"
"domains":
- "example.com"
"domicileCountry": "DOMICILE_COUNTRY_US"
"identifiers":
- "example-id"
"locations":
- "example"
"name": "WorldMonitor Analyst"
"ordinal": 0
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_ImportMonitoredCompanyBatchRequest'
required: true
responses:
"200":
description: Successful response
content:
application/json:
example:
"createdCount": 1
"rejectedCount": 1
"replayedCount": 1
"results":
- "companyId": "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"ordinal": 0
"outcome": "COMPANY_IMPORT_ROW_OUTCOME_CREATED"
"reasonCode": "example"
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_ImportMonitoredCompanyBatchResponse'
"400":
description: Validation error or malformed JSON request body
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/InvalidRequestBodyError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/company-monitoring/v1/list-monitored-companies:
get:
tags:
- CompanyMonitoringService
summary: ListMonitoredCompanies
description: 'Lists account-scoped monitored companies at a signed snapshot boundary. Requires company_monitoring:read; runtime remains disabled until dependency #6003 passes.'
operationId: ListMonitoredCompanies
parameters:
- name: lifecycle
in: query
description: Accepted values are active, paused, and removed.
required: false
style: form
explode: true
example:
- "active"
schema:
type: array
items:
type: "string"
pattern: "^(?:active|paused|removed|MONITORED_COMPANY_LIFECYCLE_(?:ACTIVE|PAUSED|REMOVED))$"
description: "Accepted values are active, paused, and removed."
- name: coverage
in: query
description: Accepted values are awaiting_first_scan, identity_unresolved, adequate, partial, stale, unavailable, and needs_confirmation.
required: false
style: form
explode: true
example:
- "awaiting_first_scan"
schema:
type: array
items:
type: "string"
pattern: "^(?:awaiting_first_scan|identity_unresolved|adequate|partial|stale|unavailable|needs_confirmation|COMPANY_COVERAGE_STATE_(?:AWAITING_FIRST_SCAN|IDENTITY_UNRESOLVED|ADEQUATE|PARTIAL|STALE|UNAVAILABLE|NEEDS_CONFIRMATION))$"
- name: page_size
in: query
description: Maximum rows to return, from 1 through 100; zero requests the server default.
required: false
example: 25
schema:
type: integer
format: int32
- name: cursor
in: query
description: Signed opaque cursor bound to the account, filters, mode, expiry, and snapshot generation; never a storage identifier.
required: false
example: "cmc1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
schema:
type: string
pattern: '^cmc1\.[A-Za-z0-9_-]{16,1000}[A-Za-z0-9_-]{0,536}\.[A-Za-z0-9_-]{43}$'
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"companies":
- "canonicalUrl": "https://example.com/worldmonitor"
"claims":
- "allowedUses":
- "COMPANY_CLAIM_ALLOWED_USE_DISCOVERY"
"claimId": "cm_claim_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"expiresAt": "2026-01-15T12:00:00Z"
"provenance": "example"
"trustState": "COMPANY_CLAIM_TRUST_STATE_DECLARED"
"companyId": "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"coverage": "COMPANY_COVERAGE_STATE_AWAITING_FIRST_SCAN"
"createdAt": "2026-01-15T12:00:00Z"
"nextCursor": "cmc1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
"snapshot":
"pollCursor": "cmc1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
"snapshotAsOf": "example"
"snapshotGeneration": "1717200000000"
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_ListMonitoredCompaniesResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/company-monitoring/v1/list-company-event-impacts:
get:
tags:
- CompanyMonitoringService
summary: ListCompanyEventImpacts
description: 'Lists account-scoped material impacts with independent direction, confidence, and lifecycle fields. Requires company_monitoring:read; runtime remains disabled until dependency #6003 passes.'
operationId: ListCompanyEventImpacts
parameters:
- name: company_id
in: query
description: Account-scoped logical company IDs to include; storage identifiers are not accepted.
required: false
style: form
explode: true
example:
- "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
schema:
type: array
items:
type: "string"
pattern: "^cm_company_[0-9A-HJKMNP-TV-Z]{26}$"
- name: direction
in: query
description: Accepted values are positive, negative, and mixed.
required: false
style: form
explode: true
example:
- "positive"
schema:
type: array
items:
type: "string"
pattern: "^(?:positive|negative|mixed|MATERIAL_IMPACT_DIRECTION_(?:POSITIVE|NEGATIVE|MIXED))$"
description: "Accepted values are positive, negative, and mixed."
- name: lifecycle
in: query
description: Accepted values are admitted, corrected, and retracted.
required: false
style: form
explode: true
example:
- "admitted"
schema:
type: array
items:
type: "string"
pattern: "^(?:admitted|corrected|retracted|MATERIAL_IMPACT_LIFECYCLE_(?:ADMITTED|CORRECTED|RETRACTED))$"
description: "Accepted values are admitted, corrected, and retracted."
- name: page_size
in: query
description: Maximum rows to return, from 1 through 100; zero requests the server default.
required: false
example: 25
schema:
type: integer
format: int32
- name: cursor
in: query
description: Signed opaque cursor bound to the account, filters, mode, expiry, and snapshot generation; never a storage identifier.
required: false
example: "cmc1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
schema:
type: string
pattern: '^cmc1\.[A-Za-z0-9_-]{16,1000}[A-Za-z0-9_-]{0,536}\.[A-Za-z0-9_-]{43}$'
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"impacts":
- "canonicalUrl": "https://example.com/worldmonitor"
"changedAt": "2026-01-15T12:00:00Z"
"channels":
- "MATERIAL_IMPACT_CHANNEL_REPUTATION"
"companyId": "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"confidence":
"attribution": 1
"materialImpact": 1
"occurrenceTruth": 1
"overall": 1
"nextCursor": "cmc1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
"snapshot":
"pollCursor": "cmc1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
"snapshotAsOf": "example"
"snapshotGeneration": "1717200000000"
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_ListCompanyEventImpactsResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/company-monitoring/v1/list-company-event-changes:
get:
tags:
- CompanyMonitoringService
summary: ListCompanyEventChanges
description: 'Polls account-scoped material-impact changes from a signed opaque cursor. Requires company_monitoring:read; runtime remains disabled until dependency #6003 passes.'
operationId: ListCompanyEventChanges
parameters:
- name: cursor
in: query
description: Required signed opaque poll cursor bound to the account, mode, expiry, and snapshot generation; never a storage identifier.
required: true
example: "cmc1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
schema:
type: string
pattern: '^cmc1\.[A-Za-z0-9_-]{16,1000}[A-Za-z0-9_-]{0,536}\.[A-Za-z0-9_-]{43}$'
- name: page_size
in: query
description: Maximum changes to return, from 1 through 100; zero requests the server default.
required: false
example: 25
schema:
type: integer
format: int32
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"impacts":
- "canonicalUrl": "https://example.com/worldmonitor"
"changedAt": "2026-01-15T12:00:00Z"
"channels":
- "MATERIAL_IMPACT_CHANNEL_REPUTATION"
"companyId": "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"confidence":
"attribution": 1
"materialImpact": 1
"occurrenceTruth": 1
"overall": 1
"nextCursor": "cmc1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
"pollState": "COMPANY_EVENT_POLL_STATE_CURRENT"
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_ListCompanyEventChangesResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/company-monitoring/v1/get-company-material-event:
get:
tags:
- CompanyMonitoringService
summary: GetCompanyMaterialEvent
description: 'Returns one account-scoped material event, its impact, and bounded evidence references. Requires company_monitoring:read; runtime remains disabled until dependency #6003 passes.'
operationId: GetCompanyMaterialEvent
parameters:
- name: impact_id
in: query
description: Account-scoped logical impact ID; storage identifiers are not accepted.
required: true
example: "cm_impact_01ARZ3NDEKTSV4RRFFQ69G5FAV"
schema:
type: string
pattern: '^cm_impact_[0-9A-HJKMNP-TV-Z]{26}$'
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"event":
"canonicalUrl": "https://example.com/worldmonitor"
"category": "cs.AI"
"eventId": "cm_event_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"lifecycle": "MATERIAL_IMPACT_LIFECYCLE_ADMITTED"
"occurredAt": "2026-01-15T12:00:00Z"
"evidence":
- "authorityTier": "EVIDENCE_AUTHORITY_TIER_PRIMARY_VERIFIED"
"canonicalUrl": "https://example.com/worldmonitor"
"evidenceId": "cm_evidence_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"excerpt": "example"
"provider": "MONITORING_PROVIDER_EXA"
"evidenceTotalCount": 1
"evidenceTruncated": true
"impact":
"canonicalUrl": "https://example.com/worldmonitor"
"changedAt": "2026-01-15T12:00:00Z"
"channels":
- "MATERIAL_IMPACT_CHANNEL_REPUTATION"
"companyId": "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"confidence":
"attribution": 1
"materialImpact": 1
"occurrenceTruth": 1
"overall": 1
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_GetCompanyMaterialEventResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/company-monitoring/v1/get-company-coverage:
get:
tags:
- CompanyMonitoringService
summary: GetCompanyCoverage
description: 'Returns the current coverage state for one account-scoped monitored company. Requires company_monitoring:read; runtime remains disabled until dependency #6003 passes.'
operationId: GetCompanyCoverage
parameters:
- name: company_id
in: query
description: Account-scoped logical company ID; storage identifiers are not accepted.
required: true
example: "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
schema:
type: string
pattern: '^cm_company_[0-9A-HJKMNP-TV-Z]{26}$'
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"companyId": "cm_company_01ARZ3NDEKTSV4RRFFQ69G5FAV"
"coverage":
"assessmentReady": true
"changedAt": "2026-01-15T12:00:00Z"
"observation": "COMPANY_OBSERVATION_STATE_EVENTS_OBSERVED"
"providers":
- "capped": true
"fresh": true
"provider": "MONITORING_PROVIDER_EXA"
"reasonCode": "example"
"returnedWindowEnd": "example"
"state": "COMPANY_COVERAGE_STATE_AWAITING_FIRST_SCAN"
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_GetCompanyCoverageResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/company-monitoring/v1/get-company-monitoring-status:
get:
tags:
- CompanyMonitoringService
summary: GetCompanyMonitoringStatus
description: 'Returns account-scoped limits, snapshot generation, access state, and independent feature flags. Requires company_monitoring:read; runtime remains disabled until dependency #6003 passes.'
operationId: GetCompanyMonitoringStatus
parameters:
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"accessState": "COMPANY_MONITORING_ACCESS_STATE_DISABLED"
"companyCount": 1
"companyLimit": 500
"featureFlags":
"alerts": false
"exaProvider": false
"publication": false
"restWrites": false
"ui": false
"snapshotGeneration": "1717200000000"
schema:
$ref: '#/components/schemas/worldmonitor_company_monitoring_v1_GetCompanyMonitoringStatusResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/conflict/v1/list-acled-events:
get:
tags:
- ConflictService
summary: ListAcledEvents
description: ListAcledEvents retrieves ACLED armed-conflict events with country, location, actors, event type and fatalities, filterable by country and inclusive time range.
operationId: ListAcledEvents
parameters:
- name: start
in: query
description: Start of time range (inclusive), Unix epoch milliseconds.
required: false
example: "1717200000000"
schema:
type: string
format: int64
- name: end
in: query
description: End of time range (inclusive), Unix epoch milliseconds.
required: false
example: "1717200000000"
schema:
type: string
format: int64
- name: page_size
in: query
description: |-
Maximum items per page (1-100).
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: 25
schema:
type: integer
format: int32
- name: cursor
in: query
description: |-
Cursor for next page.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: "next-page-token"
schema:
type: string
- name: country
in: query
description: Optional country filter (ISO 3166-1 alpha-2).
required: false
example: "US"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"events":
- "actors":
- "example"
"admin1": "example"
"country": "US"
"eventType": "all"
"fatalities": 1
"id": "example-id"
"pagination":
"nextCursor": "next-page-token"
"totalCount": 1
schema:
$ref: '#/components/schemas/worldmonitor_conflict_v1_ListAcledEventsResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/conflict/v1/list-ucdp-events:
get:
tags:
- ConflictService
summary: ListUcdpEvents
description: Browse cached, georeferenced UCDP violence events with optional country filtering, event dates and fatality estimates for country-level conflict data analysis.
operationId: ListUcdpEvents
parameters:
- name: start
in: query
description: |-
Start of time range (inclusive), Unix epoch milliseconds.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: "1717200000000"
schema:
type: string
format: int64
- name: end
in: query
description: |-
End of time range (inclusive), Unix epoch milliseconds.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: "1717200000000"
schema:
type: string
format: int64
- name: page_size
in: query
description: |-
Maximum items per page (1-100).
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: 25
schema:
type: integer
format: int32
- name: cursor
in: query
description: |-
Cursor for next page.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: "next-page-token"
schema:
type: string
- name: country
in: query
description: Optional country filter (ISO 3166-1 alpha-2).
required: false
example: "US"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"candidateVersion": "2026-01-15"
"events":
- "country": "US"
"dateEnd": 1717200000000
"dateStart": 1717200000000
"deathsBest": 1
"deathsHigh": 1
"id": "example-id"
"pagination":
"nextCursor": "next-page-token"
"totalCount": 1
schema:
$ref: '#/components/schemas/worldmonitor_conflict_v1_ListUcdpEventsResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/conflict/v1/get-humanitarian-summary:
get:
tags:
- ConflictService
summary: GetHumanitarianSummary
description: Retrieve a cached HAPI conflict summary for a country, with event counts, fatalities, demonstrations, reference period and update time for humanitarian context.
operationId: GetHumanitarianSummary
parameters:
- name: country_code
in: query
description: ISO 3166-1 alpha-2 country code (e.g., "YE", "SD", "SO").
required: true
example: "AD"
schema:
type: string
enum:
- 'AD'
- 'AE'
- 'AF'
- 'AG'
- 'AI'
- 'AL'
- 'AM'
- 'AO'
- 'AQ'
- 'AR'
- 'AS'
- 'AT'
- 'AU'
- 'AW'
- 'AX'
- 'AZ'
- 'BA'
- 'BB'
- 'BD'
- 'BE'
- 'BF'
- 'BG'
- 'BH'
- 'BI'
- 'BJ'
- 'BL'
- 'BM'
- 'BN'
- 'BO'
- 'BR'
- 'BS'
- 'BT'
- 'BW'
- 'BY'
- 'BZ'
- 'CA'
- 'CD'
- 'CF'
- 'CG'
- 'CH'
- 'CI'
- 'CK'
- 'CL'
- 'CM'
- 'CN'
- 'CO'
- 'CR'
- 'CU'
- 'CV'
- 'CW'
- 'CY'
- 'CZ'
- 'DE'
- 'DJ'
- 'DK'
- 'DM'
- 'DO'
- 'DZ'
- 'EC'
- 'EE'
- 'EG'
- 'EH'
- 'ER'
- 'ES'
- 'ET'
- 'FI'
- 'FJ'
- 'FK'
- 'FM'
- 'FO'
- 'FR'
- 'GA'
- 'GB'
- 'GD'
- 'GE'
- 'GG'
- 'GH'
- 'GI'
- 'GL'
- 'GM'
- 'GN'
- 'GQ'
- 'GR'
- 'GS'
- 'GT'
- 'GU'
- 'GW'
- 'GY'
- 'HK'
- 'HM'
- 'HN'
- 'HR'
- 'HT'
- 'HU'
- 'ID'
- 'IE'
- 'IL'
- 'IM'
- 'IN'
- 'IO'
- 'IQ'
- 'IR'
- 'IS'
- 'IT'
- 'JE'
- 'JM'
- 'JO'
- 'JP'
- 'KE'
- 'KG'
- 'KH'
- 'KI'
- 'KM'
- 'KN'
- 'KP'
- 'KR'
- 'KW'
- 'KY'
- 'KZ'
- 'LA'
- 'LB'
- 'LC'
- 'LI'
- 'LK'
- 'LR'
- 'LS'
- 'LT'
- 'LU'
- 'LV'
- 'LY'
- 'MA'
- 'MC'
- 'MD'
- 'ME'
- 'MF'
- 'MG'
- 'MH'
- 'MK'
- 'ML'
- 'MM'
- 'MN'
- 'MO'
- 'MP'
- 'MR'
- 'MS'
- 'MT'
- 'MU'
- 'MV'
- 'MW'
- 'MX'
- 'MY'
- 'MZ'
- 'NA'
- 'NC'
- 'NE'
- 'NF'
- 'NG'
- 'NI'
- 'NL'
- 'NO'
- 'NP'
- 'NR'
- 'NU'
- 'NZ'
- 'OM'
- 'PA'
- 'PE'
- 'PF'
- 'PG'
- 'PH'
- 'PK'
- 'PL'
- 'PM'
- 'PN'
- 'PR'
- 'PS'
- 'PT'
- 'PW'
- 'PY'
- 'QA'
- 'RO'
- 'RS'
- 'RU'
- 'RW'
- 'SA'
- 'SB'
- 'SC'
- 'SD'
- 'SE'
- 'SG'
- 'SH'
- 'SI'
- 'SK'
- 'SL'
- 'SM'
- 'SN'
- 'SO'
- 'SR'
- 'SS'
- 'ST'
- 'SV'
- 'SX'
- 'SY'
- 'SZ'
- 'TC'
- 'TD'
- 'TF'
- 'TG'
- 'TH'
- 'TJ'
- 'TL'
- 'TM'
- 'TN'
- 'TO'
- 'TR'
- 'TT'
- 'TV'
- 'TW'
- 'TZ'
- 'UA'
- 'UG'
- 'UM'
- 'US'
- 'UY'
- 'UZ'
- 'VA'
- 'VC'
- 'VE'
- 'VG'
- 'VI'
- 'VN'
- 'VU'
- 'WF'
- 'WS'
- 'XK'
- 'YE'
- 'ZA'
- 'ZM'
- 'ZW'
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"summary":
"conflictDemonstrations": 42
"conflictEventsTotal": 1
"conflictFatalities": 1
"conflictPoliticalViolenceEvents": 1
"countryCode": "US"
schema:
$ref: '#/components/schemas/worldmonitor_conflict_v1_GetHumanitarianSummaryResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/conflict/v1/list-iran-events:
get:
tags:
- ConflictService
summary: ListIranEvents
description: ListIranEvents is disabled by default; enable IRAN_EVENTS_ENABLED to return cached LiveUAMap Iran conflict records, otherwise an empty list with scrapedAt zero.
operationId: ListIranEvents
parameters:
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"events":
- "category": "cs.AI"
"id": "example-id"
"latitude": 40.7128
"locationName": "WorldMonitor Analyst"
"longitude": -74.006
"scrapedAt": "1717200000000"
schema:
$ref: '#/components/schemas/worldmonitor_conflict_v1_ListIranEventsResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/conflict/v1/get-humanitarian-summary-batch:
post:
parameters:
- name: Idempotency-Key
in: header
description: 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: false
example: "4f8b9c2e-1a3d-4b6f-8e0a-2c5d7f9b1e34"
schema:
type: string
minLength: 1
maxLength: 255
pattern: "^[\\x21-\\x7E]{1,255}$"
tags:
- ConflictService
summary: GetHumanitarianSummaryBatch
description: Retrieve humanitarian summaries for multiple countries in one request, with country indicators and requested versus fetched counts for coverage comparison.
operationId: GetHumanitarianSummaryBatch
requestBody:
content:
application/json:
example:
"countryCodes":
- "US"
schema:
$ref: '#/components/schemas/worldmonitor_conflict_v1_GetHumanitarianSummaryBatchRequest'
required: true
responses:
"200":
description: Successful response
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key echoed from the request. Present only when the client opted into idempotency.
Idempotent-Replayed:
schema:
type: boolean
description: true when this response was replayed from an earlier request with the same key, false on the first (original) request. Present only when the client opted into idempotency.
content:
application/json:
example:
"fetched": 1
"requested": 1
"results":
"exampleKey":
"conflictDemonstrations": 42
"conflictEventsTotal": 1
"conflictFatalities": 1
"conflictPoliticalViolenceEvents": 1
"countryCode": "US"
schema:
$ref: '#/components/schemas/worldmonitor_conflict_v1_GetHumanitarianSummaryBatchResponse'
"400":
description: Validation error, invalid Idempotency-Key header, or malformed JSON request body
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
- $ref: '#/components/schemas/InvalidRequestBodyError'
"409":
description: A request with this Idempotency-Key is still being processed
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key supplied by the client.
Retry-After:
schema:
type: string
description: Seconds to wait before retrying the in-flight request.
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
"422":
description: The Idempotency-Key was already used with a different request body
headers:
Idempotency-Key:
schema:
type: string
description: The idempotency key supplied by the client.
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/consumer-prices/v1/get-consumer-price-overview:
get:
tags:
- ConsumerPricesService
summary: GetConsumerPriceOverview
description: GetConsumerPriceOverview returns essentials and value basket indices, week and month changes, retailer spread and coverage for one of 10 scraped markets.
operationId: GetConsumerPriceOverview
parameters:
- name: market_code
in: query
description: market_code is the ISO 3166-1 alpha-2 market identifier (e.g. "ae").
required: false
example: "US"
schema:
type: string
- name: basket_slug
in: query
description: basket_slug selects which basket to use (e.g. "essentials-ae").
required: false
example: "essentials-ae"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"asOf": "1717200000000"
"coveragePct": 1.5
"currencyCode": "USD"
"essentialsIndex": 1.5
"freshnessLagMin": 1
schema:
$ref: '#/components/schemas/worldmonitor_consumer_prices_v1_GetConsumerPriceOverviewResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/consumer-prices/v1/get-consumer-price-basket-series:
get:
tags:
- ConsumerPricesService
summary: GetConsumerPriceBasketSeries
description: Retrieve consumer price basket index history by market, basket and date range, with dated observations, currency and snapshot time for price trend analysis.
operationId: GetConsumerPriceBasketSeries
parameters:
- name: market_code
in: query
description: market_code is the ISO 3166-1 alpha-2 market identifier.
required: false
example: "ae"
schema:
type: string
pattern: '^([A-Za-z]{2})?$'
- name: basket_slug
in: query
description: basket_slug selects the basket (e.g. "essentials-ae").
required: false
example: "essentials-ae"
schema:
type: string
pattern: '^([Ee][Ss][Ss][Ee][Nn][Tt][Ii][Aa][Ll][Ss]-[A-Za-z]{2})?$'
- name: range
in: query
description: range is one of "7d", "30d", "90d". Unsupported values use "30d".
required: false
example: "7d"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"asOf": "1717200000000"
"basketSlug": "essentials-ae"
"currencyCode": "AED"
"essentialsSeries":
- "date": "2026-01-15"
"index": 1.5
"marketCode": "ae"
schema:
$ref: '#/components/schemas/worldmonitor_consumer_prices_v1_GetConsumerPriceBasketSeriesResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: API access requires an active subscription (the API key's subscription is inactive or expired).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/consumer-prices/v1/list-consumer-price-categories:
get:
tags:
- ConsumerPricesService
summary: ListConsumerPriceCategories
description: ListConsumerPriceCategories returns per-category price indices with week and month changes, sparklines and coverage for a market over a 7d, 30d or 90d range.
operationId: ListConsumerPriceCategories
parameters:
- name: market_code
in: query
description: market_code is the ISO 3166-1 alpha-2 market identifier.
required: false
example: "US"
schema:
type: string
- name: basket_slug
in: query
description: basket_slug selects the basket scope.
required: false
example: "essentials-ae"
schema:
type: string
- name: range
in: query
description: range is one of "7d", "30d", "90d". Unsupported values use "30d".
required: false
example: "7d"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 byte