docs/api/EconomicService.openapi.yaml
Rama main · réplica de lectura del repositorio original.
openapi: 3.1.0
info:
title: EconomicService API
version: 1.0.0
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
servers:
- url: https://api.worldmonitor.app
paths:
/api/economic/v1/get-fred-series:
get:
tags:
- EconomicService
summary: GetFredSeries
description: Retrieve a Federal Reserve Economic Data series by ID, with an observation limit, dated values, title, units and frequency for economic time-series analysis.
operationId: GetFredSeries
parameters:
- name: series_id
in: query
description: 'FRED series ID. Supported values: "BAMLC0A0CM", "BAMLH0A0HYM2", "CPIAUCSL", "DCOILWTICO", "DGS1", "DGS10", "DGS1MO", "DGS2", "DGS30", "DGS3MO", "DGS5", "DGS6MO", "ESTR", "EURIBOR1Y", "EURIBOR3M", "EURIBOR6M", "FEDFUNDS", "GDP", "GSCPI", "ICSA", "M2SL", "MORTGAGE30US", "SOFR", "STLFSI4", "T10Y2Y", "T10Y3M", "UNRATE", "VIXCLS", "WALCL".'
required: true
example: "BAMLC0A0CM"
schema:
type: string
enum:
- 'BAMLC0A0CM'
- 'BAMLH0A0HYM2'
- 'CPIAUCSL'
- 'DCOILWTICO'
- 'DGS1'
- 'DGS10'
- 'DGS1MO'
- 'DGS2'
- 'DGS30'
- 'DGS3MO'
- 'DGS5'
- 'DGS6MO'
- 'ESTR'
- 'EURIBOR1Y'
- 'EURIBOR3M'
- 'EURIBOR6M'
- 'FEDFUNDS'
- 'GDP'
- 'GSCPI'
- 'ICSA'
- 'M2SL'
- 'MORTGAGE30US'
- 'SOFR'
- 'STLFSI4'
- 'T10Y2Y'
- 'T10Y3M'
- 'UNRATE'
- 'VIXCLS'
- 'WALCL'
- name: limit
in: query
description: Maximum number of observations to return. Defaults to 120.
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:
"series":
"frequency": "example"
"observations":
- "date": "2026-01-15"
"value": 1.5
"seriesId": "GDP"
"title": "example"
"units": "example"
schema:
$ref: '#/components/schemas/GetFredSeriesResponse'
"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/economic/v1/list-world-bank-indicators:
get:
tags:
- EconomicService
summary: ListWorldBankIndicators
description: Retrieve World Bank development indicators with country filters, country names, indicator codes and annual values for economic and development data analysis.
operationId: ListWorldBankIndicators
parameters:
- name: indicator_code
in: query
description: World Bank indicator code (e.g., "NY.GDP.MKTP.CD").
required: true
example: "NY.GDP.MKTP.CD"
schema:
type: string
- name: country_code
in: query
description: Optional country filter (ISO 3166-1 alpha-2).
required: false
example: "US"
schema:
type: string
- name: year
in: query
description: Optional year filter. Defaults to latest available.
required: false
example: 1
schema:
type: integer
format: int32
- name: page_size
in: query
description: |-
Maximum items per page.
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: 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":
- "countryCode": "US"
"countryName": "US"
"indicatorCode": "NY.GDP.MKTP.CD"
"indicatorName": "WorldMonitor Analyst"
"value": 1.5
"year": 1
"pagination":
"nextCursor": "next-page-token"
"totalCount": 1
schema:
$ref: '#/components/schemas/ListWorldBankIndicatorsResponse'
"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/economic/v1/get-energy-prices:
get:
tags:
- EconomicService
summary: GetEnergyPrices
description: Retrieve current EIA energy commodity prices for selected commodities, with names, units, price changes and observation times for energy market monitoring.
operationId: GetEnergyPrices
parameters:
- name: commodities
in: query
description: Optional commodity filter. Empty returns all tracked commodities.
required: false
style: form
explode: true
example:
- "example"
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:
"prices":
- "change": 1.5
"commodity": "example"
"frequency": "example"
"name": "WorldMonitor Analyst"
"price": 75.25
"priceAt": 1717200000000
schema:
$ref: '#/components/schemas/GetEnergyPricesResponse'
"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/economic/v1/get-macro-signals:
get:
tags:
- EconomicService
summary: GetMacroSignals
description: Review seven macro signals with bullish counts and BUY, CASH or UNKNOWN verdicts; unavailable cached data returns UNKNOWN to keep missing evidence explicit.
operationId: GetMacroSignals
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:
"bullishCount": 1
"meta":
"qqqSparkline":
- 1.5
"signals":
"fearGreed":
"history":
- "date": "2026-01-15"
"value": 1
"status": "example"
"value": 1
"flowStructure":
"btcReturn5": 1.5
"qqqReturn5": 1.5
"status": "example"
"hashRate":
"change30d": 1.5
"status": "example"
"liquidity":
"sparkline":
- 1.5
"status": "example"
"value": 1.5
"macroRegime":
"qqqRoc20": 1.5
"status": "example"
"xlpRoc20": 1.5
"timestamp": "2026-01-15T12:00:00Z"
"totalCount": 1
schema:
$ref: '#/components/schemas/GetMacroSignalsResponse'
"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/economic/v1/get-china-macro-snapshot:
get:
tags:
- EconomicService
summary: GetChinaMacroSnapshot
description: |-
GetChinaMacroSnapshot reads the normalized China macro and official release
calendar seeds. It never fans out to upstream providers on a cache miss.
operationId: GetChinaMacroSnapshot
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:
"contentObservationDate": "2026-01-15"
"countryCode": "US"
"generatedAt": "2026-01-15T12:00:00Z"
"indicators":
- "category": "cs.AI"
"comparisonBasis": "example"
"comparisonValue": 1.5
"contextOnly": true
"direction": "example"
"latestObservationDate": "2026-01-15"
schema:
$ref: '#/components/schemas/GetChinaMacroSnapshotResponse'
"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/economic/v1/get-china-activity-nowcast:
get:
tags:
- EconomicService
summary: GetChinaActivityNowcast
description: |-
GetChinaActivityNowcast compares the revision-aware official macro pulse
with reviewed proxy families using a deterministic, no-lookahead method.
operationId: GetChinaActivityNowcast
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:
"comparisonState": "example"
"generatedAt": "2026-01-15T12:00:00Z"
"methodVersion": "example"
"payloadJson": "example"
"upstreamUnavailable": false
schema:
$ref: '#/components/schemas/GetChinaActivityNowcastResponse'
"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/economic/v1/get-no2-activity:
get:
tags:
- EconomicService
summary: GetNo2Activity
description: GetNo2Activity returns Sentinel-5P NO2 year-over-year activity direction for 167 countries and 32 industrial clusters, filterable by country, region and kind.
operationId: GetNo2Activity
parameters:
- name: country_code
in: query
description: 'ISO 3166-1 alpha-2: the country plus its clusters.'
required: false
example: "US"
schema:
type: string
pattern: '^([A-Za-z]{2})?$'
- name: region_id
in: query
description: Registry id, e.g. "yangtze-river-delta".
required: false
example: "yangtze-river-delta"
schema:
type: string
pattern: '^([a-z0-9-]{1,64})?$'
- name: kind
in: query
description: Countries, clusters, or both when unspecified.
required: false
example: "NO2_REGION_KIND_COUNTRY"
schema:
type: string
enum:
- 'NO2_REGION_KIND_COUNTRY'
- 'NO2_REGION_KIND_CLUSTER'
- 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:
"attribution": "example"
"generatedAt": "2026-01-15T12:00:00Z"
"methodVersion": "example"
"regions":
- "baselineMeanNo2MolM2": 1.5
"baselineYears":
- 1
"bbox":
- 1.5
"changePercent": 42.5
"countryCode": "US"
"stale": true
schema:
$ref: '#/components/schemas/GetNo2ActivityResponse'
"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/economic/v1/get-energy-capacity:
get:
tags:
- EconomicService
summary: GetEnergyCapacity
description: Retrieve cached EIA installed capacity series by energy source, with annual megawatt values for comparing available solar, wind and coal generation capacity.
operationId: GetEnergyCapacity
parameters:
- name: energy_sources
in: query
description: |-
Energy source codes to query (e.g., "SUN", "WND", "COL").
Empty returns all tracked sources (SUN, WND, COL).
required: false
style: form
explode: true
example:
- "example"
schema:
type: array
items:
type: string
- name: years
in: query
description: |-
Number of years of historical data. Default 20 if not set.
Accepted but currently ignored; no-op until this handler supports the parameter.
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:
"series":
- "data":
- "capacityMw": 1.5
"year": 1
"energySource": "example"
"name": "WorldMonitor Analyst"
schema:
$ref: '#/components/schemas/GetEnergyCapacityResponse'
"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/economic/v1/get-bis-policy-rates:
get:
tags:
- EconomicService
summary: GetBisPolicyRates
description: Retrieve BIS central bank policy rates with country, central bank, observation date and previous rate for comparing monetary policy across available countries.
operationId: GetBisPolicyRates
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:
"rates":
- "centralBank": "example"
"countryCode": "US"
"countryName": "US"
"date": "2026-01-15"
"previousRate": 75.25
schema:
$ref: '#/components/schemas/GetBisPolicyRatesResponse'
"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/economic/v1/get-bis-exchange-rates:
get:
tags:
- EconomicService
summary: GetBisExchangeRates
description: GetBisExchangeRates retrieves the latest monthly real effective exchange rate from BIS WS_EER, with monthly change, for 12 economies including the euro area.
operationId: GetBisExchangeRates
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:
"rates":
- "countryCode": "US"
"countryName": "US"
"date": "2026-01-15"
"nominalEer": 1.5
"realChange": 1.5
schema:
$ref: '#/components/schemas/GetBisExchangeRatesResponse'
"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/economic/v1/get-bis-credit:
get:
tags:
- EconomicService
summary: GetBisCredit
description: GetBisCredit retrieves the latest quarterly credit-to-GDP ratio and prior quarter from BIS WS_TC for 12 economies, including the US, euro area and China.
operationId: GetBisCredit
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:
"entries":
- "countryCode": "US"
"countryName": "US"
"creditGdpRatio": 42.5
"date": "2026-01-15"
"previousRatio": 42.5
schema:
$ref: '#/components/schemas/GetBisCreditResponse'
"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/economic/v1/get-fred-series-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:
- EconomicService
summary: GetFredSeriesBatch
description: Retrieve multiple Federal Reserve Economic Data series in one request, with dated observations and series metadata, plus requested and fetched result counts.
operationId: GetFredSeriesBatch
requestBody:
content:
application/json:
example:
"limit": 25
"seriesIds":
- "GDP"
schema:
$ref: '#/components/schemas/GetFredSeriesBatchRequest'
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":
"frequency": "example"
"observations":
- "date": "2026-01-15"
"value": 1.5
"seriesId": "GDP"
"title": "example"
"units": "example"
schema:
$ref: '#/components/schemas/GetFredSeriesBatchResponse'
"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/economic/v1/list-grocery-basket-prices:
get:
tags:
- EconomicService
summary: ListGroceryBasketPrices
description: ListGroceryBasketPrices compares the weekly USD cost of a 10-item grocery basket (rice, eggs, milk, bread and more) across 24 countries, with weekly change.
operationId: ListGroceryBasketPrices
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:
"cheapestCountry": "US"
"countries":
- "code": "example"
"currency": "USD"
"flag": "example"
"fxRate": 75.25
"items":
- "available": true
"currency": "USD"
"itemId": "example-id"
"itemName": "WorldMonitor Analyst"
"localPrice": 75.25
"fetchedAt": "2026-01-15T12:00:00Z"
"mostExpensiveCountry": "US"
"prevFetchedAt": "2026-01-15T12:00:00Z"
schema:
$ref: '#/components/schemas/ListGroceryBasketPricesResponse'
"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/economic/v1/list-bigmac-prices:
get:
tags:
- EconomicService
summary: ListBigMacPrices
description: ListBigMacPrices retrieves weekly Big Mac prices in local currency and USD for 49 countries via Exa web search, with cheapest, priciest and weekly change.
operationId: ListBigMacPrices
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:
"cheapestCountry": "US"
"countries":
- "available": true
"code": "example"
"currency": "USD"
"flag": "example"
"fxRate": 75.25
"fetchedAt": "2026-01-15T12:00:00Z"
"mostExpensiveCountry": "US"
"prevFetchedAt": "2026-01-15T12:00:00Z"
schema:
$ref: '#/components/schemas/ListBigMacPricesResponse'
"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/economic/v1/get-national-debt:
get:
tags:
- EconomicService
summary: GetNationalDebt
description: GetNationalDebt estimates government debt in USD by country from IMF WEO debt-to-GDP and GDP with a deficit-based growth rate; US uses Treasury debt data.
operationId: GetNationalDebt
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:
"entries":
- "annualGrowth": 1.5
"baselineTs": "1717200000000"
"debtToGdp": 1.5
"debtUsd": 1.5
"gdpUsd": 1.5
"seededAt": "2026-01-15T12:00:00Z"
"unavailable": false
schema:
$ref: '#/components/schemas/GetNationalDebtResponse'
"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/economic/v1/list-fuel-prices:
get:
tags:
- EconomicService
summary: ListFuelPrices
description: ListFuelPrices retrieves weekly retail gasoline and diesel prices in USD for 30+ countries from official sources such as the EU Oil Bulletin and US EIA.
operationId: ListFuelPrices
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:
"cheapestDiesel": "example"
"cheapestGasoline": "example"
"countries":
- "code": "example"
"currency": "USD"
"diesel":
"available": true
"grade": "example"
"localPrice": 75.25
"observedAt": "2026-01-15T12:00:00Z"
"source": "example"
"flag": "example"
"fxRate": 75.25
"countryCount": 1
"fetchedAt": "2026-01-15T12:00:00Z"
schema:
$ref: '#/components/schemas/ListFuelPricesResponse'
"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/economic/v1/get-bls-series:
get:
tags:
- EconomicService
summary: GetBlsSeries
description: GetBlsSeries returns a BLS labor series, private nonfarm payrolls (USPRIV) or the employment cost index (ECIALLCIV), mirrored from FRED with recent history.
operationId: GetBlsSeries
parameters:
- name: series_id
in: query
description: 'BLS/FRED-backed series ID. Supported values: "USPRIV", "ECIALLCIV".'
required: false
example: "USPRIV"
schema:
type: string
enum:
- 'USPRIV'
- 'ECIALLCIV'
- name: limit
in: query
description: Maximum number of observations to return. Defaults to 60.
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:
"series":
"observations":
- "period": "daily"
"periodName": "daily"
"value": "example"
"year": "example"
"seriesId": "example-id"
"title": "example"
"units": "example"
schema:
$ref: '#/components/schemas/GetBlsSeriesResponse'
"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/economic/v1/get-economic-calendar:
get:
tags:
- EconomicService
summary: GetEconomicCalendar
description: GetEconomicCalendar returns scheduled FOMC and ECB rate decisions, US CPI, payrolls, GDP, PCE and retail sales, and Eurostat releases, filtered by date range.
operationId: GetEconomicCalendar
parameters:
- name: fromDate
in: query
description: Inclusive lower date bound in YYYY-MM-DD format.
required: false
example: "2026-01-15"
schema:
type: string
- name: toDate
in: query
description: Inclusive upper date bound in YYYY-MM-DD format.
required: false
example: "2026-01-15"
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": "example"
"events":
- "actual": "example"
"country": "US"
"date": "2026-01-15"
"estimate": "example"
"event": "example"
"fromDate": "2026-01-15"
"toDate": "2026-01-15"
"total": 1
schema:
$ref: '#/components/schemas/GetEconomicCalendarResponse'
"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/economic/v1/get-crude-inventories:
get:
tags:
- EconomicService
summary: GetCrudeInventories
description: GetCrudeInventories retrieves the 8 most recent weeks of US commercial crude oil inventories excluding the SPR (EIA series WCESTUS1) with the latest period.
operationId: GetCrudeInventories
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:
"latestPeriod": "daily"
"weeks":
- "period": "daily"
"stocksMb": 1.5
"weeklyChangeMb": 1.5
schema:
$ref: '#/components/schemas/GetCrudeInventoriesResponse'
"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/economic/v1/get-nat-gas-storage:
get:
tags:
- EconomicService
summary: GetNatGasStorage
description: GetNatGasStorage retrieves the 8 most recent weeks of US natural gas working gas storage from EIA (NW2_EPG0_SWO_R48_BCF).
operationId: GetNatGasStorage
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:
"latestPeriod": "daily"
"weeks":
- "period": "daily"
"storBcf": 1.5
"weeklyChangeBcf": 1.5
schema:
$ref: '#/components/schemas/GetNatGasStorageResponse'
"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/economic/v1/get-ecb-fx-rates:
get:
tags:
- EconomicService
summary: GetEcbFxRates
description: Retrieve daily ECB reference exchange rates for the euro against major currencies, with one-day changes, dates and availability status for currency analysis.
operationId: GetEcbFxRates
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:
"rates":
- "change1d": 1.5
"date": "2026-01-15"
"pair": "example"
"rate": 75.25
"seededAt": "1717200000000"
"unavailable": false
"updatedAt": "2026-01-15"
schema:
$ref: '#/components/schemas/GetEcbFxRatesResponse'
"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/economic/v1/get-eurostat-country-data:
get:
tags:
- EconomicService
summary: GetEurostatCountryData
description: GetEurostatCountryData retrieves HICP inflation, unemployment and quarterly GDP growth from Eurostat for 10 EU member states, including Germany and France.
operationId: GetEurostatCountryData
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:
"countries":
"exampleKey":
"cpi":
"date": "2026-01-15"
"hasPrior": true
"priorValue": 1.5
"unit": "example"
"value": 1.5
"gdpGrowth":
"date": "2026-01-15"
"hasPrior": true
"priorValue": 1.5
"unit": "example"
"value": 1.5
"unemployment":
"date": "2026-01-15"
"hasPrior": true
"priorValue": 1.5
"unit": "example"
"value": 1.5
"seededAt": "1717200000000"
"unavailable": false
schema:
$ref: '#/components/schemas/GetEurostatCountryDataResponse'
"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/economic/v1/get-eu-gas-storage:
get:
tags:
- EconomicService
summary: GetEuGasStorage
description: GetEuGasStorage returns EU gas storage fill % from GIE AGSI+, with day-over-day change, injection or withdrawal trend, and up to five days of history.
operationId: GetEuGasStorage
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:
"fillPct": 1.5
"fillPctChange1d": 1.5
"gasDaysConsumption": 7
"history":
- "date": "2026-01-15"
"fillPct": 1.5
"gasTwh": 1.5
"seededAt": "1717200000000"
schema:
$ref: '#/components/schemas/GetEuGasStorageResponse'
"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/economic/v1/get-eu-yield-curve:
get:
tags:
- EconomicService
summary: GetEuYieldCurve
description: GetEuYieldCurve retrieves the latest ECB euro area AAA government bond yield curve (Svensson spot rates) at the 1Y, 2Y, 5Y, 10Y, 20Y and 30Y tenors.
operationId: GetEuYieldCurve
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":
"date": "2026-01-15"
"rates":
"exampleKey": 1.5
"source": "example"
"updatedAt": "2026-01-15"
"unavailable": false
schema:
$ref: '#/components/schemas/GetEuYieldCurveResponse'
"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/economic/v1/get-eu-fsi:
get:
tags:
- EconomicService
summary: GetEuFsi
description: 'GetEuFsi retrieves the ECB Composite Indicator of Systemic Stress (CISS) for the euro area: latest daily value, a year of daily history and a staleness flag.'
operationId: GetEuFsi
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:
"history":
- "date": "2026-01-15"
"value": 1.5
"label": "example"
"latestDate": "2026-01-15"
"latestValue": 1.5
"seededAt": "2026-01-15T12:00:00Z"
schema:
$ref: '#/components/schemas/GetEuFsiResponse'
"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/economic/v1/get-economic-stress:
get:
tags:
- EconomicService
summary: GetEconomicStress
description: Review the Economic Stress Index from six FRED series, with its 0-100 composite score, component readings, missing-data flags and snapshot time for context.
operationId: GetEconomicStress
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:
"components":
- "id": "example-id"
"label": "example"
"missing": true
"rawValue": 1.5
"score": 42.5
"compositeScore": 42.5
"label": "example"
"seededAt": "2026-01-15T12:00:00Z"
"unavailable": false
schema:
$ref: '#/components/schemas/GetEconomicStressResponse'
"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/economic/v1/get-fao-food-price-index:
get:
tags:
- EconomicService
summary: GetFaoFoodPriceIndex
description: GetFaoFoodPriceIndex retrieves 12 months of the FAO Food Price Index with meat, dairy, cereals, oils and sugar sub-indices, plus monthly and annual change.
operationId: GetFaoFoodPriceIndex
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:
"currentFfpi": 1.5
"fetchedAt": "2026-01-15T12:00:00Z"
"momPct": 1.5
"points":
- "cereals": 1.5
"dairy": 1.5
"date": "2026-01-15"
"ffpi": 1.5
"meat": 1717200000000
"yoyPct": 1.5
schema:
$ref: '#/components/schemas/GetFaoFoodPriceIndexResponse'
"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/economic/v1/get-food-prices:
get:
tags:
- EconomicService
summary: GetFoodPrices
description: GetFoodPrices returns local-currency market prices with exact prior-week comparisons, plus dated GIEWS and Tunisia context. Missing comparisons are explicitly unavailable. Market, market type, product, origin, unit and currency must match; levels are not comparable across countries.
operationId: GetFoodPrices
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:
"sources":
- "attribution": "example"
"cadence": "example"
"contextOnly": true
"contexts":
- "country": "US"
"countryCode": "US"
"fetchedAt": "2026-01-15T12:00:00Z"
"referenceDate": "2026-01-15"
"status": "example"
"country": "US"
"unavailable": false
schema:
$ref: '#/components/schemas/GetFoodPricesResponse'
"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/economic/v1/get-oil-stocks-analysis:
get:
tags:
- EconomicService
summary: GetOilStocksAnalysis
description: GetOilStocksAnalysis ranks IEA members by oil stock days of net-import cover against the 90-day obligation, with Europe, Asia-Pacific and North America data.
operationId: GetOilStocksAnalysis
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:
"belowObligation":
- "example"
"dataMonth": "example"
"ieaMembers":
- "belowObligation": true
"daysOfCover": 7
"iso2": "US"
"netExporter": true
"obligationMet": true
"regionalSummary":
"asiaPacific":
"avgDays": 7
"countBelowObligation": 1
"minDays": 7
"europe":
"avgDays": 7
"countBelowObligation": 1
"minDays": 7
"northAmerica":
"avgDays": 7
"netExporters": 1
"unavailable": false
schema:
$ref: '#/components/schemas/GetOilStocksAnalysisResponse'
"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/economic/v1/get-oil-inventories:
get:
tags:
- EconomicService
summary: GetOilInventories
description: 'GetOilInventories returns recent oil-inventory series: US crude weeks, the SPR snapshot, natural-gas weeks, EU gas storage, and IEA stocks.'
operationId: GetOilInventories
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:
"crudeWeeks":
- "period": "daily"
"stocksMb": 1.5
"weeklyChangeMb": 1.5
"euGas":
"fillPct": 1.5
"fillPctChange1d": 1.5
"history":
- "date": "2026-01-15"
"fillPct": 1.5
"trend": "example"
"ieaStocks":
"asiaPacific":
"avgDays": 7
"countBelowObligation": 1
"minDays": 7
"dataMonth": "example"
"europe":
"avgDays": 7
"countBelowObligation": 1
"minDays": 7
"members":
- "belowObligation": true
"daysOfCover": 7
"iso2": "US"
"netExporter": true
"northAmerica":
"avgDays": 7
"countBelowObligation": 1
"minDays": 7
"natGasWeeks":
- "period": "daily"
"storBcf": 1.5
"weeklyChangeBcf": 1.5
"refinery":
"inputsMbpd": 1.5
"period": "daily"
schema:
$ref: '#/components/schemas/GetOilInventoriesResponse'
"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/economic/v1/get-energy-crisis-policies:
get:
tags:
- EconomicService
summary: GetEnergyCrisisPolicies
description: GetEnergyCrisisPolicies retrieves government responses to the 2026 energy crisis from the IEA policy tracker, filterable by country code and policy category.
operationId: GetEnergyCrisisPolicies
parameters:
- name: country_code
in: query
description: Optional ISO-2 country code filter.
required: false
example: "US"
schema:
type: string
- name: category
in: query
description: 'Optional category filter: "conservation" or "consumer_support".'
required: false
example: "cs.AI"
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:
"context": "example"
"policies":
- "category": "cs.AI"
"country": "US"
"countryCode": "US"
"dateAnnounced": "2026-01-15"
"measure": "example"
"source": "example"
"sourceUrl": "https://example.com/worldmonitor"
"unavailable": false
schema:
$ref: '#/components/schemas/GetEnergyCrisisPoliciesResponse'
"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/economic/v1/list-global-tenders:
get:
tags:
- EconomicService
summary: ListGlobalTenders
description: ListGlobalTenders returns the Pro-gated, paginated, seed-backed canonical procurement feed. Requires entitlement tier >= 1.
operationId: ListGlobalTenders
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: country
in: query
description: ISO 3166-1 alpha-2 country code to match.
required: false
example: "US"
schema:
type: string
- name: countries
in: query
description: One or more ISO 3166-1 alpha-2 country codes to match.
required: false
style: form
explode: true
example:
- "US"
schema:
type: array
items:
type: string
- name: region
in: query
description: Geographic region label to match, such as Europe or North America.
required: false
example: "example"
schema:
type: string
- name: source
in: query
description: 'Source adapter identifier: sam, ted, contracts-finder, canada-buys, gets, or world-bank.'
required: false
example: "example"
schema:
type: string
- name: status
in: query
description: Source-provided tender status to match, such as open or published.
required: false
example: "example"
schema:
type: string
- name: deadline_from
in: query
description: Include opportunities whose deadline is on or after this ISO-8601 timestamp.
required: false
example: "example"
schema:
type: string
- name: deadline_to
in: query
description: Include opportunities whose deadline is on or before this ISO-8601 timestamp.
required: false
example: "example"
schema:
type: string
- name: min_value
in: query
description: Include opportunities with a stated estimated value at or above this amount.
required: false
example: 1.5
schema:
type: number
format: double
- name: max_value
in: query
description: Include opportunities with a stated estimated value at or below this amount.
required: false
example: 1.5
schema:
type: number
format: double
- name: currency
in: query
description: ISO 4217 currency code used with min_value and max_value.
required: false
example: "USD"
schema:
type: string
- name: category
in: query
description: Procurement category or classification code to match.
required: false
example: "cs.AI"
schema:
type: string
- name: query
in: query
description: Case-insensitive search text matched against tender titles and descriptions.
required: false
example: "supply chain risk"
schema:
type: string
- name: page_size
in: query
description: Maximum number of tenders to return per page; capped at 100.
required: false
example: 25
schema:
type: integer
format: int32
- name: cursor
in: query
description: Opaque cursor from a previous response's next_cursor field.
required: false
example: "next-page-token"
schema:
type: string
- name: sort
in: query
description: 'Result ordering: newest, closing_soon, estimated_value, or relevance.'
required: false
example: "example"
schema:
type: string
- name: buyer
in: query
description: Case-insensitive buyer or contracting-authority text to match.
required: false
example: "example"
schema:
type: string
- name: published_from
in: query
description: Include opportunities published on or after this ISO-8601 timestamp.
required: false
example: "example"
schema:
type: string
- name: published_to
in: query
description: Include opportunities published on or before this ISO-8601 timestamp.
required: false
example: "example"
schema:
type: string
- name: min_automation_score
in: query
description: |-
Include only opportunities whose keyword-based automation_fit score is at
or above this integer value (1-100; values above 100 are clamped, and
non-integer or non-positive values disable the filter). Disabled when 0
or unset, which preserves the default all-open-opportunities behavior.
This is an evidence-backed text-relevance threshold only; it does not
assert that any party is eligible to bid.
required: false
example: 42
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:
"appliedFilters":
- "example"
"availability": "example"
"countryCoverage": "US"
"dataAvailable": true
"fetchedAt": "2026-01-15T12:00:00Z"
schema:
$ref: '#/components/schemas/ListGlobalTendersResponse'
"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 entitlement access denied.
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/economic/v1/get-us-cpi-monthly:
get:
tags:
- EconomicService
summary: GetUsCpiMonthly
description: GetUsCpiMonthly returns seasonally adjusted US CPI-U for headline, core, food, energy, shelter, and services. Month-over-month and year-over-year changes are computed from that index. history=false is the latest month. history=true is every month from 1947.
operationId: GetUsCpiMonthly
parameters:
- name: history
in: query
description: When true, return every stored month. When false, return only the latest month.
required: false
example: true
schema:
type: boolean
- name: limit
in: query
description: Maximum recent observations per series, up to 366. Omit or use zero for the full stored history.
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:
"months":
- "core":
"index": 1.5
"monthOverMonth":
"percent": 42.5
"yearOverYear":
"percent": 42.5
"energy":
"index": 1.5
"monthOverMonth":
"percent": 42.5
"yearOverYear":
"percent": 42.5
"food":
"index": 1.5
"monthOverMonth":
"percent": 42.5
"yearOverYear":
"percent": 42.5
"headline":
"index": 1.5
"monthOverMonth":
"percent": 42.5
"yearOverYear":
"percent": 42.5
"month": 1717200000000
"unavailable": false
schema:
$ref: '#/components/schemas/GetUsCpiMonthlyResponse'
"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/economic/v1/get-us-treasury-par-yield-curve:
get:
tags:
- EconomicService
summary: GetUsTreasuryParYieldCurve
description: GetUsTreasuryParYieldCurve returns the daily Treasury par yield curve, 1-month through 30-year. A missing tenor was not published that day. history=false is the latest business day. history=true is every business day since 1990.
operationId: GetUsTreasuryParYieldCurve
parameters:
- name: history
in: query
description: When true, return every stored business day since 1990. When false, return the latest day.
required: false
example: true
schema:
type: boolean
- name: limit
in: query
description: Maximum recent observations per series, up to 366. Omit or use zero for the full stored history.
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:
"curves":
- "date": 1717200000000
"fiveYear": 1.5
"fourMonth": 1.5
"oneAndAHalfMonth": 1.5
"oneMonth": 1.5
"unavailable": false
schema:
$ref: '#/components/schemas/GetUsTreasuryParYieldCurveResponse'
"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/economic/v1/get-us-interest-rates:
get:
tags:
- EconomicService
summary: GetUsInterestRates
description: GetUsInterestRates returns the effective federal funds rate, target range, H.15 Treasury yields, and SOFR. history=false is the latest point of each series. history=true is the full history. This is not the Treasury par curve.
operationId: GetUsInterestRates
parameters:
- name: history
in: query
description: When true, return every stored observation. When false, return the latest point of each series.
required: false
example: true
schema:
type: boolean
- name: limit
in: query
description: Maximum recent observations per series, up to 366. Omit or use zero for the full stored history.
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:
"series":
- "id": "fed_funds_effective"
"points":
- "date": 1717200000000
"percent": 42.5
"unavailable": false
schema:
$ref: '#/components/schemas/GetUsInterestRatesResponse'
"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/economic/v1/get-capital-flows:
get:
tags:
- EconomicService
summary: GetCapitalFlows
description: 'GetCapitalFlows returns where money enters and leaves about 230 economies, and between any two, from official statistics. Per country: IMF balance-of-payments gross inflows and outflows by FDI, portfolio and other investment (quarterly where reported, annual otherwise) with derived Forbes and Warnock surge, stop, flight and retrenchment states; BIS cross-border deposits and borrowing of non-bank residents; IMF portfolio holdings of the country''s securities; and IMF direct-investment positions. With country and counterpart: both directions of the pair across bank deposits and lending (with eight quarters of adjusted flows), portfolio holdings and direct investment (with both sides'' figures), each leg marked reported, not_itemized or not_published. A person changing residence is not a balance-of-payments flow, so wealth migration does not appear.'
operationId: GetCapitalFlows
parameters:
- name: country
in: query
description: Optional ISO 3166-1 alpha-2 filter. When set, only that country is returned (and the counterpart, if given).
required: false
example: "US"
schema:
type: string
- name: include_series
in: query
description: When true, include each returned country's period-by-period BOP series. Defaults to false.
required: false
example: true
schema:
type: boolean
- name: counterpart
in: query
description: Optional ISO 3166-1 alpha-2 partner. With country, the response adds pair (both directions) and the counterpart's own view. Ignored without country, and when equal to country.
required: false
example: "DE"
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:
"countries":
- "bank":
"householdDepositsAbroad":
"flow4qUsdBn": 1.5
"stockUsdBn": 1.5
"latestPeriod": "2026-Q1"
"nonBankBorrowingFromAbroad":
"flow4qUsdBn": 1.5
"stockUsdBn": 1.5
"nonBankDepositsAbroad":
"flow4qUsdBn": 1.5
"stockUsdBn": 1.5
"publishesBilateral": true
"bop":
"episodes":
"flight":
- "end": "2026-Q1"
"peakPeriod": "2026-Q1"
"peakZ": 1.5
"quarters": 1
"start": "2026-Q1"
"retrenchment":
- "end": "2026-Q1"
"peakPeriod": "2026-Q1"
"peakZ": 1.5
"quarters": 1
"start": "2026-Q1"
"stop":
- "end": "2026-Q1"
"peakPeriod": "2026-Q1"
"peakZ": 1.5
"quarters": 1
"start": "2026-Q1"
"surge":
- "end": "2026-Q1"
"peakPeriod": "2026-Q1"
"peakZ": 1.5
"quarters": 1
"start": "2026-Q1"
"frequency": "example"
"latestPeriod": "2026-Q1"
"series":
- "errorsOmissions": 1.5
"inflows":
"fdi": 1.5
"other": 1.5
"portfolio": 1.5
"total": 1
"outflows":
"fdi": 1.5
"other": 1.5
"portfolio": 1.5
"total": 1
"period": "2026-Q1"
"state":
"inflow": "example"
"inflowZ": 1.5
"outflow": "example"
"outflowZ": 1.5
"country": "US"
"fdi":
"inwardUsdBn": 1.5
"outwardUsdBn": 1.5
"topDestinations":
- "country": "US"
"flow4qUsdBn": 1.5
"stockUsdBn": 1.5
"topInvestors":
- "country": "US"
"flow4qUsdBn": 1.5
"stockUsdBn": 1.5
"year": 1
"gdpUsdBn": 1.5
"latest":
"bisQuarter": "2026-Q1"
"bopQuarter": "2026-Q1"
"bopYear": "example"
"fdiYear": 1
"pipYear": 1
"method":
"exampleKey": "example"
"pair":
"aBorrowingFromB":
"basis": "example"
"counterpartReportUsdBn": 1
"flow4qUsdBn": 1.5
"history":
- "period": "2026-Q1"
"usdBn": 1.5
"instrument": "example"
"aDepositsInB":
"basis": "example"
"counterpartReportUsdBn": 1
"flow4qUsdBn": 1.5
"history":
- "period": "2026-Q1"
"usdBn": 1.5
"instrument": "example"
"aFdiInB":
"basis": "example"
"counterpartReportUsdBn": 1
"flow4qUsdBn": 1.5
"history":
- "period": "2026-Q1"
"usdBn": 1.5
"instrument": "example"
"aHoldingsOfB":
"basis": "example"
"counterpartReportUsdBn": 1
"flow4qUsdBn": 1.5
"history":
- "period": "2026-Q1"
"usdBn": 1.5
"instrument": "example"
"bBorrowingFromA":
"basis": "example"
"counterpartReportUsdBn": 1
"flow4qUsdBn": 1.5
"history":
- "period": "2026-Q1"
"usdBn": 1.5
"instrument": "example"
"seededAt": 1717200000000
schema:
$ref: '#/components/schemas/GetCapitalFlowsResponse'
"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/economic/v1/get-world-cpi-monthly:
get:
tags:
- EconomicService
summary: GetWorldCpiMonthly
description: GetWorldCpiMonthly returns one national CPI series per country, worldwide. The per-country source is chosen by precedence (national overlay, then HICP for Europe, then IMF, then OECD) with a staleness fall-through, so each row carries its source, frequency and index base. Month-over-month and year-over-year changes are computed from that index; levels are not comparable across sources. history=false is the latest period per country. history=true is the stored 10-year window.
operationId: GetWorldCpiMonthly
parameters:
- name: history
in: query
description: When true, return every stored period. When false, return only the latest period per country.
required: false
example: true
schema:
type: boolean
- name: country
in: query
description: Optional ISO 3166-1 alpha-2 filter. When set, only that country is returned.
required: false
example: "US"
schema:
type: string
- name: limit
in: query
description: Maximum recent observations per series, up to 366. Omit or use zero for the full stored history.
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:
"countries":
- "country": "US"
"frequency": "example"
"indexBase": "example"
"periods":
- "period": 1
"reading":
"index": 1.5
"periodOverPeriod":
"percent": 42.5
"yearOverYear":
"percent": 42.5
"source": "example"
"unavailable": false
schema:
$ref: '#/components/schemas/GetWorldCpiMonthlyResponse'
"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/economic/v1/get-government-yield-curve:
get:
tags:
- EconomicService
summary: GetGovernmentYieldCurve
description: GetGovernmentYieldCurve returns one sovereign market's daily yield curve from its official national publisher, or the OECD monthly 10Y benchmark when no daily curve is covered. Yields keep their publisher's measure and are never converted.
operationId: GetGovernmentYieldCurve
parameters:
- name: country
in: query
description: ISO 3166-1 alpha-2 code of the sovereign, e.g. "JP" or "DE".
required: true
example: "US"
schema:
type: string
- name: history
in: query
description: True for every stored business day; false for the latest day.
required: false
example: true
schema:
type: boolean
- name: limit
in: query
description: Maximum recent observations per series, up to 366. Omit or use zero for the full stored history.
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:
"country": "US"
"curves":
- "date": 1717200000000
"tenors":
"exampleKey": 1.5
"measure": "example"
"source": "example"
"unavailable": false
schema:
$ref: '#/components/schemas/GetGovernmentYieldCurveResponse'
"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'
components:
securitySchemes:
WorldMonitorKey:
type: apiKey
in: header
name: X-WorldMonitor-Key
description: User-issued WorldMonitor API key.
ApiKeyHeader:
type: apiKey
in: header
name: X-Api-Key
description: Alias header for the WorldMonitor API key (X-WorldMonitor-Key).
BearerAuth:
type: http
scheme: bearer
description: 'Bearer token: a Clerk-issued JWT for browser session flows, passed as Authorization: Bearer <token>.'
schemas:
JmespathProjectionError:
description: Returned when a REST jmespath projection is invalid or exceeds the expression/output byte limits.
properties:
_jmespath_error:
description: Projection error discriminator and details.
type: string
original_keys:
description: Top-level keys or shape of the unprojected response.
items:
type: string
type: array
required:
- _jmespath_error
- original_keys
type: object
UnauthorizedError:
type: object
properties:
error:
type: string
description: Human-readable error message.
required:
- error
description: Returned when the API key is missing, malformed, or lacks current API access.
Error:
type: object
properties:
message:
type: string
description: Error message (e.g., 'user not found', 'database connection failed')
description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.
BillingVerificationError:
type: object
description: "Returned with HTTP 503 when paid access cannot be confirmed right now: the billing provider is re-verifying a recently expired subscription, or the entitlement backend is unreachable. Retryable — honor Retry-After."
properties:
error:
type: string
description: Human-readable billing-verification failure reason.
code:
type: string
enum:
- renewal_verification_pending
- renewal_verification_failed
- entitlement_verification_unavailable
description: Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header.
requiredTier:
type: integer
format: int32
description: Minimum entitlement tier required for this endpoint, when the denial came from a tier gate.
required:
- error
- code
InvalidRequestBodyError:
type: object
description: Returned when a JSON POST request body is empty or malformed.
properties:
message:
type: string
description: Invalid request body
required:
- message
GatewayError:
type: object
description: Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks.
properties:
error:
oneOf:
- type: string
- type: object
additionalProperties: true
description: Gateway error reason or structured gateway failure details.
required:
- error
RateLimitError:
type: object
description: Returned when a gateway or handler rate limit rejects the request.
properties:
error:
type: string
description: Human-readable rate-limit failure reason.
required:
- error
ForbiddenError:
type: object
properties:
error:
type: string
description: Human-readable entitlement failure reason.
code:
type: string
enum:
- subscription_lapsed
description: Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header).
requiredTier:
type: integer
format: int32
description: Minimum entitlement tier required for this endpoint.
currentTier:
type: integer
format: int32
description: Caller entitlement tier when known.
planKey:
type: string
description: Caller plan key when known.
required:
- error
description: Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier.
FieldViolation:
type: object
properties:
field:
type: string
description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')
description:
type: string
description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')
required:
- field
- description
description: FieldViolation describes a single validation error for a specific field.
ValidationError:
type: object
properties:
violations:
type: array
items:
$ref: '#/components/schemas/FieldViolation'
description: List of validation violations
required:
- violations
description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.
GetFredSeriesRequest:
type: object
properties:
seriesId:
type: string
minLength: 1
description: FRED series ID (e.g., "GDP", "UNRATE", "CPIAUCSL").
limit:
type: integer
format: int32
description: Maximum number of observations to return. Defaults to 120.
required:
- seriesId
description: GetFredSeriesRequest specifies which FRED series to retrieve.
GetFredSeriesResponse:
type: object
properties:
series:
$ref: '#/components/schemas/FredSeries'
description: GetFredSeriesResponse contains the requested FRED series data.
FredSeries:
type: object
properties:
seriesId:
type: string
minLength: 1
description: Series identifier (e.g., "GDP", "UNRATE", "CPIAUCSL").
title:
type: string
description: Series title.
units:
type: string
description: Unit of measurement.
frequency:
type: string
description: Data frequency (e.g., "Monthly", "Quarterly").
observations:
type: array
items:
$ref: '#/components/schemas/FredObservation'
required:
- seriesId
description: FredSeries represents a FRED time series with metadata.
FredObservation:
type: object
properties:
date:
type: string
description: Observation date as YYYY-MM-DD string.
value:
type: number
format: double
description: Observation value.
description: FredObservation represents a single data point from a FRED economic series.
ListWorldBankIndicatorsRequest:
type: object
properties:
indicatorCode:
type: string
minLength: 1
description: World Bank indicator code (e.g., "NY.GDP.MKTP.CD").
countryCode:
type: string
description: Optional country filter (ISO 3166-1 alpha-2).
year:
type: integer
format: int32
description: Optional year filter. Defaults to latest available.
pageSize:
type: integer
format: int32
description: |-
Maximum items per page.
Accepted but currently ignored; no-op until this handler supports the parameter.
cursor:
type: string
description: |-
Cursor for next page.
Accepted but currently ignored; no-op until this handler supports the parameter.
required:
- indicatorCode
description: ListWorldBankIndicatorsRequest specifies filters for retrieving World Bank data.
ListWorldBankIndicatorsResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/WorldBankCountryData'
pagination:
$ref: '#/components/schemas/PaginationResponse'
description: ListWorldBankIndicatorsResponse contains World Bank indicator data.
WorldBankCountryData:
type: object
properties:
countryCode:
type: string
minLength: 1
description: ISO 3166-1 alpha-2 country code.
countryName:
type: string
description: Country name.
indicatorCode:
type: string
minLength: 1
description: World Bank indicator code (e.g., "NY.GDP.MKTP.CD").
indicatorName:
type: string
description: Indicator name.
year:
type: integer
format: int32
description: Data year.
value:
type: number
format: double
description: Indicator value.
required:
- countryCode
- indicatorCode
description: WorldBankCountryData represents a World Bank indicator value for a country.
PaginationResponse:
type: object
properties:
nextCursor:
type: string
description: Cursor for fetching the next page. Empty string indicates no more pages.
totalCount:
type: integer
format: int32
description: Total count of items matching the query, if known. Zero if the total is unknown.
description: PaginationResponse contains pagination metadata returned alongside list results.
GetEnergyPricesRequest:
type: object
properties:
commodities:
type: array
items:
type: string
description: Optional commodity filter. Empty returns all tracked commodities.
description: GetEnergyPricesRequest specifies which energy commodities to retrieve.
GetEnergyPricesResponse:
type: object
properties:
prices:
type: array
items:
$ref: '#/components/schemas/EnergyPrice'
description: GetEnergyPricesResponse contains energy price data.
EnergyPrice:
type: object
properties:
commodity:
type: string
minLength: 1
description: Energy commodity identifier.
name:
type: string
description: Human-readable name (e.g., "WTI Crude Oil", "Henry Hub Natural Gas").
price:
type: number
format: double
description: Observed price in USD. Check stale before treating it as current.
unit:
type: string
description: Unit of measurement (e.g., "$/barrel", "$/MMBtu").
change:
type: number
format: double
description: Percentage change from previous period.
priceAt:
type: integer
format: int64
description: 'Observation date as Unix epoch milliseconds. For weekly prices, the week ending date.. Warning: Values > 2^53 may lose precision in JavaScript'
priceSource:
type: string
priceBasis:
type: string
frequency:
type: string
stale:
type: boolean
description: True when the observation is undated, future-dated, or older than the freshness budget.
required:
- commodity
description: EnergyPrice represents a current energy commodity price from EIA.
GetMacroSignalsRequest:
type: object
description: GetMacroSignalsRequest requests the current macro signal dashboard.
GetMacroSignalsResponse:
type: object
properties:
timestamp:
type: string
description: ISO 8601 timestamp of computation.
verdict:
type: string
description: 'Overall verdict: "BUY", "CASH", or "UNKNOWN".'
bullishCount:
type: integer
format: int32
description: Number of bullish signals.
totalCount:
type: integer
format: int32
description: Total number of evaluated signals (excluding UNKNOWN).
signals:
$ref: '#/components/schemas/MacroSignals'
meta:
$ref: '#/components/schemas/MacroMeta'
unavailable:
type: boolean
description: |-
True when upstream data is unavailable (fallback result).
True when the upstream or seed-backed variant is unavailable; empty payload fields
are graceful degradation, not confirmed zero data.
description: GetMacroSignalsResponse contains the full macro signal dashboard with 7 signals and verdict.
MacroSignals:
type: object
properties:
liquidity:
$ref: '#/components/schemas/LiquiditySignal'
flowStructure:
$ref: '#/components/schemas/FlowStructureSignal'
macroRegime:
$ref: '#/components/schemas/MacroRegimeSignal'
technicalTrend:
$ref: '#/components/schemas/TechnicalTrendSignal'
hashRate:
$ref: '#/components/schemas/HashRateSignal'
priceMomentum:
$ref: '#/components/schemas/PriceMomentumSignal'
fearGreed:
$ref: '#/components/schemas/FearGreedSignal'
description: MacroSignals contains all 7 individual signal computations.
LiquiditySignal:
type: object
properties:
status:
type: string
description: '"SQUEEZE", "NORMAL", or "UNKNOWN".'
value:
type: number
format: double
description: JPY 30d ROC percentage, absent if unavailable.
sparkline:
type: array
items:
type: number
format: double
description: Last 30 JPY close prices.
description: LiquiditySignal tracks JPY 30d rate of change as a liquidity proxy.
FlowStructureSignal:
type: object
properties:
status:
type: string
description: '"PASSIVE GAP", "ALIGNED", or "UNKNOWN".'
btcReturn5:
type: number
format: double
description: BTC 5-day return percentage.
qqqReturn5:
type: number
format: double
description: QQQ 5-day return percentage.
description: FlowStructureSignal compares BTC vs QQQ 5-day returns.
MacroRegimeSignal:
type: object
properties:
status:
type: string
description: '"RISK-ON", "DEFENSIVE", or "UNKNOWN".'
qqqRoc20:
type: number
format: double
description: QQQ 20d ROC percentage.
xlpRoc20:
type: number
format: double
description: XLP 20d ROC percentage.
description: MacroRegimeSignal compares QQQ vs XLP 20-day rate of change.
TechnicalTrendSignal:
type: object
properties:
status:
type: string
description: '"BULLISH", "BEARISH", "NEUTRAL", or "UNKNOWN".'
btcPrice:
type: number
format: double
description: Current BTC price.
sma50:
type: number
format: double
description: 50-day simple moving average.
sma200:
type: number
format: double
description: 200-day simple moving average.
vwap30d:
type: number
format: double
description: 30-day volume-weighted average price.
mayerMultiple:
type: number
format: double
description: Mayer multiple (BTC price / SMA200).
sparkline:
type: array
items:
type: number
format: double
description: Last 30 BTC close prices.
description: TechnicalTrendSignal evaluates BTC price vs moving averages and VWAP.
HashRateSignal:
type: object
properties:
status:
type: string
description: '"GROWING", "DECLINING", "STABLE", or "UNKNOWN".'
change30d:
type: number
format: double
description: Hash rate change over 30 days as percentage.
description: HashRateSignal tracks Bitcoin hash rate momentum.
PriceMomentumSignal:
type: object
properties:
status:
type: string
description: '"STRONG", "MODERATE", "WEAK", or "UNKNOWN".'