openapi: 3.1.0
info:
    title: WorldMonitor API
    description: Unified OpenAPI bundle spanning all WorldMonitor services.
    contact:
        name: WorldMonitor
        email: support@worldmonitor.app
    version: 1.0.0
servers:
    - url: https://api.worldmonitor.app
security:
    - WorldMonitorKey: []
    - ApiKeyHeader: []
paths:
    /api/aviation/v1/list-airport-delays:
        get:
            tags:
                - AviationService
            summary: ListAirportDelays
            description: ListAirportDelays retrieves current airport delay alerts.
            operationId: ListAirportDelays
            parameters:
                - name: page_size
                  in: query
                  description: |-
                    Maximum items per page (1-100).
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: region
                  in: query
                  description: |-
                    Optional region filter.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "AIRPORT_REGION_AMERICAS"
                  schema:
                    type: string
                    enum:
                        - 'AIRPORT_REGION_AMERICAS'
                        - 'AIRPORT_REGION_EUROPE'
                        - 'AIRPORT_REGION_APAC'
                        - 'AIRPORT_REGION_MENA'
                        - 'AIRPORT_REGION_AFRICA'
                - name: min_severity
                  in: query
                  description: |-
                    Optional minimum severity filter.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "FLIGHT_DELAY_SEVERITY_NORMAL"
                  schema:
                    type: string
                    enum:
                        - 'FLIGHT_DELAY_SEVERITY_NORMAL'
                        - 'FLIGHT_DELAY_SEVERITY_MINOR'
                        - 'FLIGHT_DELAY_SEVERITY_MODERATE'
                        - 'FLIGHT_DELAY_SEVERITY_MAJOR'
                        - 'FLIGHT_DELAY_SEVERITY_SEVERE'
                        - 'FLIGHT_DELAY_SEVERITY_UNKNOWN'
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "alerts":
                                    - "avgDelayMinutes": 1
                                      "cancelledFlights": 1
                                      "city": "example"
                                      "country": "US"
                                      "delayType": "FLIGHT_DELAY_TYPE_GROUND_STOP"
                                      "id": "example-id"
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_aviation_v1_ListAirportDelaysResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/aviation/v1/get-airport-ops-summary:
        get:
            tags:
                - AviationService
            summary: GetAirportOpsSummary
            description: GetAirportOpsSummary returns operational health metrics for watched airports.
            operationId: GetAirportOpsSummary
            parameters:
                - name: airports
                  in: query
                  description: IATA airport codes to query (e.g., ["IST", "ESB", "LHR"]).
                  required: false
                  style: form
                  explode: true
                  example:
                      - "JFK"
                  schema:
                    type: array
                    items:
                        type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "cacheHit": true
                                "summaries":
                                    - "avgDelayMinutes": 1
                                      "cancellationRate": 75.25
                                      "closureStatus": true
                                      "delayPct": 1.5
                                      "iata": "JFK"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_aviation_v1_GetAirportOpsSummaryResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/aviation/v1/list-airport-flights:
        get:
            tags:
                - AviationService
            summary: ListAirportFlights
            description: ListAirportFlights retrieves recent flights at a specific airport.
            operationId: ListAirportFlights
            parameters:
                - name: airport
                  in: query
                  description: IATA airport code (e.g., "IST").
                  required: true
                  example: "JFK"
                  schema:
                    type: string
                - name: direction
                  in: query
                  description: Direction filter.
                  required: false
                  example: "FLIGHT_DIRECTION_DEPARTURE"
                  schema:
                    type: string
                    enum:
                        - 'FLIGHT_DIRECTION_DEPARTURE'
                        - 'FLIGHT_DIRECTION_ARRIVAL'
                        - 'FLIGHT_DIRECTION_BOTH'
                - name: limit
                  in: query
                  description: Maximum number of flights to return (1-100).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "flights":
                                    - "actualArrival": 1
                                      "actualDeparture": 1
                                      "aircraftIcao24": "a835af"
                                      "aircraftType": "all"
                                      "cancelled": true
                                "source": "example"
                                "totalAvailable": 1
                                "updatedAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_aviation_v1_ListAirportFlightsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/aviation/v1/get-carrier-ops:
        get:
            tags:
                - AviationService
            summary: GetCarrierOps
            description: GetCarrierOps returns delay and cancellation metrics grouped by carrier.
            operationId: GetCarrierOps
            parameters:
                - name: airports
                  in: query
                  description: IATA airport codes to aggregate carrier metrics from.
                  required: false
                  style: form
                  explode: true
                  example:
                      - "JFK"
                  schema:
                    type: array
                    items:
                        type: string
                - name: min_flights
                  in: query
                  description: 'Minimum number of flights required to include a carrier (default: 1).'
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "carriers":
                                    - "airport": "JFK"
                                      "avgDelayMinutes": 1
                                      "cancellationRate": 75.25
                                      "cancelledCount": 1
                                      "carrier":
                                          "iataCode": "JFK"
                                          "icaoCode": "example"
                                          "name": "WorldMonitor Analyst"
                                "source": "example"
                                "updatedAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_aviation_v1_GetCarrierOpsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/aviation/v1/get-flight-status:
        get:
            tags:
                - AviationService
            summary: GetFlightStatus
            description: GetFlightStatus looks up the current status of a specific flight.
            operationId: GetFlightStatus
            parameters:
                - name: flight_number
                  in: query
                  description: IATA flight number (e.g., "TK1952").
                  required: true
                  example: "JFK"
                  schema:
                    type: string
                - name: date
                  in: query
                  description: Departure date in ISO 8601 format (e.g., "2026-03-05").
                  required: true
                  example: "2026-01-15"
                  schema:
                    type: string
                - name: origin
                  in: query
                  description: Optional origin airport IATA code to disambiguate.
                  required: false
                  example: "JFK"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "cacheHit": true
                                "flights":
                                    - "actualArrival": 1
                                      "actualDeparture": 1
                                      "aircraftIcao24": "a835af"
                                      "aircraftType": "all"
                                      "cancelled": true
                                "source": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_aviation_v1_GetFlightStatusResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/aviation/v1/track-aircraft:
        get:
            tags:
                - AviationService
            summary: TrackAircraft
            description: TrackAircraft retrieves live position stream for a specific aircraft hex.
            operationId: TrackAircraft
            parameters:
                - name: icao24
                  in: query
                  description: ICAO 24-bit transponder address (hex, e.g., "4b1805").
                  required: false
                  example: "a835af"
                  schema:
                    type: string
                - name: callsign
                  in: query
                  description: ATC callsign (e.g., "THY7CX").
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: sw_lat
                  in: query
                  description: Optional bounding box south-west latitude.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: sw_lon
                  in: query
                  description: Optional bounding box south-west longitude.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: ne_lat
                  in: query
                  description: Optional bounding box north-east latitude.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: ne_lon
                  in: query
                  description: Optional bounding box north-east longitude.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "positions":
                                    - "altitudeM": 1.5
                                      "callsign": "example"
                                      "groundSpeedKts": 1.5
                                      "icao24": "a835af"
                                      "lat": 40.7128
                                "source": "example"
                                "updatedAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_aviation_v1_TrackAircraftResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/aviation/v1/get-youtube-live-stream-info:
        get:
            tags:
                - AviationService
            summary: GetYoutubeLiveStreamInfo
            description: GetYoutubeLiveStreamInfo retrieves information about a YouTube live stream (status, title, etc).
            operationId: GetYoutubeLiveStreamInfo
            parameters:
                - name: channel
                  in: query
                  description: YouTube channel handle or ID.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: video_id
                  in: query
                  description: Specific video ID to check.
                  required: false
                  example: "example-id"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "channelExists": true
                                "channelName": "WorldMonitor Analyst"
                                "error": "example"
                                "hlsUrl": "https://example.com/worldmonitor"
                                "isLive": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_aviation_v1_GetYoutubeLiveStreamInfoResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/aviation/v1/search-flight-prices:
        get:
            tags:
                - AviationService
            summary: SearchFlightPrices
            description: SearchFlightPrices searches for flight price offers on a route.
            operationId: SearchFlightPrices
            parameters:
                - name: origin
                  in: query
                  description: Origin airport IATA code.
                  required: true
                  example: "JFK"
                  schema:
                    type: string
                - name: destination
                  in: query
                  description: Destination airport IATA code.
                  required: true
                  example: "LHR"
                  schema:
                    type: string
                - name: departure_date
                  in: query
                  description: Outbound departure date (ISO 8601).
                  required: true
                  example: "2026-01-15"
                  schema:
                    type: string
                - name: return_date
                  in: query
                  description: Return date (ISO 8601), empty for one-way.
                  required: false
                  example: "2026-01-15"
                  schema:
                    type: string
                - name: adults
                  in: query
                  description: Number of adult passengers (1-9).
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: cabin
                  in: query
                  description: Desired cabin class.
                  required: false
                  example: "CABIN_CLASS_ECONOMY"
                  schema:
                    type: string
                    enum:
                        - 'CABIN_CLASS_ECONOMY'
                        - 'CABIN_CLASS_PREMIUM_ECONOMY'
                        - 'CABIN_CLASS_BUSINESS'
                        - 'CABIN_CLASS_FIRST'
                - name: nonstop_only
                  in: query
                  description: Whether to restrict to nonstop flights only.
                  required: false
                  example: true
                  schema:
                    type: boolean
                - name: max_results
                  in: query
                  description: Maximum number of quotes to return (1-50).
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: currency
                  in: query
                  description: ISO 4217 currency code for prices (e.g., "usd", "eur", "try").
                  required: false
                  example: "USD"
                  schema:
                    type: string
                - name: market
                  in: query
                  description: Market/locale code (e.g., "us", "tr").
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "degraded": true
                                "error": "example"
                                "isDemoMode": true
                                "isIndicative": true
                                "provider": "worldmonitor"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_aviation_v1_SearchFlightPricesResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/aviation/v1/list-aviation-news:
        get:
            tags:
                - AviationService
            summary: ListAviationNews
            description: ListAviationNews retrieves filtered aviation news articles.
            operationId: ListAviationNews
            parameters:
                - name: entities
                  in: query
                  description: Entities to filter by (airline names, airport codes, route strings).
                  required: false
                  style: form
                  explode: true
                  example:
                      - "example"
                  schema:
                    type: array
                    items:
                        type: string
                - name: window_hours
                  in: query
                  description: Time window in hours to look back (1-168).
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: max_items
                  in: query
                  description: Maximum number of news items to return (1-50).
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "items":
                                    - "id": "example-id"
                                      "imageUrl": "https://example.com/worldmonitor"
                                      "matchedEntities":
                                          - "example"
                                      "publishedAt": 1717200000000
                                      "snippet": "example"
                                "source": "example"
                                "updatedAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_aviation_v1_ListAviationNewsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/aviation/v1/search-google-flights:
        get:
            tags:
                - AviationService
            summary: SearchGoogleFlights
            description: SearchGoogleFlights searches Google Flights for available itineraries on a specific date.
            operationId: SearchGoogleFlights
            parameters:
                - name: origin
                  in: query
                  description: Departure airport IATA code (e.g. "JFK").
                  required: false
                  example: "JFK"
                  schema:
                    type: string
                - name: destination
                  in: query
                  description: Arrival airport IATA code (e.g. "LHR").
                  required: false
                  example: "LHR"
                  schema:
                    type: string
                - name: departure_date
                  in: query
                  description: Departure date in YYYY-MM-DD format.
                  required: false
                  example: "2026-01-15"
                  schema:
                    type: string
                - name: return_date
                  in: query
                  description: Return date in YYYY-MM-DD format; omit for one-way.
                  required: false
                  example: "2026-01-15"
                  schema:
                    type: string
                - name: cabin_class
                  in: query
                  description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.'
                  required: false
                  example: "ECONOMY"
                  schema:
                    type: string
                - name: max_stops
                  in: query
                  description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.'
                  required: false
                  example: "ANY"
                  schema:
                    type: string
                - name: departure_window
                  in: query
                  description: Departure time window in HH-HH format (e.g. "6-20").
                  required: false
                  example: "6-20"
                  schema:
                    type: string
                - name: airlines
                  in: query
                  description: Airline IATA codes to filter by (e.g. ["BA", "AA"]).
                  required: false
                  style: form
                  explode: true
                  example:
                      - "BA"
                  schema:
                    type: array
                    items:
                        type: string
                - name: sort_by
                  in: query
                  description: 'Sort order: CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME.'
                  required: false
                  example: "CHEAPEST"
                  schema:
                    type: string
                - name: passengers
                  in: query
                  description: Number of adult passengers (1-9).
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "degraded": true
                                "error": "example"
                                "flights":
                                    - "durationMinutes": 42
                                      "legs":
                                          - "airlineCode": "example"
                                            "arrivalAirport": "example"
                                            "arrivalDatetime": "2026-01-15"
                                            "departureAirport": "example"
                                            "departureDatetime": "2026-01-15"
                                      "price": 75.25
                                      "stops": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_aviation_v1_SearchGoogleFlightsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/aviation/v1/search-google-dates:
        get:
            tags:
                - AviationService
            summary: SearchGoogleDates
            description: SearchGoogleDates finds the cheapest travel dates across a flexible date range via Google Flights.
            operationId: SearchGoogleDates
            parameters:
                - name: origin
                  in: query
                  description: Departure airport IATA code (e.g. "JFK").
                  required: false
                  example: "JFK"
                  schema:
                    type: string
                - name: destination
                  in: query
                  description: Arrival airport IATA code (e.g. "LHR").
                  required: false
                  example: "LHR"
                  schema:
                    type: string
                - name: start_date
                  in: query
                  description: Start of date range in YYYY-MM-DD format.
                  required: false
                  example: "2026-01-15"
                  schema:
                    type: string
                - name: end_date
                  in: query
                  description: End of date range in YYYY-MM-DD format.
                  required: false
                  example: "2026-01-15"
                  schema:
                    type: string
                - name: trip_duration
                  in: query
                  description: Trip duration in days (required for round-trip searches).
                  required: false
                  example: 42
                  schema:
                    type: integer
                    format: int32
                - name: is_round_trip
                  in: query
                  description: Whether to search for round-trip flights.
                  required: false
                  example: true
                  schema:
                    type: boolean
                - name: cabin_class
                  in: query
                  description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.'
                  required: false
                  example: "ECONOMY"
                  schema:
                    type: string
                - name: max_stops
                  in: query
                  description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.'
                  required: false
                  example: "ANY"
                  schema:
                    type: string
                - name: departure_window
                  in: query
                  description: Departure time window in HH-HH format (e.g. "6-20").
                  required: false
                  example: "6-20"
                  schema:
                    type: string
                - name: airlines
                  in: query
                  description: Airline IATA codes to filter by (e.g. ["BA", "AA"]).
                  required: false
                  style: form
                  explode: true
                  example:
                      - "BA"
                  schema:
                    type: array
                    items:
                        type: string
                - name: sort_by_price
                  in: query
                  description: Whether to sort results by price (lowest first).
                  required: false
                  example: true
                  schema:
                    type: boolean
                - name: passengers
                  in: query
                  description: Number of adult passengers (1-9).
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "dates":
                                    - "date": "2026-01-15"
                                      "price": 75.25
                                      "returnDate": "2026-01-15"
                                "degraded": true
                                "error": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_aviation_v1_SearchGoogleDatesResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/batch/v1/execute:
        post:
            parameters:
                - name: Idempotency-Key
                  in: header
                  description: Optional client-generated idempotency key. Retrying a POST with the same key and an identical request body replays the original response (only the status, body, and Content-Type are reproduced) instead of re-executing; reusing the key with a different body is rejected with 422. For mutations this avoids duplicating the side effect, while for batch-read POSTs it replays a cached snapshot that can be up to 24 hours stale. Keys are scoped per authenticated caller (falling back to the source IP for unauthenticated endpoints) and retained for 24 hours.
                  required: false
                  example: "4f8b9c2e-1a3d-4b6f-8e0a-2c5d7f9b1e34"
                  schema:
                    type: string
                    minLength: 1
                    maxLength: 255
                    pattern: "^[\\x21-\\x7E]{1,255}$"
            tags:
                - BatchService
            summary: ExecuteBatch
            description: ExecuteBatch runs a bulk batch of up to 20 read (GET) operations concurrently in one round trip and returns per-operation statuses and bodies. Use it instead of looping single calls when acting on many items; add a per-operation ?jmespath= projection to keep each body small.
            operationId: ExecuteBatch
            requestBody:
                content:
                    application/json:
                        example:
                            "operations":
                                - "id": "example-id"
                                  "path": "/api/market/v1/get-fear-greed-index"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_batch_v1_ExecuteBatchRequest'
                required: true
            responses:
                "200":
                    description: Successful response
                    headers:
                        Idempotency-Key:
                            schema:
                                type: string
                            description: The idempotency key echoed from the request. Present only when the client opted into idempotency.
                        Idempotent-Replayed:
                            schema:
                                type: boolean
                            description: true when this response was replayed from an earlier request with the same key, false on the first (original) request. Present only when the client opted into idempotency.
                    content:
                        application/json:
                            example:
                                "failed": 1
                                "results":
                                    - "body":
                                        {}
                                      "error": "example"
                                      "id": "example-id"
                                      "status": 1
                                "succeeded": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_batch_v1_ExecuteBatchResponse'
                "400":
                    description: Validation error, invalid Idempotency-Key header, or malformed JSON request body
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - type: object
                                      required:
                                        - error
                                        - message
                                      properties:
                                        error:
                                            type: string
                                        message:
                                            type: string
                                    - $ref: '#/components/schemas/InvalidRequestBodyError'
                "409":
                    description: A request with this Idempotency-Key is still being processed
                    headers:
                        Idempotency-Key:
                            schema:
                                type: string
                            description: The idempotency key supplied by the client.
                        Retry-After:
                            schema:
                                type: string
                            description: Seconds to wait before retrying the in-flight request.
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - error
                                    - message
                                properties:
                                    error:
                                        type: string
                                    message:
                                        type: string
                "422":
                    description: The Idempotency-Key was already used with a different request body
                    headers:
                        Idempotency-Key:
                            schema:
                                type: string
                            description: The idempotency key supplied by the client.
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - error
                                    - message
                                properties:
                                    error:
                                        type: string
                                    message:
                                        type: string
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/climate/v1/list-climate-anomalies:
        get:
            tags:
                - ClimateService
            summary: ListClimateAnomalies
            description: ListClimateAnomalies retrieves temperature and precipitation anomalies from ERA5 data.
            operationId: ListClimateAnomalies
            parameters:
                - name: page_size
                  in: query
                  description: |-
                    Maximum items per page (1-100).
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: min_severity
                  in: query
                  description: |-
                    Optional filter by anomaly severity.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "ANOMALY_SEVERITY_NORMAL"
                  schema:
                    type: string
                    enum:
                        - 'ANOMALY_SEVERITY_NORMAL'
                        - 'ANOMALY_SEVERITY_MODERATE'
                        - 'ANOMALY_SEVERITY_EXTREME'
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "anomalies":
                                    - "location":
                                        "latitude": 40.7128
                                        "longitude": -74.006
                                      "period": "daily"
                                      "precipDelta": 1.5
                                      "severity": "ANOMALY_SEVERITY_NORMAL"
                                      "tempDelta": 1.5
                                      "type": "ANOMALY_TYPE_WARM"
                                      "zone": "example"
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_climate_v1_ListClimateAnomaliesResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/climate/v1/list-climate-disasters:
        get:
            tags:
                - ClimateService
            summary: ListClimateDisasters
            description: ListClimateDisasters retrieves climate-relevant disaster events from seeded data.
            operationId: ListClimateDisasters
            parameters:
                - name: page_size
                  in: query
                  description: Maximum items per page (1-100).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: Cursor for next page.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "disasters":
                                    - "affectedPopulation": 1
                                      "country": "US"
                                      "countryCode": "US"
                                      "id": "example-id"
                                      "lat": 40.7128
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_climate_v1_ListClimateDisastersResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/climate/v1/get-co2-monitoring:
        get:
            tags:
                - ClimateService
            summary: GetCo2Monitoring
            description: GetCo2Monitoring retrieves seeded NOAA greenhouse gas monitoring data.
            operationId: GetCo2Monitoring
            parameters:
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "monitoring":
                                    "annualGrowthRate": 75.25
                                    "currentPpm": 1.5
                                    "measuredAt": "1717200000000"
                                    "methanePpb": 1.5
                                    "monthlyAverage": 1.5
                            schema:
                                $ref: '#/components/schemas/worldmonitor_climate_v1_GetCo2MonitoringResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/climate/v1/get-ocean-ice-data:
        get:
            tags:
                - ClimateService
            summary: GetOceanIceData
            description: GetOceanIceData retrieves seeded Arctic sea ice, sea level, and ocean heat indicators.
            operationId: GetOceanIceData
            parameters:
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "data":
                                    "arcticExtentAnomalyMkm2": 1.5
                                    "arcticExtentMkm2": 1.5
                                    "arcticTrend": "example"
                                    "iceTrend12m":
                                        - "anomalyMkm2": 1.5
                                          "extentMkm2": 1.5
                                          "month": "example"
                                    "measuredAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_climate_v1_GetOceanIceDataResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/climate/v1/list-air-quality-data:
        get:
            tags:
                - ClimateService
            summary: ListAirQualityData
            description: ListAirQualityData retrieves recent PM2.5 station data from the shared air-quality seed.
            operationId: ListAirQualityData
            parameters:
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "fetchedAt": 1717200000000
                                "stations":
                                    - "aqi": 1
                                      "city": "example"
                                      "countryCode": "US"
                                      "lat": 40.7128
                                      "lng": -74.006
                            schema:
                                $ref: '#/components/schemas/worldmonitor_climate_v1_ListAirQualityDataResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/climate/v1/list-climate-news:
        get:
            tags:
                - ClimateService
            summary: ListClimateNews
            description: |-
                ListClimateNews retrieves latest climate/environment intelligence headlines from seeded RSS feeds.
                 Empty items with fetched_at=0 or data_available=false means the seed snapshot
                 is unavailable/degraded, not that there are confirmed zero headlines.
            operationId: ListClimateNews
            parameters:
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "dataAvailable": true
                                "fetchedAt": 1717200000000
                                "items":
                                    - "id": "example-id"
                                      "publishedAt": 1717200000000
                                      "sourceName": "WorldMonitor Analyst"
                                      "summary": "Example WorldMonitor observation."
                                      "title": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_climate_v1_ListClimateNewsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/conflict/v1/list-acled-events:
        get:
            tags:
                - ConflictService
            summary: ListAcledEvents
            description: ListAcledEvents retrieves armed conflict events from the ACLED dataset.
            operationId: ListAcledEvents
            security: []
            parameters:
                - name: start
                  in: query
                  description: Start of time range (inclusive), Unix epoch milliseconds.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: end
                  in: query
                  description: End of time range (inclusive), Unix epoch milliseconds.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: page_size
                  in: query
                  description: |-
                    Maximum items per page (1-100).
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: country
                  in: query
                  description: Optional country filter (ISO 3166-1 alpha-2).
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "events":
                                    - "actors":
                                        - "example"
                                      "admin1": "example"
                                      "country": "US"
                                      "eventType": "all"
                                      "fatalities": 1
                                      "id": "example-id"
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_conflict_v1_ListAcledEventsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/conflict/v1/list-ucdp-events:
        get:
            tags:
                - ConflictService
            summary: ListUcdpEvents
            description: ListUcdpEvents retrieves georeferenced violence events from the UCDP dataset.
            operationId: ListUcdpEvents
            parameters:
                - name: start
                  in: query
                  description: |-
                    Start of time range (inclusive), Unix epoch milliseconds.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: end
                  in: query
                  description: |-
                    End of time range (inclusive), Unix epoch milliseconds.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: page_size
                  in: query
                  description: |-
                    Maximum items per page (1-100).
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: country
                  in: query
                  description: Optional country filter (ISO 3166-1 alpha-2).
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "events":
                                    - "country": "US"
                                      "dateEnd": 1
                                      "dateStart": 1
                                      "deathsBest": 1
                                      "deathsHigh": 1
                                      "id": "example-id"
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_conflict_v1_ListUcdpEventsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/conflict/v1/get-humanitarian-summary:
        get:
            tags:
                - ConflictService
            summary: GetHumanitarianSummary
            description: GetHumanitarianSummary retrieves a humanitarian overview for a country from HAPI/HDX.
            operationId: GetHumanitarianSummary
            parameters:
                - name: country_code
                  in: query
                  description: ISO 3166-1 alpha-2 country code (e.g., "YE", "SD", "SO").
                  required: true
                  example: "AD"
                  schema:
                    type: string
                    enum:
                        - 'AD'
                        - 'AE'
                        - 'AF'
                        - 'AG'
                        - 'AI'
                        - 'AL'
                        - 'AM'
                        - 'AO'
                        - 'AQ'
                        - 'AR'
                        - 'AS'
                        - 'AT'
                        - 'AU'
                        - 'AW'
                        - 'AX'
                        - 'AZ'
                        - 'BA'
                        - 'BB'
                        - 'BD'
                        - 'BE'
                        - 'BF'
                        - 'BG'
                        - 'BH'
                        - 'BI'
                        - 'BJ'
                        - 'BL'
                        - 'BM'
                        - 'BN'
                        - 'BO'
                        - 'BR'
                        - 'BS'
                        - 'BT'
                        - 'BW'
                        - 'BY'
                        - 'BZ'
                        - 'CA'
                        - 'CD'
                        - 'CF'
                        - 'CG'
                        - 'CH'
                        - 'CI'
                        - 'CK'
                        - 'CL'
                        - 'CM'
                        - 'CN'
                        - 'CO'
                        - 'CR'
                        - 'CU'
                        - 'CV'
                        - 'CW'
                        - 'CY'
                        - 'CZ'
                        - 'DE'
                        - 'DJ'
                        - 'DK'
                        - 'DM'
                        - 'DO'
                        - 'DZ'
                        - 'EC'
                        - 'EE'
                        - 'EG'
                        - 'EH'
                        - 'ER'
                        - 'ES'
                        - 'ET'
                        - 'FI'
                        - 'FJ'
                        - 'FK'
                        - 'FM'
                        - 'FO'
                        - 'FR'
                        - 'GA'
                        - 'GB'
                        - 'GD'
                        - 'GE'
                        - 'GG'
                        - 'GH'
                        - 'GI'
                        - 'GL'
                        - 'GM'
                        - 'GN'
                        - 'GQ'
                        - 'GR'
                        - 'GS'
                        - 'GT'
                        - 'GU'
                        - 'GW'
                        - 'GY'
                        - 'HK'
                        - 'HM'
                        - 'HN'
                        - 'HR'
                        - 'HT'
                        - 'HU'
                        - 'ID'
                        - 'IE'
                        - 'IL'
                        - 'IM'
                        - 'IN'
                        - 'IO'
                        - 'IQ'
                        - 'IR'
                        - 'IS'
                        - 'IT'
                        - 'JE'
                        - 'JM'
                        - 'JO'
                        - 'JP'
                        - 'KE'
                        - 'KG'
                        - 'KH'
                        - 'KI'
                        - 'KM'
                        - 'KN'
                        - 'KP'
                        - 'KR'
                        - 'KW'
                        - 'KY'
                        - 'KZ'
                        - 'LA'
                        - 'LB'
                        - 'LC'
                        - 'LI'
                        - 'LK'
                        - 'LR'
                        - 'LS'
                        - 'LT'
                        - 'LU'
                        - 'LV'
                        - 'LY'
                        - 'MA'
                        - 'MC'
                        - 'MD'
                        - 'ME'
                        - 'MF'
                        - 'MG'
                        - 'MH'
                        - 'MK'
                        - 'ML'
                        - 'MM'
                        - 'MN'
                        - 'MO'
                        - 'MP'
                        - 'MR'
                        - 'MS'
                        - 'MT'
                        - 'MU'
                        - 'MV'
                        - 'MW'
                        - 'MX'
                        - 'MY'
                        - 'MZ'
                        - 'NA'
                        - 'NC'
                        - 'NE'
                        - 'NF'
                        - 'NG'
                        - 'NI'
                        - 'NL'
                        - 'NO'
                        - 'NP'
                        - 'NR'
                        - 'NU'
                        - 'NZ'
                        - 'OM'
                        - 'PA'
                        - 'PE'
                        - 'PF'
                        - 'PG'
                        - 'PH'
                        - 'PK'
                        - 'PL'
                        - 'PM'
                        - 'PN'
                        - 'PR'
                        - 'PS'
                        - 'PT'
                        - 'PW'
                        - 'PY'
                        - 'QA'
                        - 'RO'
                        - 'RS'
                        - 'RU'
                        - 'RW'
                        - 'SA'
                        - 'SB'
                        - 'SC'
                        - 'SD'
                        - 'SE'
                        - 'SG'
                        - 'SH'
                        - 'SI'
                        - 'SK'
                        - 'SL'
                        - 'SM'
                        - 'SN'
                        - 'SO'
                        - 'SR'
                        - 'SS'
                        - 'ST'
                        - 'SV'
                        - 'SX'
                        - 'SY'
                        - 'SZ'
                        - 'TC'
                        - 'TD'
                        - 'TF'
                        - 'TG'
                        - 'TH'
                        - 'TJ'
                        - 'TL'
                        - 'TM'
                        - 'TN'
                        - 'TO'
                        - 'TR'
                        - 'TT'
                        - 'TV'
                        - 'TW'
                        - 'TZ'
                        - 'UA'
                        - 'UG'
                        - 'UM'
                        - 'US'
                        - 'UY'
                        - 'UZ'
                        - 'VA'
                        - 'VC'
                        - 'VE'
                        - 'VG'
                        - 'VI'
                        - 'VN'
                        - 'VU'
                        - 'WF'
                        - 'WS'
                        - 'XK'
                        - 'YE'
                        - 'ZA'
                        - 'ZM'
                        - 'ZW'
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "summary":
                                    "conflictDemonstrations": 42
                                    "conflictEventsTotal": 1
                                    "conflictFatalities": 1
                                    "conflictPoliticalViolenceEvents": 1
                                    "countryCode": "US"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_conflict_v1_GetHumanitarianSummaryResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/conflict/v1/list-iran-events:
        get:
            tags:
                - ConflictService
            summary: ListIranEvents
            description: ListIranEvents retrieves scraped conflict events from LiveUAMap Iran.
            operationId: ListIranEvents
            parameters:
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "events":
                                    - "category": "cs.AI"
                                      "id": "example-id"
                                      "latitude": 40.7128
                                      "locationName": "WorldMonitor Analyst"
                                      "longitude": -74.006
                                "scrapedAt": "1717200000000"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_conflict_v1_ListIranEventsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/conflict/v1/get-humanitarian-summary-batch:
        post:
            parameters:
                - name: Idempotency-Key
                  in: header
                  description: Optional client-generated idempotency key. Retrying a POST with the same key and an identical request body replays the original response (only the status, body, and Content-Type are reproduced) instead of re-executing; reusing the key with a different body is rejected with 422. For mutations this avoids duplicating the side effect, while for batch-read POSTs it replays a cached snapshot that can be up to 24 hours stale. Keys are scoped per authenticated caller (falling back to the source IP for unauthenticated endpoints) and retained for 24 hours.
                  required: false
                  example: "4f8b9c2e-1a3d-4b6f-8e0a-2c5d7f9b1e34"
                  schema:
                    type: string
                    minLength: 1
                    maxLength: 255
                    pattern: "^[\\x21-\\x7E]{1,255}$"
            tags:
                - ConflictService
            summary: GetHumanitarianSummaryBatch
            description: GetHumanitarianSummaryBatch retrieves humanitarian summaries for multiple countries in one call.
            operationId: GetHumanitarianSummaryBatch
            requestBody:
                content:
                    application/json:
                        example:
                            "countryCodes":
                                - "US"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_conflict_v1_GetHumanitarianSummaryBatchRequest'
                required: true
            responses:
                "200":
                    description: Successful response
                    headers:
                        Idempotency-Key:
                            schema:
                                type: string
                            description: The idempotency key echoed from the request. Present only when the client opted into idempotency.
                        Idempotent-Replayed:
                            schema:
                                type: boolean
                            description: true when this response was replayed from an earlier request with the same key, false on the first (original) request. Present only when the client opted into idempotency.
                    content:
                        application/json:
                            example:
                                "fetched": 1
                                "requested": 1
                                "results":
                                    "exampleKey":
                                        "conflictDemonstrations": 42
                                        "conflictEventsTotal": 1
                                        "conflictFatalities": 1
                                        "conflictPoliticalViolenceEvents": 1
                                        "countryCode": "US"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_conflict_v1_GetHumanitarianSummaryBatchResponse'
                "400":
                    description: Validation error, invalid Idempotency-Key header, or malformed JSON request body
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - type: object
                                      required:
                                        - error
                                        - message
                                      properties:
                                        error:
                                            type: string
                                        message:
                                            type: string
                                    - $ref: '#/components/schemas/InvalidRequestBodyError'
                "409":
                    description: A request with this Idempotency-Key is still being processed
                    headers:
                        Idempotency-Key:
                            schema:
                                type: string
                            description: The idempotency key supplied by the client.
                        Retry-After:
                            schema:
                                type: string
                            description: Seconds to wait before retrying the in-flight request.
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - error
                                    - message
                                properties:
                                    error:
                                        type: string
                                    message:
                                        type: string
                "422":
                    description: The Idempotency-Key was already used with a different request body
                    headers:
                        Idempotency-Key:
                            schema:
                                type: string
                            description: The idempotency key supplied by the client.
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - error
                                    - message
                                properties:
                                    error:
                                        type: string
                                    message:
                                        type: string
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/consumer-prices/v1/get-consumer-price-overview:
        get:
            tags:
                - ConsumerPricesService
            summary: GetConsumerPriceOverview
            description: GetConsumerPriceOverview retrieves headline basket indices and coverage metrics.
            operationId: GetConsumerPriceOverview
            parameters:
                - name: market_code
                  in: query
                  description: market_code is the ISO 3166-1 alpha-2 market identifier (e.g. "ae").
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: basket_slug
                  in: query
                  description: basket_slug selects which basket to use (e.g. "essentials-ae").
                  required: false
                  example: "essentials-ae"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "asOf": "1717200000000"
                                "coveragePct": 1.5
                                "currencyCode": "USD"
                                "essentialsIndex": 1.5
                                "freshnessLagMin": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_GetConsumerPriceOverviewResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/consumer-prices/v1/get-consumer-price-basket-series:
        get:
            tags:
                - ConsumerPricesService
            summary: GetConsumerPriceBasketSeries
            description: GetConsumerPriceBasketSeries retrieves the basket index time series.
            operationId: GetConsumerPriceBasketSeries
            parameters:
                - name: market_code
                  in: query
                  description: market_code is the ISO 3166-1 alpha-2 market identifier.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: basket_slug
                  in: query
                  description: basket_slug selects the basket (e.g. "essentials-ae").
                  required: false
                  example: "essentials-ae"
                  schema:
                    type: string
                - name: range
                  in: query
                  description: range is one of "7d", "30d", "90d", "180d".
                  required: false
                  example: "7d"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "asOf": "1717200000000"
                                "basketSlug": "essentials-ae"
                                "currencyCode": "USD"
                                "essentialsSeries":
                                    - "date": "2026-01-15"
                                      "index": 1.5
                                "marketCode": "US"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_GetConsumerPriceBasketSeriesResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: API access requires an active subscription (the API key's subscription is inactive or expired).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/consumer-prices/v1/list-consumer-price-categories:
        get:
            tags:
                - ConsumerPricesService
            summary: ListConsumerPriceCategories
            description: ListConsumerPriceCategories retrieves category summaries with sparklines.
            operationId: ListConsumerPriceCategories
            parameters:
                - name: market_code
                  in: query
                  description: market_code is the ISO 3166-1 alpha-2 market identifier.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: basket_slug
                  in: query
                  description: basket_slug selects the basket scope.
                  required: false
                  example: "essentials-ae"
                  schema:
                    type: string
                - name: range
                  in: query
                  description: range is one of "7d", "30d", "90d", "180d".
                  required: false
                  example: "7d"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "asOf": "1717200000000"
                                "categories":
                                    - "coveragePct": 1.5
                                      "currentIndex": 1.5
                                      "itemCount": 1
                                      "momPct": 1.5
                                      "name": "WorldMonitor Analyst"
                                "marketCode": "US"
                                "range": "7d"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_ListConsumerPriceCategoriesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/consumer-prices/v1/list-consumer-price-movers:
        get:
            tags:
                - ConsumerPricesService
            summary: ListConsumerPriceMovers
            description: ListConsumerPriceMovers retrieves the largest upward and downward item price moves.
            operationId: ListConsumerPriceMovers
            parameters:
                - name: market_code
                  in: query
                  description: market_code is the ISO 3166-1 alpha-2 market identifier.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: range
                  in: query
                  description: range is one of "7d", "30d", "90d".
                  required: false
                  example: "7d"
                  schema:
                    type: string
                - name: limit
                  in: query
                  description: limit caps the number of risers and fallers returned.
                  required: true
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: category_slug
                  in: query
                  description: category_slug filters to a single category when set.
                  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:
                                "asOf": "1717200000000"
                                "fallers":
                                    - "category": "cs.AI"
                                      "changePct": 1.5
                                      "currencyCode": "USD"
                                      "currentPrice": 75.25
                                      "productId": "diesel"
                                "marketCode": "US"
                                "range": "7d"
                                "risers":
                                    - "category": "cs.AI"
                                      "changePct": 1.5
                                      "currencyCode": "USD"
                                      "currentPrice": 75.25
                                      "productId": "diesel"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_ListConsumerPriceMoversResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/consumer-prices/v1/list-retailer-price-spreads:
        get:
            tags:
                - ConsumerPricesService
            summary: ListRetailerPriceSpreads
            description: ListRetailerPriceSpreads retrieves cheapest-basket comparisons across retailers.
            operationId: ListRetailerPriceSpreads
            parameters:
                - name: market_code
                  in: query
                  description: market_code is the ISO 3166-1 alpha-2 market identifier.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: basket_slug
                  in: query
                  description: basket_slug selects which basket to compare across retailers.
                  required: false
                  example: "essentials-ae"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "asOf": "1717200000000"
                                "basketSlug": "essentials-ae"
                                "currencyCode": "USD"
                                "marketCode": "US"
                                "retailers":
                                    - "basketTotal": 1
                                      "currencyCode": "USD"
                                      "deltaVsCheapest": 1.5
                                      "deltaVsCheapestPct": 1.5
                                      "freshnessMin": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_ListRetailerPriceSpreadsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/consumer-prices/v1/get-consumer-price-freshness:
        get:
            tags:
                - ConsumerPricesService
            summary: GetConsumerPriceFreshness
            description: GetConsumerPriceFreshness retrieves feed freshness and coverage health per retailer.
            operationId: GetConsumerPriceFreshness
            parameters:
                - name: market_code
                  in: query
                  description: market_code is the ISO 3166-1 alpha-2 market identifier.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "asOf": "1717200000000"
                                "marketCode": "US"
                                "overallFreshnessMin": 1
                                "retailers":
                                    - "freshnessMin": 1
                                      "lastRunAt": "1717200000000"
                                      "name": "WorldMonitor Analyst"
                                      "parseSuccessRate": 75.25
                                      "slug": "example"
                                "stalledCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_GetConsumerPriceFreshnessResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/cyber/v1/list-cyber-threats:
        get:
            tags:
                - CyberService
            summary: ListCyberThreats
            description: ListCyberThreats retrieves threat indicators from multiple intelligence sources.
            operationId: ListCyberThreats
            parameters:
                - name: start
                  in: query
                  description: |-
                    Start of time range (inclusive), Unix epoch milliseconds.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: end
                  in: query
                  description: |-
                    End of time range (inclusive), Unix epoch milliseconds.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: page_size
                  in: query
                  description: Maximum items per page (1-100).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: Cursor for next page.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: type
                  in: query
                  description: Optional threat type filter.
                  required: false
                  example: "CYBER_THREAT_TYPE_C2_SERVER"
                  schema:
                    type: string
                    enum:
                        - 'CYBER_THREAT_TYPE_C2_SERVER'
                        - 'CYBER_THREAT_TYPE_MALWARE_HOST'
                        - 'CYBER_THREAT_TYPE_PHISHING'
                        - 'CYBER_THREAT_TYPE_MALICIOUS_URL'
                - name: source
                  in: query
                  description: Optional source filter.
                  required: false
                  example: "CYBER_THREAT_SOURCE_FEODO"
                  schema:
                    type: string
                    enum:
                        - 'CYBER_THREAT_SOURCE_FEODO'
                        - 'CYBER_THREAT_SOURCE_URLHAUS'
                        - 'CYBER_THREAT_SOURCE_C2INTEL'
                        - 'CYBER_THREAT_SOURCE_OTX'
                        - 'CYBER_THREAT_SOURCE_ABUSEIPDB'
                - name: min_severity
                  in: query
                  description: Optional minimum criticality filter.
                  required: false
                  example: "CRITICALITY_LEVEL_LOW"
                  schema:
                    type: string
                    enum:
                        - 'CRITICALITY_LEVEL_LOW'
                        - 'CRITICALITY_LEVEL_MEDIUM'
                        - 'CRITICALITY_LEVEL_HIGH'
                        - 'CRITICALITY_LEVEL_CRITICAL'
                - 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:
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                                "threats":
                                    - "country": "US"
                                      "firstSeenAt": 1717200000000
                                      "id": "example-id"
                                      "indicator": "example"
                                      "indicatorType": "CYBER_THREAT_INDICATOR_TYPE_IP"
                                      "lastSeenAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_cyber_v1_ListCyberThreatsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/displacement/v1/get-displacement-summary:
        get:
            tags:
                - DisplacementService
            summary: GetDisplacementSummary
            description: |-
                GetDisplacementSummary retrieves global refugee and IDP statistics from UNHCR.
                 Empty/absent summary with fetched_at=0 or data_available=false means the
                 snapshot is unavailable/degraded, not that global displacement is zero.
            operationId: GetDisplacementSummary
            parameters:
                - name: year
                  in: query
                  description: Data year to retrieve (e.g., 2023). Uses latest available if zero.
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: country_limit
                  in: query
                  description: Maximum number of country entries to return.
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: flow_limit
                  in: query
                  description: Maximum number of displacement flows to return.
                  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:
                                "dataAvailable": true
                                "fetchedAt": 1717200000000
                                "summary":
                                    "countries":
                                        - "asylumSeekers": 1
                                          "code": "US"
                                          "hostAsylumSeekers": 1
                                          "hostRefugees": 1
                                          "hostTotal": 1
                                          "idps": 1
                                    "globalTotals":
                                        "asylumSeekers": 1
                                        "idps": 1
                                        "refugees": 1
                                        "stateless": 1
                                        "total": 1
                                    "topFlows":
                                        - "asylumCode": "US"
                                          "asylumLocation":
                                              "latitude": 40.7128
                                              "longitude": -74.006
                                          "asylumName": "WorldMonitor Analyst"
                                          "originCode": "US"
                                          "originLocation":
                                              "latitude": 40.7128
                                              "longitude": -74.006
                                          "originName": "WorldMonitor Analyst"
                                          "refugees": 1
                                    "year": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_displacement_v1_GetDisplacementSummaryResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/displacement/v1/get-population-exposure:
        get:
            tags:
                - DisplacementService
            summary: GetPopulationExposure
            description: GetPopulationExposure returns country population data or estimates population within a radius.
            operationId: GetPopulationExposure
            parameters:
                - name: mode
                  in: query
                  description: 'Mode: "countries" (default) or "exposure".'
                  required: false
                  example: "countries"
                  schema:
                    type: string
                - name: lat
                  in: query
                  description: Latitude (required for exposure mode).
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: lon
                  in: query
                  description: Longitude (required for exposure mode).
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: radius
                  in: query
                  description: Radius in km (required for exposure mode, defaults to 50).
                  required: false
                  example: 1.5
                  schema:
                    type: number
                    format: double
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "countries":
                                    - "code": "US"
                                      "densityPerKm2": 1
                                      "name": "WorldMonitor Analyst"
                                      "population": 1
                                "exposure":
                                    "densityPerKm2": 1
                                    "exposedPopulation": 1
                                    "exposureRadiusKm": 1.5
                                    "nearestCountry": "US"
                                "success": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_displacement_v1_GetPopulationExposureResponse'
                "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).
                    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'
                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:
        get:
            tags:
                - EconomicService
            summary: GetFredSeries
            description: GetFredSeries retrieves time series data from the Federal Reserve Economic Data.
            operationId: GetFredSeries
            parameters:
                - name: series_id
                  in: query
                  description: FRED series ID (e.g., "GDP", "UNRATE", "CPIAUCSL").
                  required: true
                  example: "GDP"
                  schema:
                    type: string
                - 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/worldmonitor_economic_v1_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).
                    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'
                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: ListWorldBankIndicators retrieves development indicator data from the World Bank.
            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/worldmonitor_economic_v1_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).
                    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'
                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: GetEnergyPrices retrieves current energy commodity prices from EIA.
            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"
                                      "name": "WorldMonitor Analyst"
                                      "price": 75.25
                                      "priceAt": 1717200000000
                                      "unit": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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).
                    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'
                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: GetMacroSignals computes 7 macro signals from 6 upstream sources with BUY/CASH verdict.
            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/worldmonitor_economic_v1_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).
                    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'
                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: GetEnergyCapacity retrieves installed capacity data (solar, wind, coal) from EIA.
            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/worldmonitor_economic_v1_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).
                    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'
                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: GetBisPolicyRates retrieves central bank policy rates from BIS.
            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/worldmonitor_economic_v1_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).
                    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'
                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 effective exchange rates from BIS.
            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/worldmonitor_economic_v1_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).
                    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'
                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 credit-to-GDP ratio data from BIS.
            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/worldmonitor_economic_v1_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).
                    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'
                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: GetFredSeriesBatch retrieves multiple FRED series in a single call.
            operationId: GetFredSeriesBatch
            requestBody:
                content:
                    application/json:
                        example:
                            "limit": 25
                            "seriesIds":
                                - "GDP"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_economic_v1_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/worldmonitor_economic_v1_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).
                    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'
                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 retrieves grocery basket price comparison across 24 countries worldwide.
            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/worldmonitor_economic_v1_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).
                    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'
                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 Big Mac Index prices across Middle East countries.
            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/worldmonitor_economic_v1_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).
                    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'
                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 retrieves national debt clock data for all countries. PRO-gated. Requires an active Pro subscription.
            operationId: GetNationalDebt
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            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": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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: Pro subscription required.
                    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'
                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 retail gasoline and diesel prices across 30+ countries.
            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/worldmonitor_economic_v1_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).
                    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'
                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 retrieves BLS-only series not available on FRED (CES, LAUMT, CIU).
            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/worldmonitor_economic_v1_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).
                    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'
                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 retrieves upcoming major economic events (FOMC, CPI, NFP, etc).
            operationId: GetEconomicCalendar
            parameters:
                - name: fromDate
                  in: query
                  description: Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "2026-01-15"
                  schema:
                    type: string
                - name: toDate
                  in: query
                  description: Accepted but currently ignored; no-op until this handler supports the parameter.
                  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:
                                "events":
                                    - "actual": "example"
                                      "country": "US"
                                      "date": "2026-01-15"
                                      "estimate": "example"
                                      "event": "example"
                                "fromDate": "2026-01-15"
                                "toDate": "2026-01-15"
                                "total": 1
                                "unavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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).
                    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'
                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 crude oil stockpile data from EIA (WCRSTUS1).
            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": "40.7128"
                                "weeks":
                                    - "period": "daily"
                                      "stocksMb": 1.5
                                      "weeklyChangeMb": 1.5
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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).
                    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'
                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": "40.7128"
                                "weeks":
                                    - "period": "daily"
                                      "storBcf": 1.5
                                      "weeklyChangeBcf": 1.5
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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).
                    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'
                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: GetEcbFxRates retrieves daily ECB official reference rates for EUR/major currency pairs.
            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": true
                                "updatedAt": "2026-01-15"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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).
                    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'
                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 per-country CPI, unemployment, and GDP growth for 10 EU member states.
            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": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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).
                    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'
                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 retrieves EU aggregate natural gas storage fill % from GIE AGSI+.
            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/worldmonitor_economic_v1_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).
                    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'
                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 ECB Euro Area AAA sovereign yield curve (Svensson model spot rates).
            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": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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).
                    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'
                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 CISS (Composite Indicator of Systemic Stress) for the Euro area.
            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": "40.7128"
                                "latestValue": 1.5
                                "seededAt": "2026-01-15T12:00:00Z"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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).
                    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'
                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: GetEconomicStress retrieves the composite Economic Stress Index (0-100) from 6 FRED series.
            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": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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).
                    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'
                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 the FAO Food Price Index for the past 12 months.
            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/worldmonitor_economic_v1_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).
                    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'
                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 retrieves the IEA oil stocks days-of-cover ranking and regional summary.
            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": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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).
                    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'
                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/worldmonitor_economic_v1_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).
                    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'
                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 policy responses to the 2026 energy crisis from the IEA tracker.
            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": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_economic_v1_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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/forecast/v1/get-forecasts:
        get:
            tags:
                - ForecastService
            summary: GetForecasts
            description: GetForecasts returns the latest generated probabilistic forecasts; the degraded flag distinguishes a backend outage from a healthy empty set.
            operationId: GetForecasts
            parameters:
                - name: domain
                  in: query
                  description: Forecast domain to retrieve, such as geopolitics, markets, or climate.
                  required: false
                  example: "conflict"
                  schema:
                    type: string
                    enum:
                        - 'conflict'
                        - 'market'
                        - 'supply_chain'
                        - 'political'
                        - 'military'
                        - 'cyber'
                        - 'infrastructure'
                - name: region
                  in: query
                  description: Optional geographic or thematic region filter for forecasts.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "degraded": true
                                "error": "example"
                                "forecasts":
                                    - "calibration":
                                        "drift": 1.5
                                        "marketPrice": 75.25
                                        "marketTitle": "example"
                                        "source": "example"
                                      "cascades":
                                          - "domain": "example"
                                            "effect": "example"
                                            "probability": 1.5
                                      "caseFile":
                                          "actorLenses":
                                              - "example"
                                          "actors":
                                              - "category": "cs.AI"
                                                "constraints":
                                                    - "example"
                                                "id": "example-id"
                                                "influenceScore": 42.5
                                                "likelyActions":
                                                    - "example"
                                          "baseCase": "example"
                                          "branches":
                                              - "kind": "example"
                                                "outcome": "example"
                                                "projectedProbability": 1.5
                                                "rounds":
                                                    - {}
                                                "summary": "Example WorldMonitor observation."
                                          "changeItems":
                                              - "example"
                                      "confidence": 0.82
                                      "createdAt": 1717200000000
                                "generatedAt": 1717200000000
                                "stale": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_forecast_v1_GetForecastsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/forecast/v1/get-forecast-scorecard:
        get:
            tags:
                - ForecastService
            summary: GetForecastScorecard
            description: GetForecastScorecard returns the latest forecast resolution scorecard; degraded distinguishes a backend outage from a healthy empty scorecard.
            operationId: GetForecastScorecard
            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:
                                "byDomain":
                                    - "brier": 1.5
                                      "domain": "example"
                                      "logScore": 42.5
                                      "resolved": 1
                                      "scored": 42
                                "byGenerationOrigin":
                                    - "brier": 1.5
                                      "generationOrigin": "example"
                                      "logScore": 42.5
                                      "resolved": 1
                                      "scored": 42
                                "calibration":
                                    - "brier": 1.5
                                      "bucket": "example"
                                      "count": 1
                                      "maxProbability": 1.5
                                      "minProbability": 1.5
                                "degraded": true
                                "error": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_forecast_v1_GetForecastScorecardResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/forecast/v1/get-simulation-package:
        get:
            tags:
                - ForecastService
            summary: GetSimulationPackage
            description: GetSimulationPackage returns the latest forecast simulation package; the response note is populated when a supplied runId does not match the returned package.
            operationId: GetSimulationPackage
            parameters:
                - name: runId
                  in: query
                  description: |-
                    Optional run identifier. Does not select the package — the latest stored package is
                     always returned regardless of this value. When supplied and it differs from the
                     returned package's runId, the response `note` field is populated to warn that per-run
                     filtering is not yet active. Reserved for Phase 3 per-run lookup.
                  required: false
                  example: "example-id"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "error": "example"
                                "found": true
                                "generatedAt": 1717200000000
                                "note": "example"
                                "runId": "example-id"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_forecast_v1_GetSimulationPackageResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/forecast/v1/get-simulation-outcome:
        get:
            tags:
                - ForecastService
            summary: GetSimulationOutcome
            description: GetSimulationOutcome returns the latest stored forecast simulation outcome; the response note is populated when a supplied runId does not match the returned outcome.
            operationId: GetSimulationOutcome
            parameters:
                - name: runId
                  in: query
                  description: |-
                    Filter is active for outcomes within the 24h retention window (#3734).
                     If runId is supplied:
                       - Hit on the by-run key → returns that outcome, processing=false.
                       - By-run lookup returns the tombstone (worker write transiently failed) →
                         falls through to :latest with a 'note' describing the transient failure.
                       - No by-run match but runId is in the queue → returns processing=true.
                       - No match anywhere → falls back to :latest with a 'note' describing
                         expiry-or-mismatch.
                     If runId is empty: returns :latest (existing behavior).
                  required: false
                  example: "example-id"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "allTheatersFailed": true
                                "completionStatus": "example"
                                "eligibleTheaterCount": 1
                                "error": "example"
                                "failedTheaterCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_forecast_v1_GetSimulationOutcomeResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/forecast/v1/trigger-simulation:
        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:
                - ForecastService
            summary: TriggerSimulation
            description: |-
                TriggerSimulation enqueues a simulation task for the current
                 SIMULATION_PACKAGE_LATEST_KEY package pointer. PRO-gated. The runId
                 is server-derived; callers cannot supply one. The Railway worker
                 (scripts/process-simulation-tasks.mjs) polls the queue and writes
                 outcomes; callers poll GetSimulationOutcome with the returned runId
                 to retrieve the result. Mirrors run-scenario.ts pattern. See #3734. Requires entitlement tier >= 1.
            operationId: TriggerSimulation
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            requestBody:
                content:
                    application/json:
                        example:
                            "clientVersion": "example"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_forecast_v1_TriggerSimulationRequest'
                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:
                                "pkgFingerprint": "example"
                                "queued": true
                                "reason": "example"
                                "runId": "example-id"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_forecast_v1_TriggerSimulationResponse'
                "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: PRO entitlement access denied.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/giving/v1/get-giving-summary:
        get:
            tags:
                - GivingService
            summary: GetGivingSummary
            description: |-
                GetGivingSummary retrieves a composite global giving activity index and platform breakdowns.
                 Empty/absent summary with fetched_at=0 or data_available=false means the
                 snapshot is unavailable/degraded, not that giving activity is zero.
            operationId: GetGivingSummary
            parameters:
                - name: platform_limit
                  in: query
                  description: Number of platforms to include (0 = all).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: category_limit
                  in: query
                  description: Number of category breakdowns to include (0 = all).
                  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:
                                "dataAvailable": true
                                "fetchedAt": 1717200000000
                                "summary":
                                    "activityIndex": 1.5
                                    "categories":
                                        - "activeCampaigns": 1
                                          "category": "cs.AI"
                                          "change24h": 1.5
                                          "share": 1.5
                                          "trending": true
                                    "crypto":
                                        "dailyInflowUsd": 1.5
                                        "pctOfTotal": 1
                                        "topReceivers":
                                            - "example"
                                        "trackedWallets": 1
                                        "transactions24h": 1
                                    "estimatedDailyFlowUsd": 1.5
                                    "generatedAt": "2026-01-15T12:00:00Z"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_giving_v1_GetGivingSummaryResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/health/v1/list-disease-outbreaks:
        get:
            tags:
                - HealthService
            summary: ListDiseaseOutbreaks
            description: ListDiseaseOutbreaks returns recent WHO/ProMED disease outbreak alerts.
            operationId: ListDiseaseOutbreaks
            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:
                                "alertLevelMethodologyVersion": "example"
                                "fetchedAt": 1717200000000
                                "outbreaks":
                                    - "alertLevel": "example"
                                      "cases": 1
                                      "countryCode": "US"
                                      "disease": "example"
                                      "id": "example-id"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_health_v1_ListDiseaseOutbreaksResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/health/v1/list-air-quality-alerts:
        get:
            tags:
                - HealthService
            summary: ListAirQualityAlerts
            description: ListAirQualityAlerts returns recent PM2.5 stations with AQI-derived health risk.
            operationId: ListAirQualityAlerts
            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:
                                "alerts":
                                    - "aqi": 1
                                      "city": "example"
                                      "countryCode": "US"
                                      "lat": 40.7128
                                      "lng": -74.006
                                "fetchedAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_health_v1_ListAirQualityAlertsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/imagery/v1/search-imagery:
        get:
            tags:
                - ImageryService
            summary: SearchImagery
            description: SearchImagery searches satellite imagery scenes by bounding box, datetime range, and source, returning matching scenes and a total-results count.
            operationId: SearchImagery
            parameters:
                - name: bbox
                  in: query
                  description: Bounding box filter for imagery search, encoded as west,south,east,north.
                  required: false
                  example: "-74.10,40.60,-73.70,40.90"
                  schema:
                    type: string
                - name: datetime
                  in: query
                  description: ISO 8601 datetime or datetime range for matching imagery scenes.
                  required: false
                  example: "2026-01-15"
                  schema:
                    type: string
                - name: source
                  in: query
                  description: Optional imagery source filter, such as satellite or provider name.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: limit
                  in: query
                  description: Maximum number of imagery scenes to return.
                  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:
                                "cacheHit": true
                                "scenes":
                                    - "assetUrl": "https://example.com/worldmonitor"
                                      "datetime": "2026-01-15"
                                      "geometryGeojson": "example"
                                      "id": "example-id"
                                      "mode": "example"
                                "totalResults": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_imagery_v1_SearchImageryResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/infrastructure/v1/list-internet-outages:
        get:
            tags:
                - InfrastructureService
            summary: ListInternetOutages
            description: ListInternetOutages retrieves detected internet outages from Cloudflare Radar.
            operationId: ListInternetOutages
            parameters:
                - name: start
                  in: query
                  description: Start of time range (inclusive), Unix epoch milliseconds.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: end
                  in: query
                  description: End of time range (inclusive), Unix epoch milliseconds.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: page_size
                  in: query
                  description: |-
                    Maximum items per page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: country
                  in: query
                  description: Optional country filter (ISO 3166-1 alpha-2).
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "outages":
                                    - "categories":
                                        - "example"
                                      "cause": "example"
                                      "country": "US"
                                      "description": "Example WorldMonitor observation."
                                      "detectedAt": 1717200000000
                                      "id": "example-id"
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_infrastructure_v1_ListInternetOutagesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/infrastructure/v1/list-service-statuses:
        get:
            tags:
                - InfrastructureService
            summary: ListServiceStatuses
            description: ListServiceStatuses retrieves operational status of monitored external services.
            operationId: ListServiceStatuses
            parameters:
                - name: status
                  in: query
                  description: Optional status filter. Returns only services in this state.
                  required: false
                  example: "SERVICE_OPERATIONAL_STATUS_OPERATIONAL"
                  schema:
                    type: string
                    enum:
                        - 'SERVICE_OPERATIONAL_STATUS_OPERATIONAL'
                        - 'SERVICE_OPERATIONAL_STATUS_DEGRADED'
                        - 'SERVICE_OPERATIONAL_STATUS_PARTIAL_OUTAGE'
                        - 'SERVICE_OPERATIONAL_STATUS_MAJOR_OUTAGE'
                        - 'SERVICE_OPERATIONAL_STATUS_MAINTENANCE'
                - 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:
                                "statuses":
                                    - "checkedAt": 1717200000000
                                      "description": "Example WorldMonitor observation."
                                      "id": "example-id"
                                      "latencyMs": 1
                                      "name": "WorldMonitor Analyst"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_infrastructure_v1_ListServiceStatusesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/infrastructure/v1/get-temporal-baseline:
        get:
            tags:
                - InfrastructureService
            summary: GetTemporalBaseline
            description: GetTemporalBaseline retrieves historical baseline data for a specific signal.
            operationId: GetTemporalBaseline
            parameters:
                - name: type
                  in: query
                  description: 'Activity type: "military_flights", "vessels", "protests", "news", "ais_gaps", "satellite_fires".'
                  required: true
                  example: "military_flights"
                  schema:
                    type: string
                    enum:
                        - 'military_flights'
                        - 'vessels'
                        - 'protests'
                        - 'news'
                        - 'ais_gaps'
                        - 'satellite_fires'
                - name: region
                  in: query
                  description: Geographic region key, defaults to "global".
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: count
                  in: query
                  description: Current observed count to compare against baseline.
                  required: false
                  example: 1
                  schema:
                    type: number
                    format: double
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "anomaly":
                                    "multiplier": 1.5
                                    "severity": "watch"
                                    "zScore": 42.5
                                "baseline":
                                    "mean": 1.5
                                    "sampleCount": 1
                                    "stdDev": 1.5
                                "error": "example"
                                "learning": true
                                "sampleCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_infrastructure_v1_GetTemporalBaselineResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/infrastructure/v1/get-ip-geo:
        get:
            tags:
                - InfrastructureService
            summary: GetIpGeo
            description: GetIpGeo retrieves geographic information based on the caller's IP address.
            operationId: GetIpGeo
            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:
                                "city": "example"
                                "country": "US"
                                "region": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_infrastructure_v1_GetIpGeoResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/infrastructure/v1/reverse-geocode:
        get:
            tags:
                - InfrastructureService
            summary: ReverseGeocode
            description: ReverseGeocode resolves geographic coordinates to a postal address/country.
            operationId: ReverseGeocode
            parameters:
                - name: lat
                  in: query
                  description: Latitude of the point to reverse geocode.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: lon
                  in: query
                  description: Longitude of the point to reverse geocode.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "code": "example"
                                "country": "US"
                                "displayName": "WorldMonitor Analyst"
                                "error": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_infrastructure_v1_ReverseGeocodeResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/infrastructure/v1/get-bootstrap-data:
        get:
            tags:
                - InfrastructureService
            summary: GetBootstrapData
            description: GetBootstrapData fetches multiple data points from the system cache in a single call.
            operationId: GetBootstrapData
            parameters:
                - name: tier
                  in: query
                  description: Predefined tiers or specific keys.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: keys
                  in: query
                  description: Specific bootstrap cache keys to fetch when tier is not sufficient.
                  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:
                                "data":
                                    "exampleKey": "example"
                                "missing":
                                    - "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_infrastructure_v1_GetBootstrapDataResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/infrastructure/v1/record-baseline-snapshot:
        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:
                - InfrastructureService
            summary: RecordBaselineSnapshot
            description: RecordBaselineSnapshot batch-updates baseline statistics using Welford's online algorithm.
            operationId: RecordBaselineSnapshot
            requestBody:
                content:
                    application/json:
                        example:
                            "updates":
                                - "count": 1
                                  "region": "example"
                                  "type": "military_flights"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_infrastructure_v1_RecordBaselineSnapshotRequest'
                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:
                                "error": "example"
                                "updated": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_infrastructure_v1_RecordBaselineSnapshotResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/infrastructure/v1/get-cable-health:
        get:
            tags:
                - InfrastructureService
            summary: GetCableHealth
            description: GetCableHealth computes health status for submarine cables from NGA maritime warning signals.
            operationId: GetCableHealth
            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:
                                "cables":
                                    "exampleKey":
                                        "confidence": 0.82
                                        "evidence":
                                            - "source": "example"
                                              "summary": "Example WorldMonitor observation."
                                              "ts": 1
                                        "lastUpdated": 1
                                        "score": 42.5
                                        "status": "CABLE_HEALTH_STATUS_OK"
                                "generatedAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_infrastructure_v1_GetCableHealthResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/infrastructure/v1/list-temporal-anomalies:
        get:
            tags:
                - InfrastructureService
            summary: ListTemporalAnomalies
            description: ListTemporalAnomalies returns server-computed temporal anomalies for news and satellite_fires.
            operationId: ListTemporalAnomalies
            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:
                                "anomalies":
                                    - "currentCount": 1
                                      "expectedCount": 1
                                      "message": "Example WorldMonitor observation."
                                      "multiplier": 1.5
                                      "region": "example"
                                "computedAt": "2026-01-15T12:00:00Z"
                                "trackedTypes":
                                    - "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_infrastructure_v1_ListTemporalAnomaliesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/infrastructure/v1/list-internet-ddos-attacks:
        get:
            tags:
                - InfrastructureService
            summary: ListInternetDdosAttacks
            description: ListInternetDdosAttacks retrieves L3/L4 DDoS attack summaries from Cloudflare Radar.
            operationId: ListInternetDdosAttacks
            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:
                                "dateRangeEnd": "2026-01-15"
                                "dateRangeStart": "2026-01-15"
                                "protocol":
                                    - "label": "example"
                                      "percentage": 42.5
                                "topTargetLocations":
                                    - "countryCode": "US"
                                      "countryName": "US"
                                      "latitude": 40.7128
                                      "longitude": -74.006
                                      "percentage": 42.5
                                "vector":
                                    - "label": "example"
                                      "percentage": 42.5
                            schema:
                                $ref: '#/components/schemas/worldmonitor_infrastructure_v1_ListInternetDdosAttacksResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/infrastructure/v1/list-internet-traffic-anomalies:
        get:
            tags:
                - InfrastructureService
            summary: ListInternetTrafficAnomalies
            description: ListInternetTrafficAnomalies retrieves traffic anomaly events from Cloudflare Radar.
            operationId: ListInternetTrafficAnomalies
            parameters:
                - name: country
                  in: query
                  description: Optional ISO 3166-1 alpha-2 country code filter.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "anomalies":
                                    - "asn": "example"
                                      "asnName": "WorldMonitor Analyst"
                                      "endDate": 1
                                      "latitude": 40.7128
                                      "locationCode": "US"
                                "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_infrastructure_v1_ListInternetTrafficAnomaliesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-risk-scores:
        get:
            tags:
                - IntelligenceService
            summary: GetRiskScores
            description: GetRiskScores retrieves composite risk scores and strategic assessments.
            operationId: GetRiskScores
            parameters:
                - name: region
                  in: query
                  description: Optional region filter. Empty returns all tracked regions.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "ciiScores":
                                    - "advisoryLevel": "example"
                                      "advisoryProvenance": "live"
                                      "combinedScore": 42.5
                                      "components":
                                          "ciiContribution": 1.5
                                          "geoConvergence": 1.5
                                          "militaryActivity": 1.5
                                          "newsActivity": 1.5
                                      "computedAt": 1717200000000
                                "degraded": true
                                "stale": true
                                "strategicRisks":
                                    - "factors":
                                        - "example"
                                      "level": "SEVERITY_LEVEL_LOW"
                                      "region": "example"
                                      "score": 42.5
                                      "trend": "TREND_DIRECTION_RISING"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetRiskScoresResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-pizzint-status:
        get:
            tags:
                - IntelligenceService
            summary: GetPizzintStatus
            description: GetPizzintStatus retrieves Pentagon Pizza Index and GDELT tension data.
            operationId: GetPizzintStatus
            parameters:
                - name: include_gdelt
                  in: query
                  description: Whether to include GDELT tension pairs in the response.
                  required: false
                  example: true
                  schema:
                    type: boolean
                - 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:
                                "pizzint":
                                    "activeSpikes": 1
                                    "aggregateActivity": 1.5
                                    "dataFreshness": "DATA_FRESHNESS_FRESH"
                                    "defconLabel": "example"
                                    "defconLevel": 1
                                "tensionPairs":
                                    - "changePercent": 42.5
                                      "countries":
                                          - "US"
                                      "id": "example-id"
                                      "label": "example"
                                      "region": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetPizzintStatusResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/classify-event:
        get:
            tags:
                - IntelligenceService
            summary: ClassifyEvent
            description: ClassifyEvent analyzes a news event using AI models. PRO-gated. Requires entitlement tier >= 1.
            operationId: ClassifyEvent
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: title
                  in: query
                  description: Event title or headline.
                  required: true
                  example: "example"
                  schema:
                    type: string
                - name: description
                  in: query
                  description: Event description or body text.
                  required: false
                  example: "Example WorldMonitor observation."
                  schema:
                    type: string
                - name: source
                  in: query
                  description: Event source (e.g., "reuters", "acled").
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: country
                  in: query
                  description: Country context (ISO 3166-1 alpha-2).
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "classification":
                                    "analysis": "example"
                                    "category": "cs.AI"
                                    "confidence": 0.82
                                    "entities":
                                        - "example"
                                    "severity": "SEVERITY_LEVEL_LOW"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_ClassifyEventResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-country-risk:
        get:
            tags:
                - IntelligenceService
            summary: GetCountryRisk
            description: GetCountryRisk retrieves composite risk intelligence for a specific country.
            operationId: GetCountryRisk
            parameters:
                - name: country_code
                  in: query
                  description: ISO 3166-1 alpha-2 country code.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - 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:
                                "advisoryLevel": "example"
                                "cii":
                                    "advisoryLevel": "example"
                                    "advisoryProvenance": "live"
                                    "combinedScore": 42.5
                                    "components":
                                        "ciiContribution": 1.5
                                        "geoConvergence": 1.5
                                        "militaryActivity": 1.5
                                        "newsActivity": 1.5
                                    "computedAt": 1717200000000
                                "countryCode": "US"
                                "countryName": "US"
                                "fetchedAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetCountryRiskResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-country-intel-brief:
        get:
            tags:
                - IntelligenceService
            summary: GetCountryIntelBrief
            description: GetCountryIntelBrief generates a strategic brief for a specific country.
            operationId: GetCountryIntelBrief
            parameters:
                - name: country_code
                  in: query
                  description: ISO 3166-1 alpha-2 country code.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: framework
                  in: query
                  description: Optional analytical framework instructions to append to system prompt. Max 2000 chars enforced at handler level.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "brief": "example"
                                "countryCode": "US"
                                "countryName": "US"
                                "generatedAt": 1717200000000
                                "model": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetCountryIntelBriefResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/search-gdelt-documents:
        get:
            tags:
                - IntelligenceService
            summary: SearchGdeltDocuments
            description: SearchGdeltDocuments searches the GDELT GKG API for relevant documentation.
            operationId: SearchGdeltDocuments
            parameters:
                - name: query
                  in: query
                  description: Search query string.
                  required: true
                  example: "supply chain risk"
                  schema:
                    type: string
                - name: max_records
                  in: query
                  description: |-
                    Maximum number of articles to return. Defaults to 10 when omitted or <= 0. The
                     handler caps returned results at 20, so values above 20 (though accepted, up to the
                     validation limit of 250) still return at most 20 articles.
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: timespan
                  in: query
                  description: |-
                    Time span filter (e.g., "15min", "1h", "24h").
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "15min"
                  schema:
                    type: string
                - name: tone_filter
                  in: query
                  description: |-
                    Tone filter appended to query (e.g., "tone>5" for positive, "tone<-5" for negative).
                     Left empty to skip tone filtering.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: sort
                  in: query
                  description: |-
                    Sort mode: "DateDesc" (default), "ToneDesc", "ToneAsc", "HybridRel".
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "DateDesc"
                  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:
                                "articles":
                                    - "date": "2026-01-15"
                                      "image": "example"
                                      "language": "typescript"
                                      "source": "example"
                                      "title": "example"
                                "error": "example"
                                "query": "supply chain risk"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_SearchGdeltDocumentsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/deduct-situation:
        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:
                - IntelligenceService
            summary: DeductSituation
            description: DeductSituation performs broad situational analysis using LLMs. PRO-gated. Requires an active Pro subscription.
            operationId: DeductSituation
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            requestBody:
                content:
                    application/json:
                        example:
                            "framework": "example"
                            "geoContext": "example"
                            "query": "supply chain risk"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_intelligence_v1_DeductSituationRequest'
                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:
                                "analysis": "example"
                                "model": "example"
                                "provider": "worldmonitor"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_DeductSituationResponse'
                "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: Pro subscription required.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/list-satellites:
        get:
            tags:
                - IntelligenceService
            summary: ListSatellites
            description: ListSatellites retrieves current orbital positions and metadata.
            operationId: ListSatellites
            parameters:
                - name: country
                  in: query
                  description: Filter by country code. Empty returns all.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "satellites":
                                    - "alt": 1.5
                                      "country": "US"
                                      "id": "example-id"
                                      "inclination": 1.5
                                      "line1": "example"
                                      "line2": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_ListSatellitesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/list-gps-interference:
        get:
            tags:
                - IntelligenceService
            summary: ListGpsInterference
            description: ListGpsInterference retrieves detected GPS/GNSS interference data (jamming).
            operationId: ListGpsInterference
            parameters:
                - name: region
                  in: query
                  description: Optional region filter.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "fetchedAt": 1717200000000
                                "hexes":
                                    - "aircraftCount": 1
                                      "h3": "example"
                                      "lat": 40.7128
                                      "level": "INTERFERENCE_LEVEL_LOW"
                                      "lon": -74.006
                                      "npAvg": 1.5
                                "source": "example"
                                "stats":
                                    "highCount": 1
                                    "mediumCount": 1
                                    "totalHexes": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_ListGpsInterferenceResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/list-oref-alerts:
        get:
            tags:
                - IntelligenceService
            summary: ListOrefAlerts
            description: ListOrefAlerts retrieves Israeli Home Front Command alerts (Red Alerts).
            operationId: ListOrefAlerts
            parameters:
                - name: mode
                  in: query
                  description: Mode selection. MODE_UNSPECIFIED defaults to active alerts.
                  required: false
                  example: "MODE_HISTORY"
                  schema:
                    type: string
                    enum:
                        - 'MODE_HISTORY'
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "alerts":
                                    - "cat": "2026-01-15T12:00:00Z"
                                      "data":
                                          - "example"
                                      "desc": "example"
                                      "id": "example-id"
                                      "timestampMs": 1717200000000
                                "configured": true
                                "error": "example"
                                "history":
                                    - "alerts":
                                        - "cat": "2026-01-15T12:00:00Z"
                                          "data":
                                              - "example"
                                          "desc": "example"
                                          "id": "example-id"
                                          "timestampMs": 1717200000000
                                      "timestampMs": 1717200000000
                                "historyCount24h": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_ListOrefAlertsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/list-telegram-feed:
        get:
            tags:
                - IntelligenceService
            summary: ListTelegramFeed
            description: ListTelegramFeed retrieves real-time OSINT messages from monitored Telegram channels.
            operationId: ListTelegramFeed
            parameters:
                - name: limit
                  in: query
                  description: Maximum number of messages to return (default 50).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: topic
                  in: query
                  description: Filter by topic keyword (e.g. "military", "cyber").
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: channel
                  in: query
                  description: Filter by specific channel ID or name.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "count": 1
                                "enabled": true
                                "error": "example"
                                "messages":
                                    - "channelId": "example-id"
                                      "channelName": "WorldMonitor Analyst"
                                      "id": "example-id"
                                      "mediaUrls":
                                          - "https://example.com/worldmonitor"
                                      "sourceUrl": "https://example.com/worldmonitor"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_ListTelegramFeedResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-company-enrichment:
        get:
            deprecated: true
            tags:
                - IntelligenceService
            summary: GetCompanyEnrichment
            description: |-
                GetCompanyEnrichment is DISABLED and returns an empty stub. The route is preserved
                 for contract stability, but the handler no longer aggregates any external data
                 (the prior domain-slug attribution heuristic was unsound). Deprecated pending a
                 verified attribution model.
            operationId: GetCompanyEnrichment
            parameters:
                - name: domain
                  in: query
                  description: Company domain to enrich, such as "github.com".
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: name
                  in: query
                  description: Company name to enrich when a domain is not available.
                  required: false
                  example: "WorldMonitor Analyst"
                  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:
                                "company":
                                    "description": "Example WorldMonitor observation."
                                    "domain": "example"
                                    "founded": 1
                                    "location": "example"
                                    "name": "WorldMonitor Analyst"
                                "enrichedAtMs": 1
                                "github":
                                    "avatarUrl": "https://example.com/worldmonitor"
                                    "followers": 1
                                    "publicRepos": 1
                                "hackerNewsMentions":
                                    - "comments": 1
                                      "createdAtMs": 1
                                      "points": 1
                                      "title": "example"
                                      "url": "https://example.com/worldmonitor"
                                "secFilings":
                                    "recentFilings":
                                        - "description": "Example WorldMonitor observation."
                                          "fileDate": "2026-01-15"
                                          "form": "example"
                                    "totalFilings": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetCompanyEnrichmentResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/list-company-signals:
        get:
            deprecated: true
            tags:
                - IntelligenceService
            summary: ListCompanySignals
            description: |-
                ListCompanySignals is DISABLED and returns an empty stub. The route is preserved
                 for contract stability, but the handler no longer discovers any signals (the prior
                 guessed-identity/keyword heuristic was unsound). Deprecated pending a verified
                 attribution model.
            operationId: ListCompanySignals
            parameters:
                - name: company
                  in: query
                  description: Company name to discover signals for.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: domain
                  in: query
                  description: Company domain to discover signals for.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "company": "example"
                                "discoveredAtMs": 1
                                "domain": "example"
                                "signals":
                                    - "engagement":
                                        "comments": 1
                                        "forks": 1
                                        "mentions": 1
                                        "points": 1
                                        "stars": 1
                                      "source": "example"
                                      "sourceTier": 1
                                      "strength": "example"
                                      "timestampMs": 1717200000000
                                "summary":
                                    "byType":
                                        "exampleKey": 1
                                    "signalDiversity": 1
                                    "strongestSignal":
                                        "engagement":
                                            "comments": 1
                                            "forks": 1
                                            "mentions": 1
                                            "points": 1
                                            "stars": 1
                                        "source": "example"
                                        "sourceTier": 1
                                        "strength": "example"
                                        "timestampMs": 1717200000000
                                    "totalSignals": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_ListCompanySignalsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-country-facts:
        get:
            tags:
                - IntelligenceService
            summary: GetCountryFacts
            description: GetCountryFacts retrieves factual country data from RestCountries and Wikipedia.
            operationId: GetCountryFacts
            parameters:
                - name: country_code
                  in: query
                  description: ISO 3166-1 alpha-2 country code for the facts lookup.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - 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:
                                "areaSqKm": 1.5
                                "capital": "example"
                                "countryName": "US"
                                "currencies":
                                    - "example"
                                "headOfState": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetCountryFactsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/list-security-advisories:
        get:
            tags:
                - IntelligenceService
            summary: ListSecurityAdvisories
            description: ListSecurityAdvisories retrieves pre-seeded travel and health advisories.
            operationId: ListSecurityAdvisories
            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:
                                "advisories":
                                    - "country": "US"
                                      "level": "example"
                                      "link": "https://example.com/worldmonitor"
                                      "pubDate": "2026-01-15"
                                      "source": "example"
                                "byCountry":
                                    "exampleKey": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_ListSecurityAdvisoriesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-gdelt-topic-timeline:
        get:
            tags:
                - IntelligenceService
            summary: GetGdeltTopicTimeline
            description: GetGdeltTopicTimeline retrieves tone and volume timelines for a GDELT intel topic.
            operationId: GetGdeltTopicTimeline
            parameters:
                - name: topic
                  in: query
                  description: Topic ID (military, cyber, nuclear, sanctions, intelligence, maritime).
                  required: false
                  example: "military"
                  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:
                                "error": "example"
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "tone":
                                    - "date": "2026-01-15"
                                      "value": 1.5
                                "topic": "military"
                                "vol":
                                    - "date": "2026-01-15"
                                      "value": 1.5
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetGdeltTopicTimelineResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/list-cross-source-signals:
        get:
            tags:
                - IntelligenceService
            summary: ListCrossSourceSignals
            description: ListCrossSourceSignals returns cross-domain signals ranked by severity with composite escalation detection.
            operationId: ListCrossSourceSignals
            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:
                                "compositeCount": 1
                                "evaluatedAt": 1717200000000
                                "signals":
                                    - "contributingTypes":
                                        - "example"
                                      "detectedAt": 1717200000000
                                      "id": "example-id"
                                      "severity": "CROSS_SOURCE_SIGNAL_SEVERITY_LOW"
                                      "severityScore": 42.5
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_ListCrossSourceSignalsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/list-market-implications:
        get:
            tags:
                - IntelligenceService
            summary: ListMarketImplications
            description: ListMarketImplications returns AI-generated trade-implication cards from live world state. PRO-gated. Requires an active Pro subscription.
            operationId: ListMarketImplications
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: frameworkId
                  in: query
                  description: Framework identifier whose market implication cards should be listed.
                  required: false
                  example: "example-id"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "cards":
                                    - "confidence": "example"
                                      "direction": "example"
                                      "driver": "example"
                                      "name": "WorldMonitor Analyst"
                                      "narrative": "example"
                                "degraded": true
                                "emptyReason": "example"
                                "generatedAt": "2026-01-15T12:00:00Z"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_ListMarketImplicationsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: Pro subscription required.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-social-velocity:
        get:
            tags:
                - IntelligenceService
            summary: GetSocialVelocity
            description: GetSocialVelocity returns trending Reddit posts from r/worldnews and r/geopolitics ranked by velocity.
            operationId: GetSocialVelocity
            parameters:
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "fetchedAt": 1717200000000
                                "posts":
                                    - "createdAt": 1717200000000
                                      "id": "example-id"
                                      "numComments": 1
                                      "score": 42
                                      "subreddit": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetSocialVelocityResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-country-energy-profile:
        get:
            tags:
                - IntelligenceService
            summary: GetCountryEnergyProfile
            description: GetCountryEnergyProfile aggregates Phase 1/2/2.5 energy data per country.
            operationId: GetCountryEnergyProfile
            parameters:
                - name: country_code
                  in: query
                  description: ISO 3166-1 alpha-2 country code for the energy profile.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "coalShare": 1.5
                                "crudeImportsKbd": 1.5
                                "dieselDemandKbd": 1.5
                                "dieselImportsKbd": 1.5
                                "electricityAvailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetCountryEnergyProfileResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/compute-energy-shock:
        get:
            tags:
                - IntelligenceService
            summary: ComputeEnergyShockScenario
            description: ComputeEnergyShockScenario computes on-demand product supply shock for a given country + chokepoint.
            operationId: ComputeEnergyShockScenario
            parameters:
                - name: country_code
                  in: query
                  description: ISO 3166-1 alpha-2 country code for the affected energy market.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: chokepoint_id
                  in: query
                  description: Chokepoint identifier to model as disrupted.
                  required: false
                  example: "hormuz_strait"
                  schema:
                    type: string
                    enum:
                        - 'hormuz_strait'
                        - 'malacca_strait'
                        - 'suez'
                        - 'bab_el_mandeb'
                - name: disruption_pct
                  in: query
                  description: Percent of chokepoint flow disrupted, from 0 to 100.
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: fuel_mode
                  in: query
                  description: 'Fuel mode to model: "oil", "gas", or "both". Defaults to "oil".'
                  required: false
                  example: "oil"
                  schema:
                    type: string
                    enum:
                        - 'oil'
                        - 'gas'
                        - 'both'
                - 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:
                                "assessment": "example"
                                "chokepointConfidence": "example"
                                "chokepointId": "hormuz_strait"
                                "comtradeCoverage": true
                                "countryCode": "US"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_ComputeEnergyShockScenarioResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-country-port-activity:
        get:
            tags:
                - IntelligenceService
            summary: GetCountryPortActivity
            description: GetCountryPortActivity returns port-level tanker traffic and trade volumes for a country.
            operationId: GetCountryPortActivity
            parameters:
                - name: country_code
                  in: query
                  description: ISO 3166-1 alpha-2 country code for port activity.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "available": true
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "ports":
                                    - "anomalySignal": true
                                      "exportTankerDwt": 1.5
                                      "importTankerDwt": 1.5
                                      "lat": 40.7128
                                      "lon": -74.006
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_CountryPortActivityResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-regional-snapshot:
        get:
            tags:
                - IntelligenceService
            summary: GetRegionalSnapshot
            description: |-
                GetRegionalSnapshot returns the latest persisted RegionalSnapshot for a
                 region. The snapshot is written every 6h by scripts/seed-regional-snapshots.mjs;
                 this handler only reads canonical state. Premium-gated. PRO-gated. Requires an active Pro subscription.
            operationId: GetRegionalSnapshot
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: region_id
                  in: query
                  description: |-
                    Display region id (e.g. "mena", "east-asia", "europe"). See shared/geography.js.
                     Kebab-case: lowercase alphanumeric groups separated by single hyphens, no
                     trailing or consecutive hyphens.
                  required: true
                  example: "mena"
                  schema:
                    type: string
                    pattern: '^[a-z][a-z0-9]*(-[a-z0-9]+)*$'
                - 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:
                                "snapshot":
                                    "actors":
                                        - "actorId": "example-id"
                                          "delta": 1.5
                                          "evidenceIds":
                                              - "example"
                                          "leverageDomains":
                                              - "example"
                                          "leverageScore": 42.5
                                    "balance":
                                        "allianceCohesion": 1.5
                                        "buffers":
                                            - "axis": "example"
                                              "description": "Example WorldMonitor observation."
                                              "evidenceIds":
                                                  - "example"
                                              "magnitude": 1.5
                                              "orientation": "example"
                                        "capitalStress": 1.5
                                        "coercivePressure": 1.5
                                        "domesticFragility": 1.5
                                    "evidence":
                                        - "confidence": 0.82
                                          "corridor": "example"
                                          "id": "example-id"
                                          "observedAt": 1717200000000
                                          "source": "example"
                                    "generatedAt": 1717200000000
                                    "leverageEdges":
                                        - "evidenceIds":
                                            - "example"
                                          "fromActorId": "example-id"
                                          "mechanism": "example"
                                          "strength": 1.5
                                          "toActorId": "example-id"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetRegionalSnapshotResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: Pro subscription required.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-regime-history:
        get:
            tags:
                - IntelligenceService
            summary: GetRegimeHistory
            description: |-
                GetRegimeHistory returns the region's regime transition log newest-first.
                 Entries are append-only from the seed writer, recorded only when
                 diffRegionalSnapshot reports regime_changed. Premium-gated. PRO-gated. Requires an active Pro subscription.
            operationId: GetRegimeHistory
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: region_id
                  in: query
                  description: |-
                    Display region id (e.g. "mena", "east-asia", "europe"). See shared/geography.js.
                     Kebab-case: lowercase alphanumeric groups separated by single hyphens, no
                     trailing or consecutive hyphens.
                  required: true
                  example: "mena"
                  schema:
                    type: string
                    pattern: '^[a-z][a-z0-9]*(-[a-z0-9]+)*$'
                - name: limit
                  in: query
                  description: |-
                    Optional cap on how many entries to return. Defaults to 50 server-side
                     when omitted or <= 0. Hard cap enforced by the handler at 100 (= the
                     writer-side LTRIM cap in regime-history.mjs).
                  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:
                                "transitions":
                                    - "label": "example"
                                      "previousLabel": "example"
                                      "regionId": "mena"
                                      "snapshotId": "example-id"
                                      "transitionDriver": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetRegimeHistoryResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: Pro subscription required.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/intelligence/v1/get-regional-brief:
        get:
            tags:
                - IntelligenceService
            summary: GetRegionalBrief
            description: |-
                GetRegionalBrief returns the latest weekly intelligence brief for a region.
                 Written by scripts/seed-regional-briefs.mjs on a weekly cron. Premium-gated. PRO-gated. Requires an active Pro subscription.
            operationId: GetRegionalBrief
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: region_id
                  in: query
                  description: Stable regional brief identifier, such as "middle-east".
                  required: true
                  example: "mena"
                  schema:
                    type: string
                    pattern: '^[a-z][a-z0-9]*(-[a-z0-9]+)*$'
                - 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:
                                "brief":
                                    "generatedAt": 1717200000000
                                    "keyDevelopments":
                                        - "example"
                                    "model": "example"
                                    "periodEnd": 1
                                    "periodStart": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_intelligence_v1_GetRegionalBriefResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: Pro subscription required.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/leads/v1/submit-contact:
        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:
                - LeadsService
            summary: SubmitContact
            description: SubmitContact stores an enterprise contact submission in Convex and emails ops. Turnstile-gated. Missing or invalid Cloudflare Turnstile token returns 403 Bot verification failed.
            operationId: SubmitContact
            security: []
            requestBody:
                content:
                    application/json:
                        example:
                            "email": "analyst@example.com"
                            "message": "Example WorldMonitor observation."
                            "name": "WorldMonitor Analyst"
                            "organization": "example"
                            "phone": "example"
                            "source": "example"
                            "turnstileToken": "example"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_leads_v1_SubmitContactRequest'
                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:
                                "emailSent": true
                                "status": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_leads_v1_SubmitContactResponse'
                "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
                "403":
                    description: "Bot verification failed."
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                "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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/leads/v1/register-interest:
        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:
                - LeadsService
            summary: RegisterInterest
            description: RegisterInterest adds an email to the Pro waitlist and sends a confirmation email. Turnstile-gated (desktop sources authenticate a bypass with a shared-secret HMAC instead). A failed Cloudflare Turnstile check returns 403 Bot verification failed; a desktop-source request with a missing or invalid HMAC signature returns 403 Desktop authentication failed.
            operationId: RegisterInterest
            security: []
            requestBody:
                content:
                    application/json:
                        example:
                            "appVersion": "example"
                            "email": "analyst@example.com"
                            "referredBy": "example"
                            "source": "example"
                            "turnstileToken": "example"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_leads_v1_RegisterInterestRequest'
                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:
                                "emailSuppressed": true
                                "position": 1
                                "referralCode": "example"
                                "referralCount": 1
                                "status": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_leads_v1_RegisterInterestResponse'
                "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
                "403":
                    description: "Bot verification or desktop authentication failed."
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                "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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/maritime/v1/get-vessel-snapshot:
        get:
            tags:
                - MaritimeService
            summary: GetVesselSnapshot
            description: |-
                GetVesselSnapshot retrieves a point-in-time view of AIS vessel traffic and disruptions.
                 Empty/absent snapshot with fetched_at=0 or data_available=false means the
                 relay snapshot is unavailable/degraded, not that traffic is confirmed absent.
            operationId: GetVesselSnapshot
            parameters:
                - name: ne_lat
                  in: query
                  description: North-east corner latitude of bounding box.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: ne_lon
                  in: query
                  description: North-east corner longitude of bounding box.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: sw_lat
                  in: query
                  description: South-west corner latitude of bounding box.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: sw_lon
                  in: query
                  description: South-west corner longitude of bounding box.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: include_candidates
                  in: query
                  description: |-
                    When true, populate VesselSnapshot.candidate_reports with per-vessel
                     position reports. Clients with no position callbacks should leave this
                     false to keep responses small.
                  required: false
                  example: true
                  schema:
                    type: boolean
                - name: include_tankers
                  in: query
                  description: |-
                    When true, populate VesselSnapshot.tanker_reports with per-vessel
                     position reports for AIS ship-type 80-89 (tanker class). Used by the
                     Energy Atlas live-tanker map layer. Stored separately from
                     candidate_reports (which is military-only) so consumers self-select
                     via this flag rather than the response field changing meaning.
                  required: false
                  example: true
                  schema:
                    type: boolean
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "dataAvailable": true
                                "fetchedAt": 1717200000000
                                "snapshot":
                                    "candidateReports":
                                        - "course": 1
                                          "heading": 1
                                          "lat": 40.7128
                                          "lon": -74.006
                                          "mmsi": "123456789"
                                    "densityZones":
                                        - "deltaPct": 1.5
                                          "id": "example-id"
                                          "intensity": 1.5
                                          "location":
                                              "latitude": 40.7128
                                              "longitude": -74.006
                                          "name": "WorldMonitor Analyst"
                                          "note": "example"
                                    "disruptions":
                                        - "changePct": 1.5
                                          "darkShips": 1
                                          "description": "Example WorldMonitor observation."
                                          "id": "example-id"
                                          "location":
                                              "latitude": 40.7128
                                              "longitude": -74.006
                                          "name": "WorldMonitor Analyst"
                                    "sequence": 1
                                    "snapshotAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_maritime_v1_GetVesselSnapshotResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/maritime/v1/list-navigational-warnings:
        get:
            tags:
                - MaritimeService
            summary: ListNavigationalWarnings
            description: ListNavigationalWarnings retrieves active maritime safety warnings from NGA.
            operationId: ListNavigationalWarnings
            parameters:
                - name: page_size
                  in: query
                  description: |-
                    Maximum items per page (1-100).
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: area
                  in: query
                  description: Optional area filter (e.g., "NAVAREA IV", "Persian Gulf").
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                                "warnings":
                                    - "area": "example"
                                      "authority": "example"
                                      "expiresAt": 1717200000000
                                      "id": "example-id"
                                      "issuedAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_maritime_v1_ListNavigationalWarningsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-market-quotes:
        get:
            tags:
                - MarketService
            summary: ListMarketQuotes
            description: ListMarketQuotes retrieves stock and index quotes.
            operationId: ListMarketQuotes
            parameters:
                - name: symbols
                  in: query
                  description: Ticker symbols to retrieve (e.g., ["AAPL", "^GSPC"]). Empty returns defaults.
                  required: false
                  style: form
                  explode: true
                  example:
                      - "AAPL"
                  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:
                                "finnhubSkipped": true
                                "quotes":
                                    - "change": 1.5
                                      "display": "example"
                                      "name": "WorldMonitor Analyst"
                                      "price": 75.25
                                      "sparkline":
                                          - 1.5
                                      "symbol": "AAPL"
                                "rateLimited": true
                                "skipReason": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListMarketQuotesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-crypto-quotes:
        get:
            tags:
                - MarketService
            summary: ListCryptoQuotes
            description: ListCryptoQuotes retrieves cryptocurrency quotes from CoinGecko.
            operationId: ListCryptoQuotes
            parameters:
                - name: ids
                  in: query
                  description: Cryptocurrency IDs to retrieve (CoinGecko IDs). Empty returns defaults.
                  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:
                                "quotes":
                                    - "change": 1.5
                                      "change7d": 1.5
                                      "name": "WorldMonitor Analyst"
                                      "price": 75.25
                                      "sparkline":
                                          - 1.5
                                      "symbol": "AAPL"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListCryptoQuotesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-commodity-quotes:
        get:
            tags:
                - MarketService
            summary: ListCommodityQuotes
            description: ListCommodityQuotes retrieves commodity price quotes from Yahoo Finance.
            operationId: ListCommodityQuotes
            parameters:
                - name: symbols
                  in: query
                  description: Commodity symbols to retrieve (Yahoo symbols). Empty returns defaults.
                  required: false
                  style: form
                  explode: true
                  example:
                      - "AAPL"
                  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:
                                "quotes":
                                    - "change": 1.5
                                      "display": "example"
                                      "name": "WorldMonitor Analyst"
                                      "price": 75.25
                                      "sparkline":
                                          - 1.5
                                      "symbol": "AAPL"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListCommodityQuotesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/get-sector-summary:
        get:
            tags:
                - MarketService
            summary: GetSectorSummary
            description: GetSectorSummary retrieves market sector performance data from Finnhub.
            operationId: GetSectorSummary
            parameters:
                - name: period
                  in: query
                  description: |-
                    Time period for performance calculation (e.g., "1d", "1w", "1m"). Defaults to "1d".
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "1d"
                  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:
                                "sectors":
                                    - "change": 1.5
                                      "name": "WorldMonitor Analyst"
                                      "symbol": "AAPL"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_GetSectorSummaryResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-stablecoin-markets:
        get:
            tags:
                - MarketService
            summary: ListStablecoinMarkets
            description: ListStablecoinMarkets retrieves stablecoin peg health and market data from CoinGecko.
            operationId: ListStablecoinMarkets
            parameters:
                - name: coins
                  in: query
                  description: CoinGecko IDs to retrieve (e.g. "tether,usd-coin"). Empty returns defaults.
                  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:
                                "stablecoins":
                                    - "change24h": 1.5
                                      "change7d": 1.5
                                      "deviation": 1.5
                                      "id": "example-id"
                                      "image": "example"
                                      "marketCap": 1.5
                                      "symbol": "AAPL"
                                "summary":
                                    "coinCount": 1
                                    "depeggedCount": 1
                                    "healthStatus": "example"
                                    "totalMarketCap": 1
                                    "totalVolume24h": 1
                                "timestamp": "2026-01-15T12:00:00Z"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListStablecoinMarketsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-etf-flows:
        get:
            tags:
                - MarketService
            summary: ListEtfFlows
            description: ListEtfFlows retrieves BTC spot ETF flow estimates from Yahoo Finance.
            operationId: ListEtfFlows
            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:
                                "etfs":
                                    - "avgVolume": 1
                                      "direction": "example"
                                      "estFlow": 1
                                      "issuer": "example"
                                      "price": 75.25
                                      "ticker": "AAPL"
                                "rateLimited": true
                                "summary":
                                    "etfCount": 1
                                    "inflowCount": 1
                                    "netDirection": "example"
                                    "outflowCount": 1
                                    "totalEstFlow": 1
                                "timestamp": "2026-01-15T12:00:00Z"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListEtfFlowsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/get-country-stock-index:
        get:
            tags:
                - MarketService
            summary: GetCountryStockIndex
            description: GetCountryStockIndex retrieves the primary stock index for a country from Yahoo Finance.
            operationId: GetCountryStockIndex
            parameters:
                - name: country_code
                  in: query
                  description: ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "JP").
                  required: true
                  example: "US"
                  schema:
                    type: string
                    enum:
                        - 'US'
                        - 'GB'
                        - 'DE'
                        - 'FR'
                        - 'JP'
                        - 'CN'
                        - 'HK'
                        - 'IN'
                        - 'KR'
                        - 'TW'
                        - 'AU'
                        - 'BR'
                        - 'CA'
                        - 'MX'
                        - 'AR'
                        - 'RU'
                        - 'ZA'
                        - 'SA'
                        - 'AE'
                        - 'IL'
                        - 'TR'
                        - 'PL'
                        - 'NL'
                        - 'CH'
                        - 'ES'
                        - 'IT'
                        - 'SE'
                        - 'NO'
                        - 'SG'
                        - 'TH'
                        - 'MY'
                        - 'ID'
                        - 'PH'
                        - 'NZ'
                        - 'EG'
                        - 'CL'
                        - 'PE'
                        - 'AT'
                        - 'BE'
                        - 'FI'
                        - 'DK'
                        - 'IE'
                        - 'PT'
                        - 'CZ'
                        - 'HU'
                - 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:
                                "available": true
                                "code": "US"
                                "currency": "USD"
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "indexName": "WorldMonitor Analyst"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_GetCountryStockIndexResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-gulf-quotes:
        get:
            tags:
                - MarketService
            summary: ListGulfQuotes
            description: ListGulfQuotes retrieves Gulf region market quotes (indices, currencies, oil).
            operationId: ListGulfQuotes
            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:
                                "quotes":
                                    - "change": 1.5
                                      "country": "US"
                                      "flag": "example"
                                      "name": "WorldMonitor Analyst"
                                      "price": 75.25
                                "rateLimited": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListGulfQuotesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/analyze-stock:
        get:
            tags:
                - MarketService
            summary: AnalyzeStock
            description: AnalyzeStock retrieves a premium stock analysis report with technicals, news, and AI synthesis. PRO-gated. Requires entitlement tier >= 1.
            operationId: AnalyzeStock
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: symbol
                  in: query
                  description: Stock ticker symbol to analyze.
                  required: true
                  example: "AAPL"
                  schema:
                    type: string
                - name: name
                  in: query
                  description: Optional company display name used to disambiguate the symbol.
                  required: false
                  example: "WorldMonitor Analyst"
                  schema:
                    type: string
                - name: include_news
                  in: query
                  description: Whether to include recent news in the stock analysis.
                  required: false
                  example: true
                  schema:
                    type: boolean
                - 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:
                                "action": "example"
                                "analysisAt": 1717200000000
                                "analysisId": "example-id"
                                "analystConsensus":
                                    "buy": 1
                                    "hold": 1
                                    "period": "daily"
                                    "sell": 1
                                    "strongBuy": 1
                                "available": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_AnalyzeStockResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/get-stock-analysis-history:
        get:
            tags:
                - MarketService
            summary: GetStockAnalysisHistory
            description: GetStockAnalysisHistory retrieves shared premium stock analysis history from the backend store. PRO-gated. Requires entitlement tier >= 1.
            operationId: GetStockAnalysisHistory
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: symbols
                  in: query
                  description: Stock ticker symbols whose stored analysis history should be returned.
                  required: false
                  style: form
                  explode: true
                  example:
                      - "AAPL"
                  schema:
                    type: array
                    items:
                        type: string
                - name: limit_per_symbol
                  in: query
                  description: Maximum number of history snapshots to return per symbol.
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: include_news
                  in: query
                  description: Whether history snapshots should include stored news summaries.
                  required: false
                  example: true
                  schema:
                    type: boolean
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "items":
                                    - "snapshots":
                                        - "action": "example"
                                          "analysisAt": 1717200000000
                                          "analysisId": "example-id"
                                          "analystConsensus":
                                              "buy": 1
                                              "hold": 1
                                              "period": "daily"
                                              "sell": 1
                                              "strongBuy": 1
                                          "available": true
                                      "symbol": "AAPL"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_GetStockAnalysisHistoryResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/backtest-stock:
        get:
            tags:
                - MarketService
            summary: BacktestStock
            description: BacktestStock replays premium stock-analysis signals over recent price history. PRO-gated. Requires entitlement tier >= 1.
            operationId: BacktestStock
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: symbol
                  in: query
                  description: Stock ticker symbol to backtest.
                  required: true
                  example: "AAPL"
                  schema:
                    type: string
                - name: name
                  in: query
                  description: Optional company display name used to disambiguate the symbol.
                  required: false
                  example: "WorldMonitor Analyst"
                  schema:
                    type: string
                - name: eval_window_days
                  in: query
                  description: Evaluation window in days for simulated backtest outcomes.
                  required: false
                  example: 7
                  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:
                                "actionableEvaluations": 1
                                "available": true
                                "avgSimulatedReturnPct": 1.5
                                "cumulativeSimulatedReturnPct": 1.5
                                "currency": "USD"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_BacktestStockResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-stored-stock-backtests:
        get:
            tags:
                - MarketService
            summary: ListStoredStockBacktests
            description: ListStoredStockBacktests retrieves stored premium backtest snapshots from the backend store. PRO-gated. Requires entitlement tier >= 1.
            operationId: ListStoredStockBacktests
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: symbols
                  in: query
                  description: Stock ticker symbols whose stored backtests should be returned.
                  required: false
                  style: form
                  explode: true
                  example:
                      - "AAPL"
                  schema:
                    type: array
                    items:
                        type: string
                - name: eval_window_days
                  in: query
                  description: Evaluation window in days used by stored backtests.
                  required: false
                  example: 7
                  schema:
                    type: integer
                    format: int32
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "items":
                                    - "actionableEvaluations": 1
                                      "available": true
                                      "avgSimulatedReturnPct": 1.5
                                      "cumulativeSimulatedReturnPct": 1.5
                                      "currency": "USD"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListStoredStockBacktestsResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-crypto-sectors:
        get:
            tags:
                - MarketService
            summary: ListCryptoSectors
            description: ListCryptoSectors retrieves crypto sector performance averages.
            operationId: ListCryptoSectors
            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:
                                "sectors":
                                    - "change": 1.5
                                      "id": "example-id"
                                      "name": "WorldMonitor Analyst"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListCryptoSectorsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-defi-tokens:
        get:
            tags:
                - MarketService
            summary: ListDefiTokens
            description: ListDefiTokens retrieves DeFi token prices and changes.
            operationId: ListDefiTokens
            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:
                                "tokens":
                                    - "change": 1.5
                                      "change7d": 1.5
                                      "name": "WorldMonitor Analyst"
                                      "price": 75.25
                                      "sparkline":
                                          - 1.5
                                      "symbol": "AAPL"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListDefiTokensResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-ai-tokens:
        get:
            tags:
                - MarketService
            summary: ListAiTokens
            description: ListAiTokens retrieves AI-focused crypto token prices and changes.
            operationId: ListAiTokens
            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:
                                "tokens":
                                    - "change": 1.5
                                      "change7d": 1.5
                                      "name": "WorldMonitor Analyst"
                                      "price": 75.25
                                      "sparkline":
                                          - 1.5
                                      "symbol": "AAPL"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListAiTokensResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-other-tokens:
        get:
            tags:
                - MarketService
            summary: ListOtherTokens
            description: ListOtherTokens retrieves other/trending crypto token prices and changes.
            operationId: ListOtherTokens
            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:
                                "tokens":
                                    - "change": 1.5
                                      "change7d": 1.5
                                      "name": "WorldMonitor Analyst"
                                      "price": 75.25
                                      "sparkline":
                                          - 1.5
                                      "symbol": "AAPL"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListOtherTokensResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/get-fear-greed-index:
        get:
            tags:
                - MarketService
            summary: GetFearGreedIndex
            description: GetFearGreedIndex retrieves the composite Fear & Greed sentiment index.
            operationId: GetFearGreedIndex
            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:
                                "aaiiBear": 1.5
                                "aaiiBull": 1.5
                                "breadth":
                                    "contribution": 1.5
                                    "degraded": true
                                    "inputsJson": "example"
                                    "score": 42.5
                                    "weight": 1.5
                                "cnnFearGreed": 1.5
                                "cnnLabel": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_GetFearGreedIndexResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/list-earnings-calendar:
        get:
            tags:
                - MarketService
            summary: ListEarningsCalendar
            description: ListEarningsCalendar retrieves upcoming and recent earnings releases.
            operationId: ListEarningsCalendar
            parameters:
                - name: fromDate
                  in: query
                  description: Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "2026-01-15"
                  schema:
                    type: string
                - name: toDate
                  in: query
                  description: Accepted but currently ignored; no-op until this handler supports the parameter.
                  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:
                                "earnings":
                                    - "company": "example"
                                      "date": "2026-01-15"
                                      "epsActual": 1.5
                                      "epsEstimate": 1.5
                                      "hasActuals": true
                                "fromDate": "2026-01-15"
                                "toDate": "2026-01-15"
                                "total": 1
                                "unavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_ListEarningsCalendarResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/get-cot-positioning:
        get:
            tags:
                - MarketService
            summary: GetCotPositioning
            description: GetCotPositioning retrieves CFTC COT institutional positioning data.
            operationId: GetCotPositioning
            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:
                                "instruments":
                                    - "assetManagerLong": "1717200000000"
                                      "assetManagerShort": "1717200000000"
                                      "code": "example"
                                      "dealerLong": "1717200000000"
                                      "dealerShort": "1717200000000"
                                "reportDate": "2026-01-15"
                                "unavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_GetCotPositioningResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/get-insider-transactions:
        get:
            tags:
                - MarketService
            summary: GetInsiderTransactions
            description: GetInsiderTransactions retrieves SEC insider buy/sell activity from Finnhub.
            operationId: GetInsiderTransactions
            parameters:
                - name: symbol
                  in: query
                  description: Stock ticker symbol for insider transaction lookup.
                  required: true
                  example: "AAPL"
                  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:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "netValue": 1.5
                                "symbol": "AAPL"
                                "totalBuys": 1
                                "totalSells": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_GetInsiderTransactionsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/get-market-breadth-history:
        get:
            tags:
                - MarketService
            summary: GetMarketBreadthHistory
            description: GetMarketBreadthHistory retrieves historical % of S&P 500 stocks above 20/50/200-day SMAs.
            operationId: GetMarketBreadthHistory
            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:
                                "currentPctAbove200d": 1.5
                                "currentPctAbove20d": 1.5
                                "currentPctAbove50d": 1.5
                                "history":
                                    - "date": "2026-01-15"
                                      "pctAbove200d": 1.5
                                      "pctAbove20d": 1.5
                                      "pctAbove50d": 1.5
                                "unavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_GetMarketBreadthHistoryResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/get-gold-intelligence:
        get:
            tags:
                - MarketService
            summary: GetGoldIntelligence
            description: GetGoldIntelligence retrieves gold pricing, cross-currency XAU, ratios, and CFTC positioning.
            operationId: GetGoldIntelligence
            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:
                                "cbReserves":
                                    "asOfMonth": "example"
                                    "topBuyers12m":
                                        - "deltaTonnes12m": 1.5
                                          "iso3": "USA"
                                          "name": "WorldMonitor Analyst"
                                    "topHolders":
                                        - "iso3": "USA"
                                          "name": "WorldMonitor Analyst"
                                          "pctOfReserves": 1.5
                                          "tonnes": 1.5
                                    "topSellers12m":
                                        - "deltaTonnes12m": 1.5
                                          "iso3": "USA"
                                          "name": "WorldMonitor Analyst"
                                    "totalTonnes": 1
                                "cot":
                                    "managedMoney":
                                        "longPositions": "1717200000000"
                                        "netPct": 1.5
                                        "oiSharePct": 1.5
                                        "shortPositions": "1717200000000"
                                        "wowNetDelta": "1717200000000"
                                    "nextReleaseDate": "2026-01-15"
                                    "openInterest": "1717200000000"
                                    "producerSwap":
                                        "longPositions": "1717200000000"
                                        "netPct": 1.5
                                        "oiSharePct": 1.5
                                        "shortPositions": "1717200000000"
                                        "wowNetDelta": "1717200000000"
                                    "reportDate": "2026-01-15"
                                "crossCurrencyPrices":
                                    - "currency": "USD"
                                      "flag": "example"
                                      "price": 75.25
                                "drivers":
                                    - "changePct": 1.5
                                      "correlation30d": 1.5
                                      "label": "example"
                                      "symbol": "AAPL"
                                      "value": 1.5
                                "etfFlows":
                                    "asOfDate": "2026-01-15"
                                    "aumUsd": 1.5
                                    "changeM1Pct": 1.5
                                    "changeM1Tonnes": 1.5
                                    "changeW1Pct": 1.5
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_GetGoldIntelligenceResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/market/v1/get-hyperliquid-flow:
        get:
            tags:
                - MarketService
            summary: GetHyperliquidFlow
            description: GetHyperliquidFlow retrieves Hyperliquid perp positioning flow (funding/OI/basis composite scores).
            operationId: GetHyperliquidFlow
            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:
                                "assetCount": 1
                                "assets":
                                    - "alerts":
                                        - "example"
                                      "assetClass": "example"
                                      "basisScore": 42.5
                                      "composite": 1.5
                                      "dayNotional": "example"
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "ts": "1717200000000"
                                "unavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_market_v1_GetHyperliquidFlowResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/military/v1/list-military-flights:
        get:
            tags:
                - MilitaryService
            summary: ListMilitaryFlights
            description: ListMilitaryFlights retrieves tracked military aircraft from OpenSky and Wingbits.
            operationId: ListMilitaryFlights
            parameters:
                - name: page_size
                  in: query
                  description: Maximum items per page (1-100).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: ne_lat
                  in: query
                  description: North-east corner latitude of bounding box.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: ne_lon
                  in: query
                  description: North-east corner longitude of bounding box.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: sw_lat
                  in: query
                  description: South-west corner latitude of bounding box.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: sw_lon
                  in: query
                  description: South-west corner longitude of bounding box.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: operator
                  in: query
                  description: |-
                    Optional operator filter.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "MILITARY_OPERATOR_USAF"
                  schema:
                    type: string
                    enum:
                        - 'MILITARY_OPERATOR_USAF'
                        - 'MILITARY_OPERATOR_USN'
                        - 'MILITARY_OPERATOR_USMC'
                        - 'MILITARY_OPERATOR_USA'
                        - 'MILITARY_OPERATOR_RAF'
                        - 'MILITARY_OPERATOR_RN'
                        - 'MILITARY_OPERATOR_FAF'
                        - 'MILITARY_OPERATOR_GAF'
                        - 'MILITARY_OPERATOR_PLAAF'
                        - 'MILITARY_OPERATOR_PLAN'
                        - 'MILITARY_OPERATOR_VKS'
                        - 'MILITARY_OPERATOR_IAF'
                        - 'MILITARY_OPERATOR_NATO'
                        - 'MILITARY_OPERATOR_OTHER'
                - name: aircraft_type
                  in: query
                  description: |-
                    Optional aircraft type filter.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "MILITARY_AIRCRAFT_TYPE_FIGHTER"
                  schema:
                    type: string
                    enum:
                        - 'MILITARY_AIRCRAFT_TYPE_FIGHTER'
                        - 'MILITARY_AIRCRAFT_TYPE_BOMBER'
                        - 'MILITARY_AIRCRAFT_TYPE_TRANSPORT'
                        - 'MILITARY_AIRCRAFT_TYPE_TANKER'
                        - 'MILITARY_AIRCRAFT_TYPE_AWACS'
                        - 'MILITARY_AIRCRAFT_TYPE_RECONNAISSANCE'
                        - 'MILITARY_AIRCRAFT_TYPE_HELICOPTER'
                        - 'MILITARY_AIRCRAFT_TYPE_DRONE'
                        - 'MILITARY_AIRCRAFT_TYPE_PATROL'
                        - 'MILITARY_AIRCRAFT_TYPE_SPECIAL_OPS'
                        - 'MILITARY_AIRCRAFT_TYPE_VIP'
                        - 'MILITARY_AIRCRAFT_TYPE_UNKNOWN'
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "clusters":
                                    - "activityType": "MILITARY_ACTIVITY_TYPE_EXERCISE"
                                      "dominantOperator": "MILITARY_OPERATOR_USAF"
                                      "flightCount": 1
                                      "flights":
                                          - "aircraftModel": "example"
                                            "aircraftType": "MILITARY_AIRCRAFT_TYPE_FIGHTER"
                                            "altitude": 1.5
                                            "callsign": "example"
                                            "confidence": "MILITARY_CONFIDENCE_LOW"
                                            "id": "example-id"
                                      "id": "example-id"
                                "flights":
                                    - "aircraftModel": "example"
                                      "aircraftType": "MILITARY_AIRCRAFT_TYPE_FIGHTER"
                                      "altitude": 1.5
                                      "callsign": "example"
                                      "confidence": "MILITARY_CONFIDENCE_LOW"
                                      "id": "example-id"
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_military_v1_ListMilitaryFlightsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/military/v1/get-theater-posture:
        get:
            tags:
                - MilitaryService
            summary: GetTheaterPosture
            description: GetTheaterPosture retrieves military posture assessments for geographic theaters.
            operationId: GetTheaterPosture
            parameters:
                - name: theater
                  in: query
                  description: |-
                    Theater name (e.g., "indo-pacific", "european", "middle-east"). Empty for all theaters.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "indo-pacific"
                  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:
                                "theaters":
                                    - "activeFlights": 1
                                      "activeOperations":
                                          - "example"
                                      "assessedAt": 1717200000000
                                      "postureLevel": "example"
                                      "theater": "indo-pacific"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_military_v1_GetTheaterPostureResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/military/v1/get-aircraft-details:
        get:
            tags:
                - MilitaryService
            summary: GetAircraftDetails
            description: GetAircraftDetails retrieves Wingbits aircraft enrichment data for a single ICAO24 hex.
            operationId: GetAircraftDetails
            parameters:
                - name: icao24
                  in: query
                  description: ICAO 24-bit hex address (lowercase).
                  required: true
                  example: "a835af"
                  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:
                                "configured": true
                                "details":
                                    "built": "example"
                                    "categoryDescription": "cs.AI"
                                    "engines": "example"
                                    "icao24": "a835af"
                                    "icaoAircraftType": "all"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_military_v1_GetAircraftDetailsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/military/v1/get-aircraft-details-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:
                - MilitaryService
            summary: GetAircraftDetailsBatch
            description: GetAircraftDetailsBatch retrieves Wingbits aircraft enrichment data for multiple ICAO24 hexes.
            operationId: GetAircraftDetailsBatch
            requestBody:
                content:
                    application/json:
                        example:
                            "icao24s":
                                - "a835af"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_military_v1_GetAircraftDetailsBatchRequest'
                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:
                                "configured": true
                                "fetched": 1
                                "requested": 1
                                "results":
                                    "exampleKey":
                                        "built": "example"
                                        "categoryDescription": "cs.AI"
                                        "engines": "example"
                                        "icao24": "a835af"
                                        "icaoAircraftType": "all"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_military_v1_GetAircraftDetailsBatchResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/military/v1/get-wingbits-status:
        get:
            tags:
                - MilitaryService
            summary: GetWingbitsStatus
            description: GetWingbitsStatus checks whether the Wingbits enrichment API is configured.
            operationId: GetWingbitsStatus
            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:
                                "configured": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_military_v1_GetWingbitsStatusResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/military/v1/get-usni-fleet-report:
        get:
            tags:
                - MilitaryService
            summary: GetUSNIFleetReport
            description: GetUSNIFleetReport retrieves the latest parsed USNI Fleet Tracker report.
            operationId: GetUSNIFleetReport
            parameters:
                - name: force_refresh
                  in: query
                  description: When true, bypass cache and fetch fresh data from USNI.
                  required: false
                  example: true
                  schema:
                    type: boolean
                - 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:
                                "cached": true
                                "error": "example"
                                "report":
                                    "articleDate": "2026-01-15"
                                    "articleTitle": "example"
                                    "articleUrl": "https://example.com/worldmonitor"
                                    "battleForceSummary":
                                        "deployed": 1
                                        "totalShips": 1
                                        "underway": 1
                                    "parsingWarnings":
                                        - "example"
                                "stale": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_military_v1_GetUSNIFleetReportResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/military/v1/list-military-bases:
        get:
            tags:
                - MilitaryService
            summary: ListMilitaryBases
            description: ListMilitaryBases retrieves military bases within a bounding box, with server-side clustering.
            operationId: ListMilitaryBases
            parameters:
                - name: ne_lat
                  in: query
                  description: North-east corner latitude of the map bounding box.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: ne_lon
                  in: query
                  description: North-east corner longitude of the map bounding box.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: sw_lat
                  in: query
                  description: South-west corner latitude of the map bounding box.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: sw_lon
                  in: query
                  description: South-west corner longitude of the map bounding box.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: zoom
                  in: query
                  description: Map zoom level used to decide whether to return bases or clusters.
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: type
                  in: query
                  description: Optional military base type filter.
                  required: false
                  example: "us-nato"
                  schema:
                    type: string
                    enum:
                        - 'us-nato'
                        - 'china'
                        - 'russia'
                        - 'uk'
                        - 'france'
                        - 'india'
                        - 'italy'
                        - 'uae'
                        - 'turkey'
                        - 'japan'
                        - 'other'
                - name: kind
                  in: query
                  description: Optional military base kind filter.
                  required: false
                  example: "base"
                  schema:
                    type: string
                    enum:
                        - 'base'
                        - 'airfield'
                        - 'naval_base'
                        - 'military'
                        - 'barracks'
                        - 'bunker'
                        - 'trench'
                        - 'training_area'
                        - 'checkpoint'
                        - 'shelter'
                        - 'ammunition'
                        - 'office'
                        - 'obstacle_course'
                        - 'nuclear_explosion_site'
                        - 'range'
                - name: country
                  in: query
                  description: Optional country filter for military bases.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "bases":
                                    - "branch": "example"
                                      "catAirforce": true
                                      "catNaval": true
                                      "catNuclear": true
                                      "catSpace": true
                                "clusters":
                                    - "count": 1
                                      "dominantType": "all"
                                      "expansionZoom": 1
                                      "latitude": 40.7128
                                      "longitude": -74.006
                                "totalInView": 1
                                "truncated": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_military_v1_ListMilitaryBasesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/military/v1/get-wingbits-live-flight:
        get:
            tags:
                - MilitaryService
            summary: GetWingbitsLiveFlight
            description: GetWingbitsLiveFlight retrieves real-time position data from the Wingbits ECS network for a single aircraft.
            operationId: GetWingbitsLiveFlight
            parameters:
                - name: icao24
                  in: query
                  description: ICAO 24-bit hex address (lowercase, 6 characters).
                  required: true
                  example: "a835af"
                  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:
                                "flight":
                                    "airlineName": "WorldMonitor Analyst"
                                    "altitude": 1.5
                                    "arrDelayedMin": 1
                                    "arrEstimatedUtc": "example"
                                    "arrIata": "JFK"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_military_v1_GetWingbitsLiveFlightResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/military/v1/list-defense-patents:
        get:
            tags:
                - MilitaryService
            summary: ListDefensePatents
            description: ListDefensePatents retrieves recent defense/dual-use patent filings from USPTO PatentsView.
            operationId: ListDefensePatents
            parameters:
                - name: cpc_code
                  in: query
                  description: CPC category filter (e.g. "H04B", "F42B"). Empty returns all categories.
                  required: false
                  example: "H04B"
                  schema:
                    type: string
                - name: assignee
                  in: query
                  description: Assignee keyword filter (case-insensitive substring match). Empty returns all.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: limit
                  in: query
                  description: Maximum results to return (default 20, max 100).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "patents":
                                    - "abstract": "example"
                                      "assignee": "example"
                                      "cpcCode": "example"
                                      "cpcDesc": "example"
                                      "date": "2026-01-15"
                                "total": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_military_v1_ListDefensePatentsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/natural/v1/list-natural-events:
        get:
            tags:
                - NaturalService
            summary: ListNaturalEvents
            description: |-
                ListNaturalEvents retrieves seeded EONET/GDACS/NHC natural events. Empty
                 events with fetched_at=0 or data_available=false means the seed snapshot is
                 unavailable/degraded, not that there are confirmed zero events.
            operationId: ListNaturalEvents
            security: []
            parameters:
                - name: days
                  in: query
                  description: Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 7
                  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:
                                "dataAvailable": true
                                "events":
                                    - "basin": "example"
                                      "category": "cs.AI"
                                      "categoryTitle": "cs.AI"
                                      "classification": "example"
                                      "closed": true
                                "fetchedAt": 1717200000000
                            schema:
                                $ref: '#/components/schemas/worldmonitor_natural_v1_ListNaturalEventsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/news/v1/summarize-article:
        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:
                - NewsService
            summary: SummarizeArticle
            description: SummarizeArticle generates an LLM summary with provider selection and fallback support.
            operationId: SummarizeArticle
            requestBody:
                content:
                    application/json:
                        example:
                            "bodies":
                                - "example"
                            "geoContext": "example"
                            "headlines":
                                - "example"
                            "lang": "en"
                            "mode": "brief"
                            "provider": "openrouter"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_news_v1_SummarizeArticleRequest'
                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:
                                "error": "example"
                                "errorType": "all"
                                "fallback": true
                                "model": "example"
                                "provider": "openrouter"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_news_v1_SummarizeArticleResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/news/v1/summarize-article-cache:
        get:
            tags:
                - NewsService
            summary: GetSummarizeArticleCache
            description: GetSummarizeArticleCache looks up a cached summary by deterministic key (CDN-cacheable GET).
            operationId: GetSummarizeArticleCache
            parameters:
                - name: cache_key
                  in: query
                  description: Deterministic cache key computed by buildSummaryCacheKey().
                  required: false
                  example: "summary:v1:example-cache"
                  schema:
                    type: string
                    pattern: '^summary:v\d+:[a-z0-9:_-]{3,120}$'
                - 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:
                                "error": "example"
                                "errorType": "all"
                                "fallback": true
                                "model": "example"
                                "provider": "openrouter"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_news_v1_SummarizeArticleResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/news/v1/list-feed-digest:
        get:
            tags:
                - NewsService
            summary: ListFeedDigest
            description: ListFeedDigest returns a pre-aggregated digest of all RSS feeds for a site variant.
            operationId: ListFeedDigest
            parameters:
                - name: variant
                  in: query
                  description: 'Digest variant: full, tech, finance, happy, commodity. Unsupported site variants, including energy, currently fall back to full.'
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: lang
                  in: query
                  description: ISO 639-1 language code (en, fr, ar, etc.)
                  required: false
                  example: "en"
                  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:
                                "categories":
                                    "exampleKey":
                                        "items":
                                            - "corroborationCount": 42
                                              "importanceScore": 42
                                              "isAlert": true
                                              "link": "https://example.com/worldmonitor"
                                              "location":
                                                  "latitude": 40.7128
                                                  "longitude": -74.006
                                              "source": "example"
                                              "title": "example"
                                "feedStatuses":
                                    "exampleKey": "example"
                                "generatedAt": "2026-01-15T12:00:00Z"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_news_v1_ListFeedDigestResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/positive-events/v1/list-positive-geo-events:
        get:
            tags:
                - PositiveEventsService
            summary: ListPositiveGeoEvents
            description: ListPositiveGeoEvents retrieves geocoded positive news events from GDELT GEO API.
            operationId: ListPositiveGeoEvents
            parameters:
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "events":
                                    - "category": "cs.AI"
                                      "count": 1
                                      "latitude": 40.7128
                                      "longitude": -74.006
                                      "name": "WorldMonitor Analyst"
                                "fetchedAt": 1717200000000
                                "stale": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_positive_events_v1_ListPositiveGeoEventsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/prediction/v1/list-prediction-markets:
        get:
            tags:
                - PredictionService
            summary: ListPredictionMarkets
            description: |-
                ListPredictionMarkets retrieves active prediction markets from seeded market snapshots.
                 Empty markets with fetched_at=0 or data_available=false means the seed
                 snapshot is unavailable/degraded, not that there are confirmed zero markets.
            operationId: ListPredictionMarkets
            parameters:
                - name: page_size
                  in: query
                  description: Maximum items per page (1-100).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: category
                  in: query
                  description: Optional category filter (e.g., "Politics").
                  required: false
                  example: "ai"
                  schema:
                    type: string
                    enum:
                        - 'ai'
                        - 'tech'
                        - 'crypto'
                        - 'science'
                        - 'economy'
                        - 'fed'
                        - 'inflation'
                        - 'interest-rates'
                        - 'recession'
                        - 'trade'
                        - 'tariffs'
                        - 'debt-ceiling'
                - name: query
                  in: query
                  description: Optional search query for market titles.
                  required: false
                  example: "supply chain risk"
                  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:
                                "dataAvailable": true
                                "fetchedAt": 1717200000000
                                "markets":
                                    - "category": "cs.AI"
                                      "closesAt": 1717200000000
                                      "id": "example-id"
                                      "source": "MARKET_SOURCE_POLYMARKET"
                                      "title": "example"
                                      "url": "https://example.com/worldmonitor"
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_prediction_v1_ListPredictionMarketsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/radiation/v1/list-radiation-observations:
        get:
            tags:
                - RadiationService
            summary: ListRadiationObservations
            description: |-
                ListRadiationObservations retrieves normalized EPA RadNet and Safecast readings.
                 Empty observations with fetched_at=0 or data_available=false means the seed
                 snapshot is unavailable/degraded, not that radiation readings are confirmed absent.
            operationId: ListRadiationObservations
            parameters:
                - name: max_items
                  in: query
                  description: Maximum items to return (1-25). Zero uses the service default.
                  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:
                                "anomalyCount": 1
                                "conflictingCount": 1
                                "convertedFromCpmCount": 1
                                "corroboratedCount": 75
                                "dataAvailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_radiation_v1_ListRadiationObservationsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/research/v1/list-arxiv-papers:
        get:
            tags:
                - ResearchService
            summary: ListArxivPapers
            description: ListArxivPapers retrieves recent papers from arXiv.
            operationId: ListArxivPapers
            parameters:
                - name: page_size
                  in: query
                  description: Maximum items per page (1-100).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: category
                  in: query
                  description: arXiv category filter (e.g., "cs.AI"). Empty returns all tracked categories.
                  required: false
                  example: "cs.AI"
                  schema:
                    type: string
                - name: query
                  in: query
                  description: |-
                    Search query for paper titles and abstracts.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "supply chain risk"
                  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:
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                                "papers":
                                    - "authors":
                                        - "example"
                                      "categories":
                                          - "example"
                                      "id": "example-id"
                                      "publishedAt": 1717200000000
                                      "summary": "Example WorldMonitor observation."
                                      "title": "example"
                                      "url": "https://example.com/worldmonitor"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_research_v1_ListArxivPapersResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/research/v1/list-trending-repos:
        get:
            tags:
                - ResearchService
            summary: ListTrendingRepos
            description: ListTrendingRepos retrieves trending repositories from GitHub.
            operationId: ListTrendingRepos
            parameters:
                - name: page_size
                  in: query
                  description: Maximum items per page (1-100).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: Cursor for next page.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: language
                  in: query
                  description: Programming language filter (e.g., "python", "typescript").
                  required: false
                  example: "typescript"
                  schema:
                    type: string
                - name: period
                  in: query
                  description: Trending period (e.g., "daily", "weekly"). Defaults to "daily".
                  required: false
                  example: "daily"
                  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:
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                                "repos":
                                    - "description": "Example WorldMonitor observation."
                                      "forks": 1
                                      "fullName": "koala73/worldmonitor"
                                      "language": "typescript"
                                      "stars": 1
                                      "starsToday": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_research_v1_ListTrendingReposResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/research/v1/list-hackernews-items:
        get:
            tags:
                - ResearchService
            summary: ListHackernewsItems
            description: ListHackernewsItems retrieves top stories from Hacker News.
            operationId: ListHackernewsItems
            parameters:
                - name: page_size
                  in: query
                  description: Maximum items per page (1-100).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: Cursor for next page.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: feed_type
                  in: query
                  description: 'Feed type: "top", "new", "best", "ask", "show", "job". Defaults to "top".'
                  required: false
                  example: "top"
                  schema:
                    type: string
                    enum:
                        - 'top'
                        - 'new'
                        - 'best'
                        - 'ask'
                        - 'show'
                        - 'job'
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "items":
                                    - "by": "example"
                                      "commentCount": 1
                                      "id": 1
                                      "score": 42
                                      "submittedAt": 1717200000000
                                      "title": "example"
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_research_v1_ListHackernewsItemsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/research/v1/list-tech-events:
        get:
            tags:
                - ResearchService
            summary: ListTechEvents
            description: ListTechEvents retrieves tech events from Techmeme ICS, dev.events RSS, and curated sources.
            operationId: ListTechEvents
            parameters:
                - name: type
                  in: query
                  description: 'Event type filter: "all", "conference", "earnings", "ipo", "other". Empty = all.'
                  required: false
                  example: "all"
                  schema:
                    type: string
                    enum:
                        - 'all'
                        - 'conference'
                        - 'earnings'
                        - 'ipo'
                        - 'other'
                - name: mappable
                  in: query
                  description: Only events with non-virtual coordinates.
                  required: false
                  example: true
                  schema:
                    type: boolean
                - name: limit
                  in: query
                  description: |-
                    Max events to return. The handler clamps this to the range 1-200 and defaults to 50
                     when omitted; 0 is not unlimited (it clamps up to 1).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: days
                  in: query
                  description: |-
                    Events within N days from now. The handler clamps this to the range 1-365 and defaults
                     to 90 when omitted; 0 is not unlimited (it clamps up to 1).
                  required: false
                  example: 7
                  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:
                                "conferenceCount": 1
                                "count": 1
                                "error": "example"
                                "events":
                                    - "coords":
                                        "country": "US"
                                        "lat": 40.7128
                                        "lng": -74.006
                                        "original": "example"
                                        "virtual": true
                                      "description": "Example WorldMonitor observation."
                                      "endDate": "2026-01-15"
                                      "id": "example-id"
                                      "location": "example"
                                "lastUpdated": "2026-01-15T12:00:00.000Z"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_research_v1_ListTechEventsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/resilience/v1/get-resilience-score:
        get:
            tags:
                - ResilienceService
            summary: GetResilienceScore
            description: PRO-gated. Requires an active Pro subscription.
            operationId: GetResilienceScore
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: countryCode
                  in: query
                  description: ISO 3166-1 alpha-2 country code to score.
                  required: true
                  example: "US"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "baselineScore": 42.5
                                "change30d": 1.5
                                "countryCode": "US"
                                "dataVersion": "example"
                                "domains":
                                    - "dimensions":
                                        - "coverage": 1.5
                                          "freshness":
                                              "lastObservedAtMs": "1717200000000"
                                              "staleness": "example"
                                          "id": "example-id"
                                          "imputationClass": "example"
                                          "imputedWeight": 1.5
                                      "id": "example-id"
                                      "score": 42.5
                                      "weight": 1.5
                            schema:
                                $ref: '#/components/schemas/worldmonitor_resilience_v1_GetResilienceScoreResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: Pro subscription required.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/resilience/v1/get-resilience-ranking:
        get:
            tags:
                - ResilienceService
            summary: GetResilienceRanking
            description: PRO-gated. Requires an active Pro subscription.
            operationId: GetResilienceRanking
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            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:
                                "coverage": 1.5
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "greyedOut":
                                    - "countryCode": "US"
                                      "headlineEligible": true
                                      "level": "example"
                                      "lowConfidence": true
                                      "overallCoverage": 1.5
                                "items":
                                    - "countryCode": "US"
                                      "headlineEligible": true
                                      "level": "example"
                                      "lowConfidence": true
                                      "overallCoverage": 1.5
                                "partial": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_resilience_v1_GetResilienceRankingResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: Pro subscription required.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/resilience/v1/get-runtime-manifest:
        get:
            tags:
                - ResilienceService
            summary: GetResilienceRuntimeManifest
            description: 'GetResilienceRuntimeManifest returns the public resilience-scoring runtime manifest: manifest version, generation timestamp, active formula tag, cache state, construct versions, and interval availability.'
            operationId: GetResilienceRuntimeManifest
            security: []
            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:
                                "cache":
                                    "historyPrefix": "example"
                                    "intervalMethodology": "example"
                                    "intervalPrefix": "example"
                                    "rankingKey": "example"
                                    "scorePrefix": "example"
                                "constructVersions":
                                    "energy": "example"
                                "dataVersion": "example"
                                "deployedCommitSha": "example"
                                "flags":
                                    - "enabled": true
                                      "name": "WorldMonitor Analyst"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_resilience_v1_GetResilienceRuntimeManifestResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/sanctions/v1/list-sanctions-pressure:
        get:
            tags:
                - SanctionsService
            summary: ListSanctionsPressure
            description: ListSanctionsPressure retrieves normalized OFAC designation summaries and recent additions. PRO-gated. Requires entitlement tier >= 1.
            operationId: ListSanctionsPressure
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: max_items
                  in: query
                  description: Maximum number of recent sanctions entries to include.
                  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:
                                "aircraftCount": 1
                                "consolidatedCount": 1
                                "countries":
                                    - "aircraftCount": 1
                                      "countryCode": "US"
                                      "countryName": "US"
                                      "entryCount": 1
                                      "newEntryCount": 1
                                "datasetDate": "1717200000000"
                                "entries":
                                    - "countryCodes":
                                        - "US"
                                      "countryNames":
                                          - "US"
                                      "effectiveAt": "1717200000000"
                                      "entityType": "SANCTIONS_ENTITY_TYPE_ENTITY"
                                      "id": "example-id"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_sanctions_v1_ListSanctionsPressureResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/sanctions/v1/lookup-sanction-entity:
        get:
            tags:
                - SanctionsService
            summary: LookupSanctionEntity
            description: LookupSanctionEntity searches the OFAC entity index by name, vessel, or aircraft.
            operationId: LookupSanctionEntity
            parameters:
                - name: q
                  in: query
                  description: Search text for a sanctioned person, organization, vessel, or aircraft.
                  required: false
                  example: "example"
                  schema:
                    type: string
                - name: max_results
                  in: query
                  description: Maximum number of matching sanctioned entities to return.
                  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:
                                "results":
                                    - "countryCodes":
                                        - "US"
                                      "entityType": "all"
                                      "id": "example-id"
                                      "name": "WorldMonitor Analyst"
                                      "programs":
                                          - "example"
                                "source": "example"
                                "total": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_sanctions_v1_LookupSanctionEntityResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/scenario/v1/run-scenario:
        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:
                - ScenarioService
            summary: RunScenario
            description: |-
                RunScenario enqueues a scenario job on scenario-queue:pending. PRO-gated.
                 Async job pattern: a successful enqueue returns HTTP 202 Accepted with a
                 Location header pointing at GetScenarioStatus; poll it (or the statusUrl
                 body field) with the returned jobId until status is "done" or "failed".
                 The scenario-worker (scripts/scenario-worker.mjs) pulls jobs off the
                 queue via BLMOVE and writes results under scenario-result:{job_id}. Requires entitlement tier >= 1.
            operationId: RunScenario
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            requestBody:
                content:
                    application/json:
                        example:
                            "iso2": "US"
                            "scenarioId": "hormuz-tanker-blockade"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_scenario_v1_RunScenarioRequest'
                required: true
            responses:
                "202":
                    description: Accepted — scenario job enqueued. The body carries the job id (jobId), the initial status (always pending) and a poll URL (statusUrl); the Location header points at the same GetScenarioStatus endpoint. Poll it until status is done or failed.
                    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.
                        Location:
                            schema:
                                type: string
                            description: Relative URL of the job-status poll endpoint for this job (same value as the statusUrl body field).
                            example: "/api/scenario/v1/get-scenario-status?jobId=scenario%3A1717200000000%3Aabcd1234"
                    content:
                        application/json:
                            example:
                                "jobId": "scenario:1717200000000:abcd1234"
                                "status": "pending"
                                "statusUrl": "/api/scenario/v1/get-scenario-status?jobId=scenario%3A1717200000000%3Aabcd1234"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_scenario_v1_RunScenarioResponse'
                "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: PRO entitlement access denied.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/scenario/v1/get-scenario-status:
        get:
            tags:
                - ScenarioService
            summary: GetScenarioStatus
            description: |-
                GetScenarioStatus polls a single job's result. PRO-gated.
                 Returns status="pending" when no result key exists, mirroring the
                 worker's lifecycle state once the key is written. Requires entitlement tier >= 1.
            operationId: GetScenarioStatus
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: jobId
                  in: query
                  description: |-
                    Job id of the form `scenario:{epoch_ms}:{8-char-suffix}`. Path-traversal
                     guarded by JOB_ID_RE in the handler.
                  required: true
                  example: "scenario:1717200000000:abcd1234"
                  schema:
                    type: string
                    pattern: '^scenario:[0-9]{13}:[a-z0-9]{8}$'
                - 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:
                                "result":
                                    "affectedChokepointIds":
                                        - "hormuz_strait"
                                    "template":
                                        "costShockMultiplier": 2.1
                                        "disruptionPct": 100
                                        "durationDays": 14
                                        "name": "hormuz_strait"
                                    "topImpactCountries":
                                        - "impactPct": 100
                                          "iso2": "US"
                                          "totalImpact": 42.5
                                "status": "done"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_scenario_v1_GetScenarioStatusResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/scenario/v1/list-scenario-templates:
        get:
            tags:
                - ScenarioService
            summary: ListScenarioTemplates
            description: |-
                ListScenarioTemplates returns the catalog of pre-defined scenarios.
                 Not PRO-gated — used by documented public API consumers.
            operationId: ListScenarioTemplates
            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:
                                "templates":
                                    - "affectedChokepointIds":
                                        - "suez"
                                      "affectedHs2":
                                          - "27"
                                      "costShockMultiplier": 75.25
                                      "disruptionPct": 1
                                      "durationDays": 7
                            schema:
                                $ref: '#/components/schemas/worldmonitor_scenario_v1_ListScenarioTemplatesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/seismology/v1/list-earthquakes:
        get:
            tags:
                - SeismologyService
            summary: ListEarthquakes
            description: ListEarthquakes retrieves recent earthquakes from the USGS GeoJSON feed.
            operationId: ListEarthquakes
            security: []
            parameters:
                - name: start
                  in: query
                  description: |-
                    Start of time range (inclusive), Unix epoch milliseconds.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: end
                  in: query
                  description: |-
                    End of time range (inclusive), Unix epoch milliseconds.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: page_size
                  in: query
                  description: |-
                    Maximum items per page. Defaults to 500 when omitted or 0; the handler applies no
                     clamp, so the requested value directly limits the returned list (no enforced maximum).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: min_magnitude
                  in: query
                  description: |-
                    Minimum magnitude filter (e.g., 4.0 for significant quakes).
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 1.5
                  schema:
                    type: number
                    format: double
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "earthquakes":
                                    - "concernLevel": "example"
                                      "concernScore": 42.5
                                      "depthKm": 1.5
                                      "id": "example-id"
                                      "location":
                                          "latitude": 40.7128
                                          "longitude": -74.006
                                      "magnitude": 1.5
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_seismology_v1_ListEarthquakesResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/v2/shipping/route-intelligence:
        get:
            tags:
                - ShippingV2Service
            summary: RouteIntelligence
            description: |-
                RouteIntelligence scores a country-pair trade route for chokepoint exposure
                 and current disruption risk. Partner-facing; wire shape is byte-compatible
                 with the pre-migration JSON response documented at docs/api-shipping-v2.mdx.
                 Empty exposure/bypass arrays with empty fetched_at mean the route snapshot is
                 unavailable/degraded, not that the route has confirmed zero exposure. PRO-gated. Requires an active Pro subscription.
            operationId: RouteIntelligence
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: fromIso2
                  in: query
                  description: Origin country, ISO-3166-1 alpha-2 uppercase.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: toIso2
                  in: query
                  description: Destination country, ISO-3166-1 alpha-2 uppercase.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: cargoType
                  in: query
                  description: |-
                    Cargo type — one of: container (default), tanker, bulk, roro.
                     Empty string defers to the server default. Unknown values are coerced to
                     "container" to preserve legacy behavior.
                  required: false
                  example: "container"
                  schema:
                    type: string
                - name: hs2
                  in: query
                  description: |-
                    2-digit HS commodity code (default "27" — mineral fuels). Non-digit
                     characters are stripped server-side to match legacy behavior.
                  required: false
                  example: "27"
                  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:
                                "bypassOptions":
                                    - "activationThreshold": "example"
                                      "addedCostMultiplier": 75.25
                                      "addedTransitDays": 7
                                      "id": "example-id"
                                      "name": "WorldMonitor Analyst"
                                "cargoType": "container"
                                "chokepointExposures":
                                    - "chokepointId": "suez"
                                      "chokepointName": "WorldMonitor Analyst"
                                      "exposurePct": 1
                                "disruptionScore": 42
                                "fetchedAt": "2026-01-15T12:00:00Z"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_shipping_v2_RouteIntelligenceResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: Pro subscription required.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/v2/shipping/webhooks:
        get:
            tags:
                - ShippingV2Service
            summary: ListWebhooks
            description: |-
                ListWebhooks returns the caller's registered webhooks filtered by the
                 SHA-256 owner tag of the calling API key. The `secret` is intentionally
                 omitted from the response; use rotate-secret to obtain a new one. PRO-gated. Requires an active Pro subscription.
            operationId: ListWebhooks
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            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:
                                "webhooks":
                                    - "active": true
                                      "alertThreshold": 1
                                      "callbackUrl": "https://example.com/worldmonitor-webhook"
                                      "chokepointIds":
                                          - "suez"
                                      "createdAt": "2026-01-15T12:00:00Z"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_shipping_v2_ListWebhooksResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "401":
                    description: Missing or invalid API key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                "403":
                    description: Pro subscription required.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
        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:
                - ShippingV2Service
            summary: RegisterWebhook
            description: |-
                RegisterWebhook subscribes a callback URL to chokepoint disruption alerts.
                 Returns the subscriberId and the raw HMAC secret — the secret is never
                 returned again except via rotate-secret. PRO-gated. Requires an active Pro subscription.
            operationId: RegisterWebhook
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            requestBody:
                content:
                    application/json:
                        example:
                            "alertThreshold": 1
                            "callbackUrl": "https://example.com/worldmonitor-webhook"
                            "chokepointIds":
                                - "suez"
                        schema:
                            $ref: '#/components/schemas/worldmonitor_shipping_v2_RegisterWebhookRequest'
                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:
                                "secret": "example"
                                "subscriberId": "example-id"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_shipping_v2_RegisterWebhookResponse'
                "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: Pro subscription required.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-shipping-rates:
        get:
            tags:
                - SupplyChainService
            summary: GetShippingRates
            description: GetShippingRates returns current container shipping-rate indices; upstream_unavailable is set when the source could not be reached.
            operationId: GetShippingRates
            parameters:
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "indices":
                                    - "changePct": 1.5
                                      "currentValue": 1.5
                                      "history":
                                          - "date": "2026-01-15"
                                            "value": 1.5
                                      "indexId": "example-id"
                                      "name": "WorldMonitor Analyst"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetShippingRatesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-chokepoint-status:
        get:
            tags:
                - SupplyChainService
            summary: GetChokepointStatus
            description: |-
                GetChokepointStatus retrieves seeded chokepoint status. Empty chokepoints
                 with upstream_unavailable=true means the seed snapshot is unavailable/
                 degraded, not that there are confirmed zero chokepoints.
            operationId: GetChokepointStatus
            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:
                                "chokepoints":
                                    - "activeWarnings": 1
                                      "affectedRoutes":
                                          - "example"
                                      "aisDisruptions": 1
                                      "congestionLevel": "example"
                                      "description": "Example WorldMonitor observation."
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetChokepointStatusResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-chokepoint-history:
        get:
            tags:
                - SupplyChainService
            summary: GetChokepointHistory
            description: |-
                GetChokepointHistory returns transit-count history for a single chokepoint,
                 loaded lazily on card expand. Keeps the status RPC compact (no 180-day
                 history per chokepoint on every call).
            operationId: GetChokepointHistory
            parameters:
                - name: chokepointId
                  in: query
                  description: Chokepoint identifier whose transit history should be returned.
                  required: true
                  example: "suez"
                  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:
                                "chokepointId": "suez"
                                "fetchedAt": "1717200000000"
                                "history":
                                    - "capContainer": 1.5
                                      "capDryBulk": 1.5
                                      "capGeneralCargo": 1.5
                                      "capRoro": 1.5
                                      "capTanker": 1.5
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetChokepointHistoryResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-critical-minerals:
        get:
            tags:
                - SupplyChainService
            summary: GetCriticalMinerals
            description: GetCriticalMinerals returns critical-minerals supply indicators; upstream_unavailable is set when the source could not be reached.
            operationId: GetCriticalMinerals
            parameters:
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "minerals":
                                    - "globalProduction": 1.5
                                      "hhi": 1.5
                                      "mineral": "example"
                                      "riskRating": "example"
                                      "topProducers":
                                          - "country": "US"
                                            "countryCode": "US"
                                            "productionTonnes": 1.5
                                            "sharePct": 1.5
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetCriticalMineralsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-shipping-stress:
        get:
            tags:
                - SupplyChainService
            summary: GetShippingStress
            description: GetShippingStress returns carrier market data and a composite stress index.
            operationId: GetShippingStress
            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:
                                "carriers":
                                    - "carrierType": "all"
                                      "changePct": 1.5
                                      "name": "WorldMonitor Analyst"
                                      "price": 75.25
                                      "sparkline":
                                          - 1.5
                                "fetchedAt": 1717200000000
                                "stressLevel": "example"
                                "stressScore": 42.5
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetShippingStressResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-country-chokepoint-index:
        get:
            tags:
                - SupplyChainService
            summary: GetCountryChokepointIndex
            description: GetCountryChokepointIndex returns per-chokepoint exposure scores for a country. PRO-gated. Requires entitlement tier >= 1.
            operationId: GetCountryChokepointIndex
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: iso2
                  in: query
                  description: ISO 3166-1 alpha-2 country code (uppercase).
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: hs2
                  in: query
                  description: HS2 chapter (2-digit string). Defaults to "27" (energy/mineral fuels) when absent.
                  required: false
                  example: "27"
                  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:
                                "exposures":
                                    - "chokepointId": "suez"
                                      "chokepointName": "WorldMonitor Analyst"
                                      "coastSide": "example"
                                      "exposureScore": 42.5
                                      "shockSupported": true
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "hs2": "27"
                                "iso2": "US"
                                "primaryChokepointId": "suez"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetCountryChokepointIndexResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-bypass-options:
        get:
            tags:
                - SupplyChainService
            summary: GetBypassOptions
            description: GetBypassOptions returns ranked bypass corridors for a chokepoint. PRO-gated. Requires entitlement tier >= 1.
            operationId: GetBypassOptions
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: chokepointId
                  in: query
                  description: Chokepoint identifier to evaluate for bypass options.
                  required: true
                  example: "suez"
                  schema:
                    type: string
                - name: cargoType
                  in: query
                  description: 'container | tanker | bulk | roro  (default: "container")'
                  required: false
                  example: "container"
                  schema:
                    type: string
                - name: closurePct
                  in: query
                  description: '0-100, percent of capacity blocked (default: 100)'
                  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:
                                "cargoType": "container"
                                "chokepointId": "suez"
                                "closurePct": 1
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "options":
                                    - "activationThreshold": "example"
                                      "addedCostMultiplier": 75.25
                                      "addedTransitDays": 7
                                      "bypassWarRiskTier": "WAR_RISK_TIER_NORMAL"
                                      "capacityConstraintTonnage": "1717200000000"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetBypassOptionsResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-country-cost-shock:
        get:
            tags:
                - SupplyChainService
            summary: GetCountryCostShock
            description: GetCountryCostShock returns cost shock and war risk data for a country+chokepoint. PRO-gated. Requires entitlement tier >= 1.
            operationId: GetCountryCostShock
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: iso2
                  in: query
                  description: ISO 3166-1 alpha-2 country code for the importing country.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: chokepointId
                  in: query
                  description: Chokepoint identifier to model as disrupted.
                  required: true
                  example: "suez"
                  schema:
                    type: string
                - name: hs2
                  in: query
                  description: 'HS2 chapter (default: "27")'
                  required: false
                  example: "27"
                  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:
                                "chokepointId": "suez"
                                "coverageDays": 7
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "hasEnergyModel": true
                                "hs2": "27"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetCountryCostShockResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-country-products:
        get:
            tags:
                - SupplyChainService
            summary: GetCountryProducts
            description: GetCountryProducts returns the seeded bilateral-HS4 import basket for a country. PRO-gated. Requires entitlement tier >= 1.
            operationId: GetCountryProducts
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: iso2
                  in: query
                  description: ISO 3166-1 alpha-2 country code whose strategic products should be returned.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "iso2": "US"
                                "products":
                                    - "description": "Example WorldMonitor observation."
                                      "hs4": "example"
                                      "topExporters":
                                          - "partnerCode": 1
                                            "partnerIso2": "US"
                                            "share": 1.5
                                            "value": 1.5
                                      "totalValue": 1
                                      "year": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetCountryProductsResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-multi-sector-cost-shock:
        get:
            tags:
                - SupplyChainService
            summary: GetMultiSectorCostShock
            description: |-
                GetMultiSectorCostShock returns per-sector cost-shock estimates for a
                 country+chokepoint+closure-window. PRO-gated. Requires entitlement tier >= 1.
            operationId: GetMultiSectorCostShock
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: iso2
                  in: query
                  description: ISO 3166-1 alpha-2 country code for the importing country.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: chokepointId
                  in: query
                  description: Chokepoint identifier to model as disrupted.
                  required: true
                  example: "suez"
                  schema:
                    type: string
                - name: closureDays
                  in: query
                  description: Closure-window duration in days. Server clamps to [1, 365]. Defaults to 30.
                  required: false
                  example: 7
                  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:
                                "chokepointId": "suez"
                                "closureDays": 7
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "iso2": "US"
                                "sectors":
                                    - "addedTransitDays": 7
                                      "closureDays": 7
                                      "freightAddedPctPerTon": 1.5
                                      "hs2": "27"
                                      "hs2Label": "27"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetMultiSectorCostShockResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-sector-dependency:
        get:
            tags:
                - SupplyChainService
            summary: GetSectorDependency
            description: GetSectorDependency returns dependency flags and risk profile for a country+HS2 sector. PRO-gated. Requires entitlement tier >= 1.
            operationId: GetSectorDependency
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: iso2
                  in: query
                  description: ISO 3166-1 alpha-2 country code whose sector dependency should be analyzed.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: hs2
                  in: query
                  description: HS2 chapter code, e.g. "27" (mineral fuels), "85" (electronics)
                  required: true
                  example: "27"
                  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:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "flags":
                                    - "DEPENDENCY_FLAG_SINGLE_SOURCE_CRITICAL"
                                "hasViableBypass": true
                                "hs2": "27"
                                "hs2Label": "27"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetSectorDependencyResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-route-explorer-lane:
        get:
            tags:
                - SupplyChainService
            summary: GetRouteExplorerLane
            description: |-
                GetRouteExplorerLane returns the primary maritime route, chokepoint exposures,
                 bypass options with geometry, war risk, and static transit/freight estimates for
                 a country pair + HS2 + cargo type. PRO-gated. Wraps the route-intelligence vendor
                 endpoint's compute with browser-callable auth and adds fields needed by the
                 Route Explorer UI. Requires entitlement tier >= 1.
            operationId: GetRouteExplorerLane
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: fromIso2
                  in: query
                  description: ISO 3166-1 alpha-2 origin country code for the trade lane.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: toIso2
                  in: query
                  description: ISO 3166-1 alpha-2 destination country code for the trade lane.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: hs2
                  in: query
                  description: HS2 chapter code, e.g. "27", "85"
                  required: true
                  example: "27"
                  schema:
                    type: string
                - name: cargoType
                  in: query
                  description: 'One of: container, tanker, bulk, roro'
                  required: true
                  example: "container"
                  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:
                                "bypassOptions":
                                    - "addedCostMultiplier": 75.25
                                      "addedTransitDays": 7
                                      "fromPort":
                                          "lat": 40.7128
                                          "lon": -74.006
                                      "id": "example-id"
                                      "name": "WorldMonitor Analyst"
                                "cargoType": "container"
                                "chokepointExposures":
                                    - "chokepointId": "suez"
                                      "chokepointName": "WorldMonitor Analyst"
                                      "exposurePct": 1
                                "disruptionScore": 42.5
                                "estFreightUsdPerTeuRange":
                                    "max": 1
                                    "min": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetRouteExplorerLaneResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-route-impact:
        get:
            tags:
                - SupplyChainService
            summary: GetRouteImpact
            description: 'GetRouteImpact returns route-level trade exposure: lane value, primary exporter concentration, strategic products, resilience score, dependency flags, and Comtrade provenance. PRO-gated. Requires entitlement tier >= 1.'
            operationId: GetRouteImpact
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: fromIso2
                  in: query
                  description: ISO 3166-1 alpha-2 origin country code for the route.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: toIso2
                  in: query
                  description: ISO 3166-1 alpha-2 destination country code for the route.
                  required: true
                  example: "US"
                  schema:
                    type: string
                    pattern: '^[A-Z]{2}$'
                - name: hs2
                  in: query
                  description: HS2 chapter code for the product sector on the route.
                  required: true
                  example: "27"
                  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:
                                "comtradeSource": "example"
                                "dependencyFlags":
                                    - "DEPENDENCY_FLAG_SINGLE_SOURCE_CRITICAL"
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "hs2InSeededUniverse": true
                                "laneValueUsd": 1.5
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetRouteImpactResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/list-pipelines:
        get:
            tags:
                - SupplyChainService
            summary: ListPipelines
            description: |-
                ListPipelines returns the curated oil & gas pipeline registry for the
                 Energy Atlas PathLayer. Public badges are DERIVED from evidence bundles
                 server-side and versioned (classifier_version). Free-tier; see
                 docs/methodology/pipelines.mdx for data + classifier spec.
            operationId: ListPipelines
            parameters:
                - name: commodityType
                  in: query
                  description: Filter to one commodity. Omit (or pass empty) to receive both.
                  required: false
                  example: "oil"
                  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:
                                "classifierVersion": "example"
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "pipelines":
                                    - "capacityBcmYr": 1.5
                                      "capacityMbd": 1.5
                                      "commodityType": "oil"
                                      "endPoint":
                                          "lat": 40.7128
                                          "lon": -74.006
                                      "evidence":
                                          "classifierConfidence": 0.82
                                          "classifierVersion": "example"
                                          "commercialState": "example"
                                          "lastEvidenceUpdate": "2026-01-15"
                                          "operatorStatement":
                                              "date": "2026-01-15"
                                              "text": "example"
                                              "url": "https://example.com/worldmonitor"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_ListPipelinesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-pipeline-detail:
        get:
            tags:
                - SupplyChainService
            summary: GetPipelineDetail
            description: |-
                GetPipelineDetail returns a single pipeline with full evidence bundle
                 + auto-revision-log entries. Loaded lazily on drawer open.
            operationId: GetPipelineDetail
            parameters:
                - name: pipelineId
                  in: query
                  description: Pipeline identifier to load with full evidence details.
                  required: true
                  example: "transmed-pipeline"
                  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:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "pipeline":
                                    "capacityBcmYr": 1.5
                                    "capacityMbd": 1.5
                                    "commodityType": "oil"
                                    "endPoint":
                                        "lat": 40.7128
                                        "lon": -74.006
                                    "evidence":
                                        "classifierConfidence": 0.82
                                        "classifierVersion": "example"
                                        "commercialState": "example"
                                        "lastEvidenceUpdate": "2026-01-15"
                                        "operatorStatement":
                                            "date": "2026-01-15"
                                            "text": "example"
                                            "url": "https://example.com/worldmonitor"
                                "revisions":
                                    - "classifierVersion": "example"
                                      "date": "2026-01-15"
                                      "fieldChanged": "example"
                                      "newValue": "example"
                                      "previousValue": "example"
                                "unavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetPipelineDetailResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/list-storage-facilities:
        get:
            tags:
                - SupplyChainService
            summary: ListStorageFacilities
            description: |-
                ListStorageFacilities returns the curated strategic storage registry
                 (UGS + SPR + LNG + crude tank farms) for the Energy Atlas DeckGL
                 ScatterplotLayer. Public badges are DERIVED from evidence bundles
                 server-side and versioned (classifier_version). Free-tier; see
                 docs/methodology/storage.mdx.
            operationId: ListStorageFacilities
            parameters:
                - name: facilityType
                  in: query
                  description: |-
                    Filter to one facility type. Accepts:
                       "ugs" | "spr" | "lng_export" | "lng_import" | "crude_tank_farm"
                     Omit (or pass empty) to receive all types.
                  required: false
                  example: "ugs"
                  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:
                                "classifierVersion": "example"
                                "facilities":
                                    - "capacityMb": 1.5
                                      "capacityMtpa": 1.5
                                      "capacityTwh": 1.5
                                      "country": "US"
                                      "evidence":
                                          "classifierConfidence": 0.82
                                          "classifierVersion": "example"
                                          "commercialState": "example"
                                          "fillDisclosed": true
                                          "fillSource": "example"
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_ListStorageFacilitiesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-storage-facility-detail:
        get:
            tags:
                - SupplyChainService
            summary: GetStorageFacilityDetail
            description: |-
                GetStorageFacilityDetail returns a single facility with full evidence
                 bundle + revision log. Loaded lazily on drawer open.
            operationId: GetStorageFacilityDetail
            parameters:
                - name: facilityId
                  in: query
                  description: Storage facility identifier to load with full evidence details.
                  required: true
                  example: "rough-storage"
                  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:
                                "facility":
                                    "capacityMb": 1.5
                                    "capacityMtpa": 1.5
                                    "capacityTwh": 1.5
                                    "country": "US"
                                    "evidence":
                                        "classifierConfidence": 0.82
                                        "classifierVersion": "example"
                                        "commercialState": "example"
                                        "fillDisclosed": true
                                        "fillSource": "example"
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "revisions":
                                    - "classifierVersion": "example"
                                      "date": "2026-01-15"
                                      "fieldChanged": "example"
                                      "newValue": "example"
                                      "previousValue": "example"
                                "unavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetStorageFacilityDetailResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/list-fuel-shortages:
        get:
            tags:
                - SupplyChainService
            summary: ListFuelShortages
            description: |-
                ListFuelShortages returns the global fuel-shortage alert registry.
                 Curated-only: severity ("confirmed" | "watch") is a row field authored
                 at curation time, not a client-side derivation. Free tier.
            operationId: ListFuelShortages
            parameters:
                - name: country
                  in: query
                  description: Filter to one ISO 3166-1 alpha-2 country. Omit for global.
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: product
                  in: query
                  description: |-
                    Filter to one product. Accepts: "petrol" | "diesel" | "jet" | "heating_oil".
                     Omit for all products.
                  required: false
                  example: "diesel"
                  schema:
                    type: string
                - name: severity
                  in: query
                  description: 'Filter to one severity. Accepts: "confirmed" | "watch". Omit for both.'
                  required: false
                  example: "watch"
                  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:
                                "classifierVersion": "example"
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "shortages":
                                    - "causeChain":
                                        - "example"
                                      "country": "US"
                                      "evidence":
                                          "classifierConfidence": 0.82
                                          "classifierVersion": "example"
                                          "evidenceSources":
                                              - "authority": "example"
                                                "date": "2026-01-15"
                                                "sourceType": "all"
                                                "title": "example"
                                                "url": "https://example.com/worldmonitor"
                                          "firstRegulatorConfirmation": "40.7128"
                                          "lastEvidenceUpdate": "2026-01-15"
                                      "firstSeen": "example"
                                      "id": "example-id"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_ListFuelShortagesResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/get-fuel-shortage-detail:
        get:
            tags:
                - SupplyChainService
            summary: GetFuelShortageDetail
            description: |-
                GetFuelShortageDetail returns a single shortage with full evidence
                 bundle and citation timeline. Loaded lazily on drawer open.
            operationId: GetFuelShortageDetail
            parameters:
                - name: shortageId
                  in: query
                  description: Fuel-shortage identifier to load with full evidence details.
                  required: true
                  example: "example-id"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "shortage":
                                    "causeChain":
                                        - "example"
                                    "country": "US"
                                    "evidence":
                                        "classifierConfidence": 0.82
                                        "classifierVersion": "example"
                                        "evidenceSources":
                                            - "authority": "example"
                                              "date": "2026-01-15"
                                              "sourceType": "all"
                                              "title": "example"
                                              "url": "https://example.com/worldmonitor"
                                        "firstRegulatorConfirmation": "40.7128"
                                        "lastEvidenceUpdate": "2026-01-15"
                                    "firstSeen": "example"
                                    "id": "example-id"
                                "unavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GetFuelShortageDetailResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/supply-chain/v1/list-energy-disruptions:
        get:
            tags:
                - SupplyChainService
            summary: ListEnergyDisruptions
            description: |-
                ListEnergyDisruptions returns the disruption event log for pipelines
                 and storage facilities. Supports per-asset or per-asset-type filtering
                 so panel drawers can fetch a scoped timeline without pulling the
                 full registry.
            operationId: ListEnergyDisruptions
            parameters:
                - name: assetId
                  in: query
                  description: |-
                    Filter to one asset. Omit for all. When set, also narrows to the
                     matching asset_type if provided.
                  required: false
                  example: "asset-example-1"
                  schema:
                    type: string
                - name: assetType
                  in: query
                  description: 'Filter to one asset type. Accepts: "pipeline" | "storage".'
                  required: false
                  example: "pipeline"
                  schema:
                    type: string
                - name: ongoingOnly
                  in: query
                  description: If true, only return events with endAt empty (still ongoing).
                  required: false
                  example: true
                  schema:
                    type: boolean
                - 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:
                                "classifierVersion": "example"
                                "events":
                                    - "assetId": "asset-example-1"
                                      "assetType": "pipeline"
                                      "capacityOfflineBcmYr": 1.5
                                      "capacityOfflineMbd": 1.5
                                      "causeChain":
                                          - "example"
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_supply_chain_v1_ListEnergyDisruptionsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/thermal/v1/list-thermal-escalations:
        get:
            tags:
                - ThermalService
            summary: ListThermalEscalations
            description: |-
                ListThermalEscalations retrieves seeded thermal anomaly clusters. Empty
                 clusters with empty fetched_at or data_available=false means the seed
                 snapshot is unavailable/degraded, not that escalation is confirmed absent.
            operationId: ListThermalEscalations
            parameters:
                - name: max_items
                  in: query
                  description: Maximum number of thermal escalation clusters to return.
                  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:
                                "clusters":
                                    - "avgBrightness": 1.5
                                      "baselineExpectedCount": 1
                                      "baselineExpectedFrp": 1.5
                                      "centroid":
                                          "latitude": 40.7128
                                          "longitude": -74.006
                                      "confidence": "THERMAL_CONFIDENCE_LOW"
                                "dataAvailable": true
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "observationWindowHours": 1
                                "sourceVersion": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_thermal_v1_ListThermalEscalationsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/trade/v1/get-trade-restrictions:
        get:
            tags:
                - TradeService
            summary: GetTradeRestrictions
            description: Get quantitative restrictions and export controls.
            operationId: GetTradeRestrictions
            parameters:
                - name: countries
                  in: query
                  description: |-
                    WTO member codes to filter by. Empty = all.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  style: form
                  explode: true
                  example:
                      - "840"
                  schema:
                    type: array
                    items:
                        type: string
                - name: limit
                  in: query
                  description: Max results to return (server caps at 100).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "restrictions":
                                    - "affectedCountry": "US"
                                      "description": "Example WorldMonitor observation."
                                      "id": "example-id"
                                      "measureType": "all"
                                      "notifiedAt": "2026-01-15T12:00:00Z"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_trade_v1_GetTradeRestrictionsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/trade/v1/get-tariff-trends:
        get:
            tags:
                - TradeService
            summary: GetTariffTrends
            description: Get tariff rate timeseries for a country pair. PRO-gated. Requires entitlement tier >= 1.
            operationId: GetTariffTrends
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: reporting_country
                  in: query
                  description: WTO member code of reporting country (e.g. "840" = US).
                  required: false
                  example: "840"
                  schema:
                    type: string
                - name: partner_country
                  in: query
                  description: WTO member code of partner country (e.g. "156" = China).
                  required: false
                  example: "156"
                  schema:
                    type: string
                - name: product_sector
                  in: query
                  description: Product sector filter (HS chapter). Empty = aggregate.
                  required: false
                  example: "diesel"
                  schema:
                    type: string
                - name: years
                  in: query
                  description: Number of years to look back (default 10, max 30).
                  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:
                                "datapoints":
                                    - "boundRate": 75.25
                                      "indicatorCode": "example"
                                      "partnerCountry": "156"
                                      "productSector": "diesel"
                                      "reportingCountry": "840"
                                "effectiveTariffRate":
                                    "observationPeriod": "daily"
                                    "sourceName": "WorldMonitor Analyst"
                                    "sourceUrl": "https://example.com/worldmonitor"
                                    "tariffRate": 75.25
                                    "updatedAt": "2026-01-15"
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_trade_v1_GetTariffTrendsResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/trade/v1/get-trade-flows:
        get:
            tags:
                - TradeService
            summary: GetTradeFlows
            description: Get bilateral merchandise trade flows.
            operationId: GetTradeFlows
            parameters:
                - name: reporting_country
                  in: query
                  description: WTO member code of reporting country.
                  required: false
                  example: "840"
                  schema:
                    type: string
                - name: partner_country
                  in: query
                  description: WTO member code of partner country.
                  required: false
                  example: "156"
                  schema:
                    type: string
                - name: years
                  in: query
                  description: Number of years to look back (default 10, max 30).
                  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:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "flows":
                                    - "exportValueUsd": 1.5
                                      "importValueUsd": 1.5
                                      "partnerCountry": "156"
                                      "productSector": "diesel"
                                      "reportingCountry": "840"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_trade_v1_GetTradeFlowsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/trade/v1/get-trade-barriers:
        get:
            tags:
                - TradeService
            summary: GetTradeBarriers
            description: Get SPS/TBT barrier notifications.
            operationId: GetTradeBarriers
            parameters:
                - name: countries
                  in: query
                  description: |-
                    WTO member codes to filter by. Empty = all.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  style: form
                  explode: true
                  example:
                      - "840"
                  schema:
                    type: array
                    items:
                        type: string
                - name: measure_type
                  in: query
                  description: |-
                    Filter by measure type: "SPS", "TBT", or empty for both.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "SPS"
                  schema:
                    type: string
                - name: limit
                  in: query
                  description: Max results to return (server caps at 100).
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "barriers":
                                    - "dateDistributed": "2026-01-15"
                                      "id": "example-id"
                                      "measureType": "SPS"
                                      "notifyingCountry": "US"
                                      "objective": "example"
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_trade_v1_GetTradeBarriersResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/trade/v1/get-customs-revenue:
        get:
            tags:
                - TradeService
            summary: GetCustomsRevenue
            description: Get US customs duties revenue (Treasury MTS data, seeded by Railway).
            operationId: GetCustomsRevenue
            parameters:
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "months":
                                    - "calendarMonth": 1
                                      "calendarYear": 1
                                      "fiscalYear": 1
                                      "fytdAmountBillions": 1.5
                                      "monthlyAmountBillions": 1.5
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_trade_v1_GetCustomsRevenueResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/trade/v1/list-comtrade-flows:
        get:
            tags:
                - TradeService
            summary: ListComtradeFlows
            description: List UN Comtrade strategic commodity flows with anomaly detection. PRO-gated. Requires entitlement tier >= 1.
            operationId: ListComtradeFlows
            security:
                - WorldMonitorKey: []
                - ApiKeyHeader: []
                - BearerAuth: []
            parameters:
                - name: reporter_code
                  in: query
                  description: UN Comtrade reporter code (e.g. "842" = US, "156" = China). Empty returns all reporters.
                  required: false
                  example: "842"
                  schema:
                    type: string
                - name: cmd_code
                  in: query
                  description: HS commodity code (e.g. "2709" = crude oil). Empty returns all commodities.
                  required: false
                  example: "2709"
                  schema:
                    type: string
                    pattern: '^\d{4,6}$'
                - name: anomalies_only
                  in: query
                  description: If true, only return flows with a year-over-year change exceeding 30%.
                  required: false
                  example: true
                  schema:
                    type: boolean
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "fetchedAt": "2026-01-15T12:00:00Z"
                                "flows":
                                    - "cmdCode": "2709"
                                      "cmdDesc": "example"
                                      "isAnomaly": true
                                      "netWeightKg": 1.5
                                      "partnerCode": "example"
                                "upstreamUnavailable": true
                            schema:
                                $ref: '#/components/schemas/worldmonitor_trade_v1_ListComtradeFlowsResponse'
                "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.
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/unrest/v1/list-unrest-events:
        get:
            tags:
                - UnrestService
            summary: ListUnrestEvents
            description: ListUnrestEvents retrieves protest, riot, and civil unrest events.
            operationId: ListUnrestEvents
            security: []
            parameters:
                - name: start
                  in: query
                  description: Start of time range (inclusive), Unix epoch milliseconds.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: end
                  in: query
                  description: End of time range (inclusive), Unix epoch milliseconds.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: page_size
                  in: query
                  description: |-
                    Maximum items per page (1-100).
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: country
                  in: query
                  description: Optional country filter (ISO 3166-1 alpha-2).
                  required: false
                  example: "US"
                  schema:
                    type: string
                - name: min_severity
                  in: query
                  description: |-
                    Optional minimum severity filter.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "SEVERITY_LEVEL_LOW"
                  schema:
                    type: string
                    enum:
                        - 'SEVERITY_LEVEL_LOW'
                        - 'SEVERITY_LEVEL_MEDIUM'
                        - 'SEVERITY_LEVEL_HIGH'
                - name: ne_lat
                  in: query
                  description: |-
                    North-east corner latitude of bounding box.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: ne_lon
                  in: query
                  description: |-
                    North-east corner longitude of bounding box.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: sw_lat
                  in: query
                  description: |-
                    South-west corner latitude of bounding box.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: sw_lon
                  in: query
                  description: |-
                    South-west corner longitude of bounding box.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "clusters":
                                    - "country": "US"
                                      "endAt": 1717200000000
                                      "eventCount": 1
                                      "events":
                                          - "actors":
                                              - "example"
                                            "city": "example"
                                            "confidence": "CONFIDENCE_LEVEL_LOW"
                                            "country": "US"
                                            "eventType": "UNREST_EVENT_TYPE_PROTEST"
                                            "id": "example-id"
                                      "id": "example-id"
                                "events":
                                    - "actors":
                                        - "example"
                                      "city": "example"
                                      "confidence": "CONFIDENCE_LEVEL_LOW"
                                      "country": "US"
                                      "eventType": "UNREST_EVENT_TYPE_PROTEST"
                                      "id": "example-id"
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_unrest_v1_ListUnrestEventsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidationError'
                                    - $ref: '#/components/schemas/JmespathProjectionError'
                "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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/webcam/v1/list-webcams:
        get:
            tags:
                - WebcamService
            summary: ListWebcams
            description: ListWebcams lists webcams in view, grouped into map clusters, with a total-in-view count.
            operationId: ListWebcams
            parameters:
                - name: zoom
                  in: query
                  description: Map zoom level used to decide whether to return webcams or clusters.
                  required: false
                  example: 1
                  schema:
                    type: integer
                    format: int32
                - name: bound_w
                  in: query
                  description: Western longitude bound of the map viewport.
                  required: false
                  example: 1.5
                  schema:
                    type: number
                    format: double
                - name: bound_s
                  in: query
                  description: Southern latitude bound of the map viewport.
                  required: false
                  example: 1.5
                  schema:
                    type: number
                    format: double
                - name: bound_e
                  in: query
                  description: Eastern longitude bound of the map viewport.
                  required: false
                  example: 1.5
                  schema:
                    type: number
                    format: double
                - name: bound_n
                  in: query
                  description: Northern latitude bound of the map viewport.
                  required: false
                  example: 1.5
                  schema:
                    type: number
                    format: double
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "clusters":
                                    - "categories":
                                        - "example"
                                      "count": 1
                                      "lat": 40.7128
                                      "lng": -74.006
                                "totalInView": 1
                                "webcams":
                                    - "category": "cs.AI"
                                      "country": "US"
                                      "lat": 40.7128
                                      "lng": -74.006
                                      "title": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_webcam_v1_ListWebcamsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/webcam/v1/get-webcam-image:
        get:
            tags:
                - WebcamService
            summary: GetWebcamImage
            description: GetWebcamImage resolves a webcam id into its thumbnail and player URLs, title, and last-updated timestamp.
            operationId: GetWebcamImage
            parameters:
                - name: webcam_id
                  in: query
                  description: Webcam identifier to resolve into image and player URLs.
                  required: false
                  example: "example-id"
                  schema:
                    type: string
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "error": "example"
                                "lastUpdated": "2026-01-15T12:00:00.000Z"
                                "playerUrl": "https://example.com/worldmonitor"
                                "thumbnailUrl": "https://example.com/worldmonitor"
                                "title": "example"
                            schema:
                                $ref: '#/components/schemas/worldmonitor_webcam_v1_GetWebcamImageResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
    /api/wildfire/v1/list-fire-detections:
        get:
            tags:
                - WildfireService
            summary: ListFireDetections
            description: |-
                ListFireDetections retrieves satellite-detected active fires from NASA FIRMS.
                 Empty fire_detections with fetched_at=0 or data_available=false means the
                 seed snapshot is unavailable/degraded, not that there are confirmed zero fires.
            operationId: ListFireDetections
            parameters:
                - name: start
                  in: query
                  description: |-
                    Start of time range (inclusive), Unix epoch milliseconds.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: end
                  in: query
                  description: |-
                    End of time range (inclusive), Unix epoch milliseconds.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "1717200000000"
                  schema:
                    type: string
                    format: int64
                - name: page_size
                  in: query
                  description: |-
                    Maximum items per page (1-100).
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 25
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: |-
                    Cursor for next page.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: "next-page-token"
                  schema:
                    type: string
                - name: ne_lat
                  in: query
                  description: |-
                    North-east latitude of bounding box.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: ne_lon
                  in: query
                  description: |-
                    North-east longitude of bounding box.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: sw_lat
                  in: query
                  description: |-
                    South-west latitude of bounding box.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: 40.7128
                  schema:
                    type: number
                    format: double
                - name: sw_lon
                  in: query
                  description: |-
                    South-west longitude of bounding box.
                     Accepted but currently ignored; no-op until this handler supports the parameter.
                  required: false
                  example: -74.006
                  schema:
                    type: number
                    format: double
                - name: jmespath
                  in: query
                  description: |-
                    Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
                  required: false
                  example: "keys(@)"
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            example:
                                "dataAvailable": true
                                "fetchedAt": 1717200000000
                                "fireDetections":
                                    - "brightness": 1.5
                                      "confidence": "FIRE_CONFIDENCE_LOW"
                                      "dayNight": "example"
                                      "detectedAt": 1717200000000
                                      "frp": 1.5
                                      "id": "example-id"
                                "pagination":
                                    "nextCursor": "next-page-token"
                                    "totalCount": 1
                            schema:
                                $ref: '#/components/schemas/worldmonitor_wildfire_v1_ListFireDetectionsResponse'
                "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).
                    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'
                default:
                    description: Gateway or handler error response.
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/Error'
                                    - $ref: '#/components/schemas/GatewayError'
webhooks:
    chokepoint.disruption:
        post:
            tags:
                - ShippingV2Service
            summary: Chokepoint disruption alert (outbound, signed)
            description: |-
                WorldMonitor POSTs this event to the `callbackUrl` you register via
                RegisterWebhook whenever a subscribed chokepoint's disruption score
                crosses your `alertThreshold`. Every delivery is signed so you can
                confirm it genuinely came from WorldMonitor.

                Verification: the `X-WM-Signature` header is
                `sha256=<hex>`, where `<hex>` is the lowercase hex HMAC-SHA256 of the
                exact raw request body, keyed by the `secret` returned when you
                registered the webhook. To verify, recompute
                `sha256=` + hex(HMAC_SHA256(key=secret, message=rawRequestBody)) over
                the bytes exactly as received (do not re-serialize the JSON) and
                compare against `X-WM-Signature` in constant time. Use the
                `secret` string verbatim as the HMAC key — do not hex-decode it.
                Reject the delivery if the signatures differ.

                A verifiable signed sample (fixed secret + exact raw body +
                resulting signature) is published at
                https://www.worldmonitor.app/.well-known/webhook-sample.json so you
                can confirm your HMAC verification end-to-end before registering.

                Respond with any 2xx to acknowledge receipt; a non-2xx response or a
                timeout marks the delivery failed. `X-WM-Delivery-Id` uniquely
                identifies each delivery for idempotent processing.
            operationId: ChokepointDisruptionWebhook
            security: []
            parameters:
                - name: X-WM-Signature
                  in: header
                  required: true
                  description: |-
                      HMAC-SHA256 signature of the raw request body, keyed by the
                      subscription `secret`, formatted as `sha256=<lowercase-hex>`.
                  schema:
                      type: string
                      pattern: ^sha256=[0-9a-f]{64}$
                      example: sha256=2b8c0d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c
                - name: X-WM-Event
                  in: header
                  required: true
                  description: Event type. Currently always `chokepoint.disruption`.
                  schema:
                      type: string
                      example: chokepoint.disruption
                - name: X-WM-Delivery-Id
                  in: header
                  required: true
                  description: |-
                      Unique delivery identifier (`whd_` + 32 hex chars). Use it to
                      dedupe retries and process deliveries idempotently.
                  schema:
                      type: string
                      pattern: ^whd_[0-9a-f]{32}$
                      example: whd_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - subscriberId
                                - chokepointId
                                - score
                                - alertThreshold
                                - triggeredAt
                                - reason
                            properties:
                                subscriberId:
                                    type: string
                                    description: The `wh_`-prefixed subscription receiving this alert.
                                chokepointId:
                                    type: string
                                    description: Chokepoint that breached the threshold (e.g. `suez`).
                                score:
                                    type: number
                                    description: Current disruption score of the chokepoint, 0-100.
                                alertThreshold:
                                    type: number
                                    description: The subscription's configured alert threshold, 0-100.
                                triggeredAt:
                                    type: string
                                    format: date-time
                                    description: ISO-8601 timestamp when the alert fired.
                                reason:
                                    type: string
                                    description: Human-readable explanation for the alert.
                                details:
                                    type: object
                                    additionalProperties: true
                                    description: Optional structured context for the disruption.
                        example:
                            "subscriberId": "wh_1a2b3c4d5e6f7a8b9c0d1e2f"
                            "chokepointId": "suez"
                            "score": 72
                            "alertThreshold": 50
                            "triggeredAt": "2026-07-04T12:34:56Z"
                            "reason": "Disruption score 72 crossed alert threshold 50"
                            "details":
                                "trend": "rising"
            responses:
                "2XX":
                    description: |-
                        Any 2xx acknowledges receipt. A non-2xx response or a delivery
                        timeout marks the delivery failed.
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.
        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.
                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.
        worldmonitor_aviation_v1_ListAirportDelaysRequest:
            type: object
            properties:
                pageSize:
                    type: integer
                    format: int32
                    description: |-
                        Maximum items per page (1-100).
                         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.
                region:
                    type: string
                    enum:
                        - AIRPORT_REGION_UNSPECIFIED
                        - AIRPORT_REGION_AMERICAS
                        - AIRPORT_REGION_EUROPE
                        - AIRPORT_REGION_APAC
                        - AIRPORT_REGION_MENA
                        - AIRPORT_REGION_AFRICA
                    description: AirportRegion represents the geographic region of an airport.
                minSeverity:
                    type: string
                    enum:
                        - FLIGHT_DELAY_SEVERITY_UNSPECIFIED
                        - FLIGHT_DELAY_SEVERITY_NORMAL
                        - FLIGHT_DELAY_SEVERITY_MINOR
                        - FLIGHT_DELAY_SEVERITY_MODERATE
                        - FLIGHT_DELAY_SEVERITY_MAJOR
                        - FLIGHT_DELAY_SEVERITY_SEVERE
                        - FLIGHT_DELAY_SEVERITY_UNKNOWN
                    description: |-
                        FlightDelaySeverity represents the severity of flight delays at an airport.
                         Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe' | 'unknown'.
            description: ListAirportDelaysRequest specifies filters for retrieving airport delay alerts.
        worldmonitor_aviation_v1_ListAirportDelaysResponse:
            type: object
            properties:
                alerts:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_aviation_v1_AirportDelayAlert'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListAirportDelaysResponse contains airport delay alerts matching the request.
        worldmonitor_aviation_v1_AirportDelayAlert:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Unique alert identifier.
                iata:
                    type: string
                    description: IATA airport code (e.g., "JFK").
                icao:
                    type: string
                    description: ICAO airport code (e.g., "KJFK").
                name:
                    type: string
                    description: Airport name.
                city:
                    type: string
                    description: City where the airport is located.
                country:
                    type: string
                    description: Country code (ISO 3166-1 alpha-2).
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                region:
                    type: string
                    enum:
                        - AIRPORT_REGION_UNSPECIFIED
                        - AIRPORT_REGION_AMERICAS
                        - AIRPORT_REGION_EUROPE
                        - AIRPORT_REGION_APAC
                        - AIRPORT_REGION_MENA
                        - AIRPORT_REGION_AFRICA
                    description: AirportRegion represents the geographic region of an airport.
                delayType:
                    type: string
                    enum:
                        - FLIGHT_DELAY_TYPE_UNSPECIFIED
                        - FLIGHT_DELAY_TYPE_GROUND_STOP
                        - FLIGHT_DELAY_TYPE_GROUND_DELAY
                        - FLIGHT_DELAY_TYPE_DEPARTURE_DELAY
                        - FLIGHT_DELAY_TYPE_ARRIVAL_DELAY
                        - FLIGHT_DELAY_TYPE_GENERAL
                        - FLIGHT_DELAY_TYPE_CLOSURE
                    description: FlightDelayType represents the type of flight delay.
                severity:
                    type: string
                    enum:
                        - FLIGHT_DELAY_SEVERITY_UNSPECIFIED
                        - FLIGHT_DELAY_SEVERITY_NORMAL
                        - FLIGHT_DELAY_SEVERITY_MINOR
                        - FLIGHT_DELAY_SEVERITY_MODERATE
                        - FLIGHT_DELAY_SEVERITY_MAJOR
                        - FLIGHT_DELAY_SEVERITY_SEVERE
                        - FLIGHT_DELAY_SEVERITY_UNKNOWN
                    description: |-
                        FlightDelaySeverity represents the severity of flight delays at an airport.
                         Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe' | 'unknown'.
                avgDelayMinutes:
                    type: integer
                    format: int32
                    description: Average delay in minutes.
                delayedFlightsPct:
                    type: number
                    format: double
                    description: Percentage of delayed flights.
                cancelledFlights:
                    type: integer
                    format: int32
                    description: Number of cancelled flights.
                totalFlights:
                    type: integer
                    format: int32
                    description: Total flights scheduled.
                reason:
                    type: string
                    description: Human-readable reason for delays.
                source:
                    type: string
                    enum:
                        - FLIGHT_DELAY_SOURCE_UNSPECIFIED
                        - FLIGHT_DELAY_SOURCE_FAA
                        - FLIGHT_DELAY_SOURCE_EUROCONTROL
                        - FLIGHT_DELAY_SOURCE_COMPUTED
                        - FLIGHT_DELAY_SOURCE_AVIATIONSTACK
                        - FLIGHT_DELAY_SOURCE_NOTAM
                    description: FlightDelaySource represents the source of delay data.
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Last data update time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            required:
                - id
            description: |-
                AirportDelayAlert represents a flight delay advisory at an airport.
                 Sourced from FAA and Eurocontrol.
        worldmonitor_core_v1_GeoCoordinates:
            type: object
            properties:
                latitude:
                    type: number
                    maximum: 90
                    minimum: -90
                    format: double
                    description: Latitude in decimal degrees (-90 to 90).
                longitude:
                    type: number
                    maximum: 180
                    minimum: -180
                    format: double
                    description: Longitude in decimal degrees (-180 to 180).
            description: GeoCoordinates represents a geographic location using WGS84 coordinates.
        worldmonitor_core_v1_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.
        worldmonitor_aviation_v1_GetAirportOpsSummaryRequest:
            type: object
            properties:
                airports:
                    type: array
                    items:
                        type: string
                        maxItems: 20
                        minItems: 1
                        description: IATA airport codes to query (e.g., ["IST", "ESB", "LHR"]).
                    maxItems: 20
                    minItems: 1
            description: GetAirportOpsSummaryRequest specifies which airports to summarize.
        worldmonitor_aviation_v1_GetAirportOpsSummaryResponse:
            type: object
            properties:
                summaries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_aviation_v1_AirportOpsSummary'
                cacheHit:
                    type: boolean
                    description: Whether the response was served from cache.
            description: GetAirportOpsSummaryResponse contains operational summaries for requested airports.
        worldmonitor_aviation_v1_AirportOpsSummary:
            type: object
            properties:
                iata:
                    type: string
                    description: IATA airport code.
                icao:
                    type: string
                    description: ICAO airport code.
                name:
                    type: string
                    description: Airport name.
                timezone:
                    type: string
                    description: IANA timezone (e.g., "Europe/Istanbul").
                delayPct:
                    type: number
                    format: double
                    description: Percentage of flights currently delayed (0-100).
                avgDelayMinutes:
                    type: integer
                    format: int32
                    description: Average delay in minutes across delayed flights.
                cancellationRate:
                    type: number
                    format: double
                    description: Cancellation rate as a percentage (0-100).
                totalFlights:
                    type: integer
                    format: int32
                    description: Total flights in the observation window.
                closureStatus:
                    type: boolean
                    description: Whether the airport is currently closed.
                notamFlags:
                    type: array
                    items:
                        type: string
                        description: Active NOTAM summary flags (e.g., "RWY 06/24 CLSD", "LOW VIS OPS").
                severity:
                    type: string
                    enum:
                        - FLIGHT_DELAY_SEVERITY_UNSPECIFIED
                        - FLIGHT_DELAY_SEVERITY_NORMAL
                        - FLIGHT_DELAY_SEVERITY_MINOR
                        - FLIGHT_DELAY_SEVERITY_MODERATE
                        - FLIGHT_DELAY_SEVERITY_MAJOR
                        - FLIGHT_DELAY_SEVERITY_SEVERE
                        - FLIGHT_DELAY_SEVERITY_UNKNOWN
                    description: |-
                        FlightDelaySeverity represents the severity of flight delays at an airport.
                         Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe' | 'unknown'.
                topDelayReasons:
                    type: array
                    items:
                        type: string
                        description: Top reasons for delays.
                source:
                    type: string
                    description: Data source identifier.
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: AirportOpsSummary contains operational health metrics for a single airport.
        worldmonitor_aviation_v1_ListAirportFlightsRequest:
            type: object
            properties:
                airport:
                    type: string
                    maxLength: 4
                    minLength: 3
                    description: IATA airport code (e.g., "IST").
                direction:
                    type: string
                    enum:
                        - FLIGHT_DIRECTION_UNSPECIFIED
                        - FLIGHT_DIRECTION_DEPARTURE
                        - FLIGHT_DIRECTION_ARRIVAL
                        - FLIGHT_DIRECTION_BOTH
                    description: FlightDirection specifies whether to retrieve departures, arrivals, or both.
                limit:
                    type: integer
                    maximum: 100
                    minimum: 1
                    format: int32
                    description: Maximum number of flights to return (1-100).
            required:
                - airport
            description: ListAirportFlightsRequest specifies parameters for retrieving recent flights at an airport.
        worldmonitor_aviation_v1_ListAirportFlightsResponse:
            type: object
            properties:
                flights:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_aviation_v1_FlightInstance'
                totalAvailable:
                    type: integer
                    format: int32
                    description: Total number of flights available from the provider.
                source:
                    type: string
                    description: Data source identifier.
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: ListAirportFlightsResponse contains recent flights at an airport.
        worldmonitor_aviation_v1_FlightInstance:
            type: object
            properties:
                flightNumber:
                    type: string
                    description: IATA flight number (e.g., "TK1952").
                date:
                    type: string
                    description: Departure date in ISO 8601 format (e.g., "2026-03-05").
                operatingCarrier:
                    $ref: '#/components/schemas/worldmonitor_aviation_v1_Carrier'
                origin:
                    $ref: '#/components/schemas/worldmonitor_aviation_v1_AirportRef'
                destination:
                    $ref: '#/components/schemas/worldmonitor_aviation_v1_AirportRef'
                scheduledDeparture:
                    type: integer
                    format: int64
                    description: 'Scheduled departure time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
                estimatedDeparture:
                    type: integer
                    format: int64
                    description: 'Estimated departure time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
                actualDeparture:
                    type: integer
                    format: int64
                    description: 'Actual departure time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
                scheduledArrival:
                    type: integer
                    format: int64
                    description: 'Scheduled arrival time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
                estimatedArrival:
                    type: integer
                    format: int64
                    description: 'Estimated arrival time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
                actualArrival:
                    type: integer
                    format: int64
                    description: 'Actual arrival time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
                status:
                    type: string
                    enum:
                        - FLIGHT_INSTANCE_STATUS_UNSPECIFIED
                        - FLIGHT_INSTANCE_STATUS_SCHEDULED
                        - FLIGHT_INSTANCE_STATUS_BOARDING
                        - FLIGHT_INSTANCE_STATUS_DEPARTED
                        - FLIGHT_INSTANCE_STATUS_AIRBORNE
                        - FLIGHT_INSTANCE_STATUS_LANDED
                        - FLIGHT_INSTANCE_STATUS_ARRIVED
                        - FLIGHT_INSTANCE_STATUS_CANCELLED
                        - FLIGHT_INSTANCE_STATUS_DIVERTED
                        - FLIGHT_INSTANCE_STATUS_UNKNOWN
                    description: FlightInstanceStatus represents the operational status of a flight occurrence.
                delayMinutes:
                    type: integer
                    format: int32
                    description: Delay in minutes (0 if on time, negative if early).
                cancelled:
                    type: boolean
                    description: Whether the flight is cancelled.
                diverted:
                    type: boolean
                    description: Whether the flight has been diverted.
                gate:
                    type: string
                    description: Departure gate (if available).
                terminal:
                    type: string
                    description: Departure terminal (if available).
                aircraftIcao24:
                    type: string
                    description: ICAO 24-bit transponder address of the aircraft (hex, e.g., "4b1805").
                aircraftType:
                    type: string
                    description: Aircraft type designator (e.g., "B738").
                codeshareFlightNumbers:
                    type: array
                    items:
                        type: string
                        description: Codeshare flight numbers marketed under this operating flight.
                source:
                    type: string
                    description: Data source provider name.
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: FlightInstance represents a specific occurrence of a flight on a given date.
        worldmonitor_aviation_v1_Carrier:
            type: object
            properties:
                iataCode:
                    type: string
                    description: IATA two-letter airline code (e.g., "TK").
                icaoCode:
                    type: string
                    description: ICAO three-letter airline code (e.g., "THY").
                name:
                    type: string
                    description: Full airline name (e.g., "Turkish Airlines").
            description: Carrier represents an airline or aircraft operator.
        worldmonitor_aviation_v1_AirportRef:
            type: object
            properties:
                iata:
                    type: string
                    description: IATA airport code (e.g., "IST").
                icao:
                    type: string
                    description: ICAO airport code (e.g., "LTFM").
                name:
                    type: string
                    description: Airport name (e.g., "Istanbul Airport").
                timezone:
                    type: string
                    description: IANA timezone (e.g., "Europe/Istanbul").
            description: AirportRef is a lightweight reference to an airport.
        worldmonitor_aviation_v1_GetCarrierOpsRequest:
            type: object
            properties:
                airports:
                    type: array
                    items:
                        type: string
                        maxItems: 20
                        minItems: 1
                        description: IATA airport codes to aggregate carrier metrics from.
                    maxItems: 20
                    minItems: 1
                minFlights:
                    type: integer
                    minimum: 0
                    format: int32
                    description: 'Minimum number of flights required to include a carrier (default: 1).'
            description: GetCarrierOpsRequest specifies parameters for carrier operations metrics.
        worldmonitor_aviation_v1_GetCarrierOpsResponse:
            type: object
            properties:
                carriers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_aviation_v1_CarrierOpsSummary'
                source:
                    type: string
                    description: Data source identifier.
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: GetCarrierOpsResponse contains carrier operations metrics.
        worldmonitor_aviation_v1_CarrierOpsSummary:
            type: object
            properties:
                carrier:
                    $ref: '#/components/schemas/worldmonitor_aviation_v1_Carrier'
                airport:
                    type: string
                    description: Airport IATA code this summary applies to.
                totalFlights:
                    type: integer
                    format: int32
                    description: Total flights observed.
                delayedCount:
                    type: integer
                    format: int32
                    description: Number of delayed flights.
                cancelledCount:
                    type: integer
                    format: int32
                    description: Number of cancelled flights.
                avgDelayMinutes:
                    type: integer
                    format: int32
                    description: Average delay in minutes across delayed flights.
                delayPct:
                    type: number
                    format: double
                    description: Delay percentage (0-100).
                cancellationRate:
                    type: number
                    format: double
                    description: Cancellation rate (0-100).
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: CarrierOpsSummary contains delay and cancellation metrics for a carrier at an airport.
        worldmonitor_aviation_v1_GetFlightStatusRequest:
            type: object
            properties:
                flightNumber:
                    type: string
                    maxLength: 10
                    minLength: 3
                    description: IATA flight number (e.g., "TK1952").
                date:
                    type: string
                    description: Departure date in ISO 8601 format (e.g., "2026-03-05").
                origin:
                    type: string
                    description: Optional origin airport IATA code to disambiguate.
            required:
                - flightNumber
                - date
            description: GetFlightStatusRequest specifies a flight to look up.
        worldmonitor_aviation_v1_GetFlightStatusResponse:
            type: object
            properties:
                flights:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_aviation_v1_FlightInstance'
                source:
                    type: string
                    description: Data source identifier.
                cacheHit:
                    type: boolean
                    description: Whether the response was served from cache.
            description: GetFlightStatusResponse contains flight status results.
        worldmonitor_aviation_v1_TrackAircraftRequest:
            type: object
            properties:
                icao24:
                    type: string
                    description: ICAO 24-bit transponder address (hex, e.g., "4b1805").
                callsign:
                    type: string
                    description: ATC callsign (e.g., "THY7CX").
                swLat:
                    type: number
                    format: double
                    description: Optional bounding box south-west latitude.
                swLon:
                    type: number
                    format: double
                    description: Optional bounding box south-west longitude.
                neLat:
                    type: number
                    format: double
                    description: Optional bounding box north-east latitude.
                neLon:
                    type: number
                    format: double
                    description: Optional bounding box north-east longitude.
            description: TrackAircraftRequest specifies an aircraft to track.
        worldmonitor_aviation_v1_TrackAircraftResponse:
            type: object
            properties:
                positions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_aviation_v1_PositionSample'
                source:
                    type: string
                    description: Data source identifier.
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: TrackAircraftResponse contains aircraft position observations.
        worldmonitor_aviation_v1_PositionSample:
            type: object
            properties:
                icao24:
                    type: string
                    description: ICAO 24-bit transponder address (hex, e.g., "4b1805").
                callsign:
                    type: string
                    description: ATC callsign (e.g., "THY7CX").
                lat:
                    type: number
                    format: double
                    description: Latitude in decimal degrees.
                lon:
                    type: number
                    format: double
                    description: Longitude in decimal degrees.
                altitudeM:
                    type: number
                    format: double
                    description: Barometric altitude in metres.
                groundSpeedKts:
                    type: number
                    format: double
                    description: Ground speed in knots.
                trackDeg:
                    type: number
                    format: double
                    description: True track over ground in degrees (0 = North, clockwise).
                verticalRate:
                    type: number
                    format: double
                    description: Vertical rate in metres per second (positive = climbing).
                onGround:
                    type: boolean
                    description: Whether the aircraft is on the ground.
                source:
                    type: string
                    enum:
                        - POSITION_SOURCE_UNSPECIFIED
                        - POSITION_SOURCE_OPENSKY
                        - POSITION_SOURCE_WINGBITS
                        - POSITION_SOURCE_SIMULATED
                    description: PositionSource identifies the provider of aircraft position data.
                observedAt:
                    type: integer
                    format: int64
                    description: 'Observation time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: PositionSample represents a single aircraft position observation.
        worldmonitor_aviation_v1_GetYoutubeLiveStreamInfoRequest:
            type: object
            properties:
                channel:
                    type: string
                    description: YouTube channel handle or ID.
                videoId:
                    type: string
                    description: Specific video ID to check.
            description: GetYoutubeLiveStreamInfoRequest parameters for detecting live status.
        worldmonitor_aviation_v1_GetYoutubeLiveStreamInfoResponse:
            type: object
            properties:
                videoId:
                    type: string
                    description: Video ID of the live stream (if found).
                isLive:
                    type: boolean
                    description: Whether the stream is currently live.
                channelExists:
                    type: boolean
                    description: Whether the channel exists.
                channelName:
                    type: string
                    description: Human-readable channel name.
                hlsUrl:
                    type: string
                    description: HLS manifest URL (if available).
                title:
                    type: string
                    description: Stream title.
                error:
                    type: string
                    description: Optional error message.
            description: GetYoutubeLiveStreamInfoResponse containing detection results.
        worldmonitor_aviation_v1_SearchFlightPricesRequest:
            type: object
            properties:
                origin:
                    type: string
                    maxLength: 4
                    minLength: 3
                    description: Origin airport IATA code.
                destination:
                    type: string
                    maxLength: 4
                    minLength: 3
                    description: Destination airport IATA code.
                departureDate:
                    type: string
                    description: Outbound departure date (ISO 8601).
                returnDate:
                    type: string
                    description: Return date (ISO 8601), empty for one-way.
                adults:
                    type: integer
                    maximum: 9
                    minimum: 1
                    format: int32
                    description: Number of adult passengers (1-9).
                cabin:
                    type: string
                    enum:
                        - CABIN_CLASS_UNSPECIFIED
                        - CABIN_CLASS_ECONOMY
                        - CABIN_CLASS_PREMIUM_ECONOMY
                        - CABIN_CLASS_BUSINESS
                        - CABIN_CLASS_FIRST
                    description: CabinClass represents the travel class for a flight ticket.
                nonstopOnly:
                    type: boolean
                    description: Whether to restrict to nonstop flights only.
                maxResults:
                    type: integer
                    maximum: 50
                    minimum: 1
                    format: int32
                    description: Maximum number of quotes to return (1-50).
                currency:
                    type: string
                    description: ISO 4217 currency code for prices (e.g., "usd", "eur", "try").
                market:
                    type: string
                    description: Market/locale code (e.g., "us", "tr").
            required:
                - origin
                - destination
                - departureDate
            description: SearchFlightPricesRequest specifies parameters for a flight price search.
        worldmonitor_aviation_v1_SearchFlightPricesResponse:
            type: object
            properties:
                quotes:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_aviation_v1_PriceQuote'
                provider:
                    type: string
                    description: |-
                        Provider name: "travelpayouts_data", "demo", or "none" when no live
                         provider is configured.
                isDemoMode:
                    type: boolean
                    description: |-
                        Whether results are from demo/simulated mode. Requires explicit
                         AVIATION_DEMO_PRICES=1 opt-in on the server. Never true in default
                         self-host / production runs. See issue #3756.
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                isIndicative:
                    type: boolean
                    description: Whether returned prices are indicative (subject to change).
                degraded:
                    type: boolean
                    description: |-
                        True when the live provider could not satisfy the request — missing
                         credentials, upstream failure, or zero results. Mirrors the
                         searchGoogleFlights pattern so clients can render distinct messages
                         for each error class.
                error:
                    type: string
                    description: |-
                        Discriminator for the degraded state: "" (ok), "missing_credentials"
                         (TRAVELPAYOUTS_API_TOKEN unset), "upstream_error" (provider call
                         threw), "no_results" (provider returned empty for this route).
            description: SearchFlightPricesResponse contains flight price offers.
        worldmonitor_aviation_v1_PriceQuote:
            type: object
            properties:
                id:
                    type: string
                    description: Unique quote identifier.
                origin:
                    type: string
                    description: Origin airport IATA code.
                destination:
                    type: string
                    description: Destination airport IATA code.
                departureDate:
                    type: string
                    description: Outbound departure date (ISO 8601).
                returnDate:
                    type: string
                    description: Return date (ISO 8601), empty for one-way.
                carrier:
                    $ref: '#/components/schemas/worldmonitor_aviation_v1_Carrier'
                priceAmount:
                    type: number
                    format: double
                    description: Total price amount.
                currency:
                    type: string
                    description: ISO 4217 currency code (e.g., "EUR", "USD", "TRY").
                cabin:
                    type: string
                    enum:
                        - CABIN_CLASS_UNSPECIFIED
                        - CABIN_CLASS_ECONOMY
                        - CABIN_CLASS_PREMIUM_ECONOMY
                        - CABIN_CLASS_BUSINESS
                        - CABIN_CLASS_FIRST
                    description: CabinClass represents the travel class for a flight ticket.
                stops:
                    type: integer
                    format: int32
                    description: Number of stops (0 = nonstop).
                durationMinutes:
                    type: integer
                    format: int32
                    description: Total travel duration in minutes.
                bookingUrl:
                    type: string
                    description: Booking URL or deep-link (if available).
                provider:
                    type: string
                    description: Provider name (e.g., "amadeus", "demo").
                isIndicative:
                    type: boolean
                    description: Whether the price is indicative rather than bookable.
                observedAt:
                    type: integer
                    format: int64
                    description: 'Time when this quote was observed, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                checkoutRef:
                    type: string
                    description: Reference used during the checkout process (for follow-up actions).
                expiresAt:
                    type: integer
                    format: int64
                    description: 'Time when this quote expires, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: PriceQuote represents a single flight price offer from a provider.
        worldmonitor_aviation_v1_ListAviationNewsRequest:
            type: object
            properties:
                entities:
                    type: array
                    items:
                        type: string
                        maxItems: 10
                        minItems: 1
                        description: Entities to filter by (airline names, airport codes, route strings).
                    maxItems: 10
                    minItems: 1
                windowHours:
                    type: integer
                    maximum: 168
                    minimum: 1
                    format: int32
                    description: Time window in hours to look back (1-168).
                maxItems:
                    type: integer
                    maximum: 50
                    minimum: 1
                    format: int32
                    description: Maximum number of news items to return (1-50).
            description: ListAviationNewsRequest specifies filters for aviation news retrieval.
        worldmonitor_aviation_v1_ListAviationNewsResponse:
            type: object
            properties:
                items:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_aviation_v1_AviationNewsItem'
                source:
                    type: string
                    description: Data source identifier.
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: ListAviationNewsResponse contains filtered aviation news items.
        worldmonitor_aviation_v1_AviationNewsItem:
            type: object
            properties:
                id:
                    type: string
                    description: Unique item identifier (hash of URL).
                title:
                    type: string
                    description: Article title.
                url:
                    type: string
                    description: Article URL.
                sourceName:
                    type: string
                    description: Name of the news source (e.g., "FlightGlobal").
                publishedAt:
                    type: integer
                    format: int64
                    description: 'Publication time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                snippet:
                    type: string
                    description: Short text snippet or description.
                matchedEntities:
                    type: array
                    items:
                        type: string
                        description: Entities matched from the query (airport codes, airline names).
                imageUrl:
                    type: string
                    description: Article image URL (if available).
            description: AviationNewsItem represents a single aviation news article or press release.
        worldmonitor_aviation_v1_SearchGoogleFlightsRequest:
            type: object
            properties:
                origin:
                    type: string
                    description: Departure airport IATA code (e.g. "JFK").
                destination:
                    type: string
                    description: Arrival airport IATA code (e.g. "LHR").
                departureDate:
                    type: string
                    description: Departure date in YYYY-MM-DD format.
                returnDate:
                    type: string
                    description: Return date in YYYY-MM-DD format; omit for one-way.
                cabinClass:
                    type: string
                    description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.'
                maxStops:
                    type: string
                    description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.'
                departureWindow:
                    type: string
                    description: Departure time window in HH-HH format (e.g. "6-20").
                airlines:
                    type: array
                    items:
                        type: string
                        description: Airline IATA codes to filter by (e.g. ["BA", "AA"]).
                sortBy:
                    type: string
                    description: 'Sort order: CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME.'
                passengers:
                    type: integer
                    format: int32
                    description: Number of adult passengers (1-9).
            description: SearchGoogleFlightsRequest specifies parameters for a Google Flights search.
        worldmonitor_aviation_v1_SearchGoogleFlightsResponse:
            type: object
            properties:
                flights:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_aviation_v1_GoogleFlightResult'
                degraded:
                    type: boolean
                error:
                    type: string
            description: SearchGoogleFlightsResponse contains flight results from Google Flights.
        worldmonitor_aviation_v1_GoogleFlightResult:
            type: object
            properties:
                legs:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_aviation_v1_GoogleFlightLeg'
                price:
                    type: number
                    format: double
                durationMinutes:
                    type: integer
                    format: int32
                stops:
                    type: integer
                    format: int32
            description: GoogleFlightResult represents a complete itinerary (one or more legs).
        worldmonitor_aviation_v1_GoogleFlightLeg:
            type: object
            properties:
                airlineCode:
                    type: string
                flightNumber:
                    type: string
                departureAirport:
                    type: string
                arrivalAirport:
                    type: string
                departureDatetime:
                    type: string
                    description: ISO 8601 local datetime, e.g. "2025-06-01T08:45".
                arrivalDatetime:
                    type: string
                durationMinutes:
                    type: integer
                    format: int32
            description: GoogleFlightLeg represents a single flight segment (one plane, one takeoff and landing).
        worldmonitor_aviation_v1_SearchGoogleDatesRequest:
            type: object
            properties:
                origin:
                    type: string
                    description: Departure airport IATA code (e.g. "JFK").
                destination:
                    type: string
                    description: Arrival airport IATA code (e.g. "LHR").
                startDate:
                    type: string
                    description: Start of date range in YYYY-MM-DD format.
                endDate:
                    type: string
                    description: End of date range in YYYY-MM-DD format.
                tripDuration:
                    type: integer
                    format: int32
                    description: Trip duration in days (required for round-trip searches).
                isRoundTrip:
                    type: boolean
                    description: Whether to search for round-trip flights.
                cabinClass:
                    type: string
                    description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.'
                maxStops:
                    type: string
                    description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.'
                departureWindow:
                    type: string
                    description: Departure time window in HH-HH format (e.g. "6-20").
                airlines:
                    type: array
                    items:
                        type: string
                        description: Airline IATA codes to filter by (e.g. ["BA", "AA"]).
                sortByPrice:
                    type: boolean
                    description: Whether to sort results by price (lowest first).
                passengers:
                    type: integer
                    format: int32
                    description: Number of adult passengers (1-9).
            description: SearchGoogleDatesRequest specifies parameters for a Google Flights date-range price search.
        worldmonitor_aviation_v1_SearchGoogleDatesResponse:
            type: object
            properties:
                dates:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_aviation_v1_DatePriceEntry'
                degraded:
                    type: boolean
                error:
                    type: string
            description: SearchGoogleDatesResponse contains cheapest-date results from Google Flights.
        worldmonitor_aviation_v1_DatePriceEntry:
            type: object
            properties:
                date:
                    type: string
                    description: Departure date in YYYY-MM-DD format.
                returnDate:
                    type: string
                    description: Return date in YYYY-MM-DD format; empty for one-way results.
                price:
                    type: number
                    format: double
            description: DatePriceEntry pairs a departure date (and optional return date) with its cheapest price.
        worldmonitor_batch_v1_ExecuteBatchRequest:
            type: object
            properties:
                operations:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_batch_v1_BatchOperation'
                    maxItems: 20
                    minItems: 1
            description: ExecuteBatchRequest carries the array of operations to execute in bulk.
        worldmonitor_batch_v1_BatchOperation:
            type: object
            properties:
                id:
                    type: string
                    maxLength: 64
                    description: Client-chosen correlation id echoed back in the matching result. Defaults to the operation's zero-based index when omitted.
                path:
                    type: string
                    maxLength: 2048
                    description: Absolute path of any documented GET operation, optionally including a query string — e.g. "/api/market/v1/list-market-quotes" or "/api/intelligence/v1/get-country-risk?country=DE&jmespath=score". Nested batch paths (/api/batch/*) are rejected.
            required:
                - path
            description: BatchOperation describes one read operation to execute within a batch request.
        worldmonitor_batch_v1_ExecuteBatchResponse:
            type: object
            properties:
                results:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_batch_v1_BatchOperationResult'
                succeeded:
                    type: integer
                    format: int32
                    description: Number of operations that returned an HTTP 2xx status.
                failed:
                    type: integer
                    format: int32
                    description: Number of operations that returned a non-2xx status or failed to execute.
            description: ExecuteBatchResponse aggregates the per-operation results.
        worldmonitor_batch_v1_BatchOperationResult:
            type: object
            properties:
                id:
                    type: string
                    description: Correlation id from the request (or the operation's zero-based index when omitted).
                status:
                    type: integer
                    format: int32
                    description: HTTP status code returned by the operation, or 0 when the operation could not be executed at all (see error).
                body:
                    $ref: '#/components/schemas/worldmonitor_batch_v1_BatchOperationBody'
                error:
                    type: string
                    description: 'Machine-readable failure reason when no response body is available: invalid_path, nested_batch, timeout, fetch_failed, response_too_large, or invalid_json.'
            description: BatchOperationResult is the outcome of one operation in the batch.
        worldmonitor_batch_v1_BatchOperationBody:
            type: object
            description: BatchOperationBody is the JSON response body returned by one batched operation. It is a free-form object whose shape is defined by the target operation's own response schema (see that operation's entry in this spec).
        worldmonitor_climate_v1_ListClimateAnomaliesRequest:
            type: object
            properties:
                pageSize:
                    type: integer
                    format: int32
                    description: |-
                        Maximum items per page (1-100).
                         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.
                minSeverity:
                    type: string
                    enum:
                        - ANOMALY_SEVERITY_UNSPECIFIED
                        - ANOMALY_SEVERITY_NORMAL
                        - ANOMALY_SEVERITY_MODERATE
                        - ANOMALY_SEVERITY_EXTREME
                    description: |-
                        AnomalySeverity represents the severity of a climate anomaly.
                         Maps to existing TS union: 'normal' | 'moderate' | 'extreme'.
            description: ListClimateAnomaliesRequest specifies filters for retrieving climate anomaly data.
        worldmonitor_climate_v1_ListClimateAnomaliesResponse:
            type: object
            properties:
                anomalies:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_climate_v1_ClimateAnomaly'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListClimateAnomaliesResponse contains the list of climate anomalies.
        worldmonitor_climate_v1_ClimateAnomaly:
            type: object
            properties:
                zone:
                    type: string
                    minLength: 1
                    description: Climate zone name (e.g., "Northern Europe", "Sahel").
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                tempDelta:
                    type: number
                    format: double
                    description: Temperature deviation from normal in degrees Celsius.
                precipDelta:
                    type: number
                    format: double
                    description: Precipitation deviation from normal in millimeters.
                severity:
                    type: string
                    enum:
                        - ANOMALY_SEVERITY_UNSPECIFIED
                        - ANOMALY_SEVERITY_NORMAL
                        - ANOMALY_SEVERITY_MODERATE
                        - ANOMALY_SEVERITY_EXTREME
                    description: |-
                        AnomalySeverity represents the severity of a climate anomaly.
                         Maps to existing TS union: 'normal' | 'moderate' | 'extreme'.
                type:
                    type: string
                    enum:
                        - ANOMALY_TYPE_UNSPECIFIED
                        - ANOMALY_TYPE_WARM
                        - ANOMALY_TYPE_COLD
                        - ANOMALY_TYPE_WET
                        - ANOMALY_TYPE_DRY
                        - ANOMALY_TYPE_MIXED
                    description: |-
                        AnomalyType represents the type of climate anomaly.
                         Maps to existing TS union: 'warm' | 'cold' | 'wet' | 'dry' | 'mixed'.
                period:
                    type: string
                    minLength: 1
                    description: Time period covered (e.g., "2024-W03", "2024-01").
            required:
                - zone
                - period
            description: |-
                ClimateAnomaly represents a temperature or precipitation deviation from historical norms.
                 Sourced from Open-Meteo / ERA5 reanalysis data.
        worldmonitor_climate_v1_ListClimateDisastersRequest:
            type: object
            properties:
                pageSize:
                    type: integer
                    format: int32
                    description: Maximum items per page (1-100).
                cursor:
                    type: string
                    description: Cursor for next page.
            description: ListClimateDisastersRequest specifies filters for retrieving climate disasters.
        worldmonitor_climate_v1_ListClimateDisastersResponse:
            type: object
            properties:
                disasters:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_climate_v1_ClimateDisaster'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListClimateDisastersResponse contains climate disaster events.
        worldmonitor_climate_v1_ClimateDisaster:
            type: object
            properties:
                id:
                    type: string
                    description: Unique event identifier.
                type:
                    type: string
                    description: 'Disaster type: flood, cyclone, drought, heatwave, wildfire.'
                name:
                    type: string
                    description: Human-readable event name.
                country:
                    type: string
                    description: Country name.
                countryCode:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                lat:
                    type: number
                    format: double
                    description: Event latitude.
                lng:
                    type: number
                    format: double
                    description: Event longitude.
                severity:
                    type: string
                    description: 'Severity level. GDACS: green/orange/red. ReliefWeb: low/medium/high.'
                startedAt:
                    type: integer
                    format: int64
                    description: 'Event start time as Unix epoch milliseconds. Warning: Values > 2^53 may lose precision in JavaScript'
                status:
                    type: string
                    description: 'Event status: alert/ongoing/past.'
                affectedPopulation:
                    type: integer
                    format: int32
                    description: Affected population when available.
                source:
                    type: string
                    description: 'Source system: GDACS, ReliefWeb, NASA FIRMS.'
                sourceUrl:
                    type: string
                    description: Source URL for drill-down.
            description: ClimateDisaster represents a climate-relevant disaster event from seeded caches.
        worldmonitor_climate_v1_GetCo2MonitoringRequest:
            type: object
        worldmonitor_climate_v1_GetCo2MonitoringResponse:
            type: object
            properties:
                monitoring:
                    $ref: '#/components/schemas/worldmonitor_climate_v1_Co2Monitoring'
        worldmonitor_climate_v1_Co2Monitoring:
            type: object
            properties:
                currentPpm:
                    type: number
                    format: double
                yearAgoPpm:
                    type: number
                    format: double
                annualGrowthRate:
                    type: number
                    format: double
                preIndustrialBaseline:
                    type: number
                    format: double
                monthlyAverage:
                    type: number
                    format: double
                trend12m:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_climate_v1_Co2DataPoint'
                methanePpb:
                    type: number
                    format: double
                nitrousOxidePpb:
                    type: number
                    format: double
                measuredAt:
                    type: string
                    format: int64
                station:
                    type: string
        worldmonitor_climate_v1_Co2DataPoint:
            type: object
            properties:
                month:
                    type: string
                ppm:
                    type: number
                    format: double
                anomaly:
                    type: number
                    format: double
                    description: Year-over-year delta vs same calendar month, in ppm.
        worldmonitor_climate_v1_GetOceanIceDataRequest:
            type: object
        worldmonitor_climate_v1_GetOceanIceDataResponse:
            type: object
            properties:
                data:
                    $ref: '#/components/schemas/worldmonitor_climate_v1_OceanIceData'
        worldmonitor_climate_v1_OceanIceData:
            type: object
            properties:
                arcticExtentMkm2:
                    type: number
                    format: double
                arcticExtentAnomalyMkm2:
                    type: number
                    format: double
                arcticTrend:
                    type: string
                seaLevelMmAbove1993:
                    type: number
                    format: double
                seaLevelAnnualRiseMm:
                    type: number
                    format: double
                ohc0700mZj:
                    type: number
                    format: double
                sstAnomalyC:
                    type: number
                    format: double
                measuredAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                iceTrend12m:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_climate_v1_IceTrendPoint'
        worldmonitor_climate_v1_IceTrendPoint:
            type: object
            properties:
                month:
                    type: string
                extentMkm2:
                    type: number
                    format: double
                anomalyMkm2:
                    type: number
                    format: double
        worldmonitor_climate_v1_ListAirQualityDataRequest:
            type: object
        worldmonitor_climate_v1_ListAirQualityDataResponse:
            type: object
            properties:
                stations:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_climate_v1_AirQualityStation'
                fetchedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
        worldmonitor_climate_v1_AirQualityStation:
            type: object
            properties:
                city:
                    type: string
                countryCode:
                    type: string
                lat:
                    type: number
                    format: double
                lng:
                    type: number
                    format: double
                pm25:
                    type: number
                    format: double
                aqi:
                    type: integer
                    format: int32
                riskLevel:
                    type: string
                pollutant:
                    type: string
                measuredAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                source:
                    type: string
        worldmonitor_climate_v1_ListClimateNewsRequest:
            type: object
        worldmonitor_climate_v1_ListClimateNewsResponse:
            type: object
            properties:
                items:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_climate_v1_ClimateNewsItem'
                fetchedAt:
                    type: integer
                    format: int64
                    description: |-
                        Time the seed snapshot was fetched, as Unix epoch milliseconds. A value of
                         0 means the snapshot is unavailable/degraded, not that there are
                         confirmed zero climate headlines.. Warning: Values > 2^53 may lose precision in JavaScript
                dataAvailable:
                    type: boolean
                    description: |-
                        True when items came from a seed snapshot. False means an empty payload is
                         graceful degradation because the snapshot is unavailable.
        worldmonitor_climate_v1_ClimateNewsItem:
            type: object
            properties:
                id:
                    type: string
                    description: Unique identifier (URL hash + publish timestamp).
                title:
                    type: string
                    description: Article headline.
                url:
                    type: string
                    description: Canonical article URL.
                sourceName:
                    type: string
                    description: Source publication name.
                publishedAt:
                    type: integer
                    format: int64
                    description: 'Publication time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                summary:
                    type: string
                    description: Short summary/description (max 300 chars in seed pipeline).
            description: ClimateNewsItem represents a single climate/environment news article.
        worldmonitor_conflict_v1_ListAcledEventsRequest:
            type: object
            properties:
                start:
                    type: integer
                    format: int64
                    description: 'Start of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                end:
                    type: integer
                    format: int64
                    description: 'End of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                pageSize:
                    type: integer
                    format: int32
                    description: |-
                        Maximum items per page (1-100).
                         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.
                country:
                    type: string
                    description: Optional country filter (ISO 3166-1 alpha-2).
            description: ListAcledEventsRequest specifies filters for retrieving ACLED conflict events.
        worldmonitor_conflict_v1_ListAcledEventsResponse:
            type: object
            properties:
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_conflict_v1_AcledConflictEvent'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListAcledEventsResponse contains ACLED conflict events matching the request.
        worldmonitor_conflict_v1_AcledConflictEvent:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Unique ACLED event identifier.
                eventType:
                    type: string
                    description: ACLED event type classification (e.g., "Battles", "Explosions/Remote violence").
                country:
                    type: string
                    description: Country where the event occurred.
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                occurredAt:
                    type: integer
                    format: int64
                    description: 'Time the event occurred, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                fatalities:
                    type: integer
                    format: int32
                    description: Reported fatalities from this event.
                actors:
                    type: array
                    items:
                        type: string
                        description: Named actors involved in the event.
                source:
                    type: string
                    description: Source article or report.
                admin1:
                    type: string
                    description: Administrative region within the country.
            required:
                - id
            description: AcledConflictEvent represents an armed conflict event from the ACLED dataset.
        worldmonitor_conflict_v1_ListUcdpEventsRequest:
            type: object
            properties:
                start:
                    type: integer
                    format: int64
                    description: |-
                        Start of time range (inclusive), Unix epoch milliseconds.
                         Accepted but currently ignored; no-op until this handler supports the parameter.. Warning: Values > 2^53 may lose precision in JavaScript
                end:
                    type: integer
                    format: int64
                    description: |-
                        End of time range (inclusive), Unix epoch milliseconds.
                         Accepted but currently ignored; no-op until this handler supports the parameter.. Warning: Values > 2^53 may lose precision in JavaScript
                pageSize:
                    type: integer
                    format: int32
                    description: |-
                        Maximum items per page (1-100).
                         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.
                country:
                    type: string
                    description: Optional country filter (ISO 3166-1 alpha-2).
            description: ListUcdpEventsRequest specifies filters for retrieving UCDP violence events.
        worldmonitor_conflict_v1_ListUcdpEventsResponse:
            type: object
            properties:
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_conflict_v1_UcdpViolenceEvent'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListUcdpEventsResponse contains UCDP violence events matching the request.
        worldmonitor_conflict_v1_UcdpViolenceEvent:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Unique UCDP event identifier.
                dateStart:
                    type: integer
                    format: int64
                    description: 'Start date of the event, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                dateEnd:
                    type: integer
                    format: int64
                    description: 'End date of the event, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                country:
                    type: string
                    description: Country where the event occurred.
                sideA:
                    type: string
                    description: Primary party in the conflict (Side A).
                sideB:
                    type: string
                    description: Secondary party in the conflict (Side B).
                deathsBest:
                    type: integer
                    format: int32
                    description: Best estimate of deaths.
                deathsLow:
                    type: integer
                    format: int32
                    description: Low estimate of deaths.
                deathsHigh:
                    type: integer
                    format: int32
                    description: High estimate of deaths.
                violenceType:
                    type: string
                    enum:
                        - UCDP_VIOLENCE_TYPE_UNSPECIFIED
                        - UCDP_VIOLENCE_TYPE_STATE_BASED
                        - UCDP_VIOLENCE_TYPE_NON_STATE
                        - UCDP_VIOLENCE_TYPE_ONE_SIDED
                    description: |-
                        UcdpViolenceType represents the UCDP violence classification.
                         Maps to existing TS union: 'state-based' | 'non-state' | 'one-sided'.
                sourceOriginal:
                    type: string
                    description: Original source of the event report.
            required:
                - id
            description: UcdpViolenceEvent represents a georeferenced violence event from the UCDP dataset.
        worldmonitor_conflict_v1_GetHumanitarianSummaryRequest:
            type: object
            properties:
                countryCode:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 country code (e.g., "YE", "SD", "SO").
            required:
                - countryCode
            description: GetHumanitarianSummaryRequest specifies which country to retrieve the humanitarian summary for.
        worldmonitor_conflict_v1_GetHumanitarianSummaryResponse:
            type: object
            properties:
                summary:
                    $ref: '#/components/schemas/worldmonitor_conflict_v1_HumanitarianCountrySummary'
            description: GetHumanitarianSummaryResponse contains the humanitarian summary for the requested country.
        worldmonitor_conflict_v1_HumanitarianCountrySummary:
            type: object
            properties:
                countryCode:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                countryName:
                    type: string
                    description: Country name.
                conflictEventsTotal:
                    type: integer
                    format: int32
                    description: Total conflict events in the reference period.
                conflictPoliticalViolenceEvents:
                    type: integer
                    format: int32
                    description: Political violence + civilian targeting event count.
                conflictFatalities:
                    type: integer
                    format: int32
                    description: Total fatalities from political violence and civilian targeting.
                referencePeriod:
                    type: string
                    description: Reference period start date (YYYY-MM-DD).
                conflictDemonstrations:
                    type: integer
                    format: int32
                    description: Number of demonstration events.
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Last data update time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: HumanitarianCountrySummary represents HAPI conflict event counts for a country.
        worldmonitor_conflict_v1_ListIranEventsRequest:
            type: object
        worldmonitor_conflict_v1_ListIranEventsResponse:
            type: object
            properties:
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_conflict_v1_IranEvent'
                scrapedAt:
                    type: string
                    format: int64
        worldmonitor_conflict_v1_IranEvent:
            type: object
            properties:
                id:
                    type: string
                title:
                    type: string
                category:
                    type: string
                sourceUrl:
                    type: string
                latitude:
                    type: number
                    format: double
                longitude:
                    type: number
                    format: double
                locationName:
                    type: string
                timestamp:
                    type: string
                    format: int64
                severity:
                    type: string
        worldmonitor_conflict_v1_GetHumanitarianSummaryBatchRequest:
            type: object
            properties:
                countryCodes:
                    type: array
                    items:
                        type: string
                        maxItems: 25
                        minItems: 1
                        description: ISO 3166-1 alpha-2 country codes (e.g., "YE", "SD"). Max 25.
                    maxItems: 25
                    minItems: 1
            description: GetHumanitarianSummaryBatchRequest looks up humanitarian summaries for multiple countries.
        worldmonitor_conflict_v1_GetHumanitarianSummaryBatchResponse:
            type: object
            properties:
                results:
                    type: object
                    additionalProperties:
                        $ref: '#/components/schemas/worldmonitor_conflict_v1_HumanitarianCountrySummary'
                    description: Map of country_code -> humanitarian summary for found countries.
                fetched:
                    type: integer
                    format: int32
                    description: Number of countries successfully fetched.
                requested:
                    type: integer
                    format: int32
                    description: Number of countries requested.
            description: GetHumanitarianSummaryBatchResponse contains humanitarian summaries for the requested countries.
        worldmonitor_conflict_v1_GetHumanitarianSummaryBatchResponse_ResultsEntry:
            type: object
            properties:
                key:
                    type: string
                value:
                    $ref: '#/components/schemas/worldmonitor_conflict_v1_HumanitarianCountrySummary'
        worldmonitor_consumer_prices_v1_GetConsumerPriceOverviewRequest:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code is the ISO 3166-1 alpha-2 market identifier (e.g. "ae").
                basketSlug:
                    type: string
                    description: basket_slug selects which basket to use (e.g. "essentials-ae").
            description: GetConsumerPriceOverviewRequest parameters for the overview RPC.
        worldmonitor_consumer_prices_v1_GetConsumerPriceOverviewResponse:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code echoes the requested market.
                asOf:
                    type: string
                    format: int64
                    description: as_of is the Unix millisecond timestamp of the snapshot.
                currencyCode:
                    type: string
                    description: currency_code is the ISO 4217 currency for price values.
                essentialsIndex:
                    type: number
                    format: double
                    description: essentials_index is the fixed basket index value (base = 100).
                valueBasketIndex:
                    type: number
                    format: double
                    description: value_basket_index is the value basket index value (base = 100).
                wowPct:
                    type: number
                    format: double
                    description: wow_pct is the week-over-week percentage change in the essentials index.
                momPct:
                    type: number
                    format: double
                    description: mom_pct is the month-over-month percentage change in the essentials index.
                retailerSpreadPct:
                    type: number
                    format: double
                    description: retailer_spread_pct is the basket cost spread between cheapest and most expensive retailer.
                coveragePct:
                    type: number
                    format: double
                    description: coverage_pct is the fraction of basket items with current observations.
                freshnessLagMin:
                    type: integer
                    format: int32
                    description: freshness_lag_min is the average minutes since last observation across all retailers.
                topCategories:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_CategorySnapshot'
                upstreamUnavailable:
                    type: boolean
                    description: upstream_unavailable is true when the companion service could not be reached.
            description: GetConsumerPriceOverviewResponse contains headline basket and coverage metrics.
        worldmonitor_consumer_prices_v1_CategorySnapshot:
            type: object
            properties:
                slug:
                    type: string
                    description: slug is the machine-readable category identifier (e.g. "eggs", "rice").
                name:
                    type: string
                    description: name is the human-readable category label.
                wowPct:
                    type: number
                    format: double
                    description: wow_pct is the week-over-week percentage change.
                momPct:
                    type: number
                    format: double
                    description: mom_pct is the month-over-month percentage change.
                currentIndex:
                    type: number
                    format: double
                    description: current_index is the current price index value (base = 100).
                sparkline:
                    type: array
                    items:
                        type: number
                        format: double
                        description: sparkline is an ordered sequence of index values for the selected range.
                coveragePct:
                    type: number
                    format: double
                    description: coverage_pct is the percentage of basket items observed for this category.
                itemCount:
                    type: integer
                    format: int32
                    description: item_count is the number of observed products in this category.
            description: CategorySnapshot holds price index data for a single product category.
        worldmonitor_consumer_prices_v1_GetConsumerPriceBasketSeriesRequest:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code is the ISO 3166-1 alpha-2 market identifier.
                basketSlug:
                    type: string
                    description: basket_slug selects the basket (e.g. "essentials-ae").
                range:
                    type: string
                    description: range is one of "7d", "30d", "90d", "180d".
            description: GetConsumerPriceBasketSeriesRequest parameters for time series data.
        worldmonitor_consumer_prices_v1_GetConsumerPriceBasketSeriesResponse:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code echoes the requested market.
                basketSlug:
                    type: string
                    description: basket_slug echoes the requested basket.
                asOf:
                    type: string
                    format: int64
                    description: as_of is the Unix millisecond timestamp of the snapshot.
                currencyCode:
                    type: string
                    description: currency_code is the ISO 4217 currency code.
                range:
                    type: string
                    description: range echoes the requested range.
                essentialsSeries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_BasketPoint'
                valueSeries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_BasketPoint'
                upstreamUnavailable:
                    type: boolean
                    description: upstream_unavailable is true when the companion service could not be reached.
            description: GetConsumerPriceBasketSeriesResponse contains the basket index time series.
        worldmonitor_consumer_prices_v1_BasketPoint:
            type: object
            properties:
                date:
                    type: string
                    description: date is the ISO 8601 date string (YYYY-MM-DD).
                index:
                    type: number
                    format: double
                    description: index is the basket index value (base = 100).
            description: BasketPoint is a single data point in a basket index time series.
        worldmonitor_consumer_prices_v1_ListConsumerPriceCategoriesRequest:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code is the ISO 3166-1 alpha-2 market identifier.
                basketSlug:
                    type: string
                    description: basket_slug selects the basket scope.
                range:
                    type: string
                    description: range is one of "7d", "30d", "90d", "180d".
            description: ListConsumerPriceCategoriesRequest parameters for category listing.
        worldmonitor_consumer_prices_v1_ListConsumerPriceCategoriesResponse:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code echoes the requested market.
                asOf:
                    type: string
                    format: int64
                    description: as_of is the Unix millisecond timestamp of the snapshot.
                range:
                    type: string
                    description: range echoes the requested range.
                categories:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_CategorySnapshot'
                upstreamUnavailable:
                    type: boolean
                    description: upstream_unavailable is true when the companion service could not be reached.
            description: ListConsumerPriceCategoriesResponse holds category-level price snapshots.
        worldmonitor_consumer_prices_v1_ListConsumerPriceMoversRequest:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code is the ISO 3166-1 alpha-2 market identifier.
                range:
                    type: string
                    description: range is one of "7d", "30d", "90d".
                limit:
                    type: integer
                    format: int32
                    description: limit caps the number of risers and fallers returned.
                categorySlug:
                    type: string
                    description: category_slug filters to a single category when set.
            required:
                - limit
            description: ListConsumerPriceMoversRequest parameters for the movers RPC.
        worldmonitor_consumer_prices_v1_ListConsumerPriceMoversResponse:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code echoes the requested market.
                asOf:
                    type: string
                    format: int64
                    description: as_of is the Unix millisecond timestamp of the snapshot.
                range:
                    type: string
                    description: range echoes the requested range.
                risers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_PriceMover'
                fallers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_PriceMover'
                upstreamUnavailable:
                    type: boolean
                    description: upstream_unavailable is true when the companion service could not be reached.
            description: ListConsumerPriceMoversResponse holds the top price movers.
        worldmonitor_consumer_prices_v1_PriceMover:
            type: object
            properties:
                productId:
                    type: string
                    description: product_id is the retailer product identifier.
                title:
                    type: string
                    description: title is the normalized product title.
                category:
                    type: string
                    description: category is the product category slug.
                retailerSlug:
                    type: string
                    description: retailer_slug identifies the retailer where this move was observed.
                changePct:
                    type: number
                    format: double
                    description: change_pct is the signed percentage change over the selected window.
                currentPrice:
                    type: number
                    format: double
                    description: current_price is the latest observed price.
                currencyCode:
                    type: string
                    description: currency_code is the ISO 4217 currency code.
            description: PriceMover describes a product with a notable upward or downward price move.
        worldmonitor_consumer_prices_v1_ListRetailerPriceSpreadsRequest:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code is the ISO 3166-1 alpha-2 market identifier.
                basketSlug:
                    type: string
                    description: basket_slug selects which basket to compare across retailers.
            description: ListRetailerPriceSpreadsRequest parameters for the retailer spread RPC.
        worldmonitor_consumer_prices_v1_ListRetailerPriceSpreadsResponse:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code echoes the requested market.
                asOf:
                    type: string
                    format: int64
                    description: as_of is the Unix millisecond timestamp of the snapshot.
                basketSlug:
                    type: string
                    description: basket_slug echoes the requested basket.
                currencyCode:
                    type: string
                    description: currency_code is the ISO 4217 currency code.
                retailers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_RetailerSpread'
                spreadPct:
                    type: number
                    format: double
                    description: spread_pct is the percentage difference between cheapest and most expensive retailer.
                upstreamUnavailable:
                    type: boolean
                    description: upstream_unavailable is true when the companion service could not be reached.
            description: ListRetailerPriceSpreadsResponse holds cheapest-basket rankings.
        worldmonitor_consumer_prices_v1_RetailerSpread:
            type: object
            properties:
                slug:
                    type: string
                    description: slug is the retailer identifier.
                name:
                    type: string
                    description: name is the retailer display name.
                basketTotal:
                    type: number
                    format: double
                    description: basket_total is the sum of matched basket item prices at this retailer.
                deltaVsCheapest:
                    type: number
                    format: double
                    description: delta_vs_cheapest is the absolute price difference vs the cheapest retailer.
                deltaVsCheapestPct:
                    type: number
                    format: double
                    description: delta_vs_cheapest_pct is the percentage difference vs the cheapest retailer.
                itemCount:
                    type: integer
                    format: int32
                    description: item_count is the number of matched basket items observed.
                freshnessMin:
                    type: integer
                    format: int32
                    description: freshness_min is minutes since the last successful scrape for this retailer.
                currencyCode:
                    type: string
                    description: currency_code is the ISO 4217 currency code.
            description: RetailerSpread holds the basket cost breakdown for one retailer.
        worldmonitor_consumer_prices_v1_GetConsumerPriceFreshnessRequest:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code is the ISO 3166-1 alpha-2 market identifier.
            description: GetConsumerPriceFreshnessRequest parameters for the freshness RPC.
        worldmonitor_consumer_prices_v1_GetConsumerPriceFreshnessResponse:
            type: object
            properties:
                marketCode:
                    type: string
                    description: market_code echoes the requested market.
                asOf:
                    type: string
                    format: int64
                    description: as_of is the Unix millisecond timestamp of the snapshot.
                retailers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_consumer_prices_v1_RetailerFreshnessInfo'
                overallFreshnessMin:
                    type: integer
                    format: int32
                    description: overall_freshness_min is the average freshness lag across all retailers.
                stalledCount:
                    type: integer
                    format: int32
                    description: stalled_count is the number of retailers with no recent successful scrape.
                upstreamUnavailable:
                    type: boolean
                    description: upstream_unavailable is true when the companion service could not be reached.
            description: GetConsumerPriceFreshnessResponse describes feed health for all retailers.
        worldmonitor_consumer_prices_v1_RetailerFreshnessInfo:
            type: object
            properties:
                slug:
                    type: string
                    description: slug is the retailer identifier.
                name:
                    type: string
                    description: name is the retailer display name.
                lastRunAt:
                    type: string
                    format: int64
                    description: last_run_at is the Unix millisecond timestamp of the last successful scrape.
                status:
                    type: string
                    description: status is one of "ok", "stale", "failed", "unknown".
                parseSuccessRate:
                    type: number
                    format: double
                    description: parse_success_rate is the fraction of pages parsed successfully (0–1).
                freshnessMin:
                    type: integer
                    format: int32
                    description: freshness_min is minutes since last successful observation.
            description: RetailerFreshnessInfo describes the operational health of one retailer feed.
        worldmonitor_cyber_v1_ListCyberThreatsRequest:
            type: object
            properties:
                start:
                    type: integer
                    format: int64
                    description: |-
                        Start of time range (inclusive), Unix epoch milliseconds.
                         Accepted but currently ignored; no-op until this handler supports the parameter.. Warning: Values > 2^53 may lose precision in JavaScript
                end:
                    type: integer
                    format: int64
                    description: |-
                        End of time range (inclusive), Unix epoch milliseconds.
                         Accepted but currently ignored; no-op until this handler supports the parameter.. Warning: Values > 2^53 may lose precision in JavaScript
                pageSize:
                    type: integer
                    format: int32
                    description: Maximum items per page (1-100).
                cursor:
                    type: string
                    description: Cursor for next page.
                type:
                    type: string
                    enum:
                        - CYBER_THREAT_TYPE_UNSPECIFIED
                        - CYBER_THREAT_TYPE_C2_SERVER
                        - CYBER_THREAT_TYPE_MALWARE_HOST
                        - CYBER_THREAT_TYPE_PHISHING
                        - CYBER_THREAT_TYPE_MALICIOUS_URL
                    description: |-
                        CyberThreatType represents the classification of a cyber threat.
                         Maps to TS union: 'c2_server' | 'malware_host' | 'phishing' | 'malicious_url'.
                source:
                    type: string
                    enum:
                        - CYBER_THREAT_SOURCE_UNSPECIFIED
                        - CYBER_THREAT_SOURCE_FEODO
                        - CYBER_THREAT_SOURCE_URLHAUS
                        - CYBER_THREAT_SOURCE_C2INTEL
                        - CYBER_THREAT_SOURCE_OTX
                        - CYBER_THREAT_SOURCE_ABUSEIPDB
                    description: |-
                        CyberThreatSource represents the intelligence source of a cyber threat.
                         Maps to TS union: 'feodo' | 'urlhaus' | 'c2intel' | 'otx' | 'abuseipdb'.
                minSeverity:
                    type: string
                    enum:
                        - CRITICALITY_LEVEL_UNSPECIFIED
                        - CRITICALITY_LEVEL_LOW
                        - CRITICALITY_LEVEL_MEDIUM
                        - CRITICALITY_LEVEL_HIGH
                        - CRITICALITY_LEVEL_CRITICAL
                    description: |-
                        CriticalityLevel represents a four-tier criticality classification for cyber and risk domains.
                         Maps to existing TS union: 'low' | 'medium' | 'high' | 'critical'.
            description: ListCyberThreatsRequest specifies filters for retrieving cyber threat indicators.
        worldmonitor_cyber_v1_ListCyberThreatsResponse:
            type: object
            properties:
                threats:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_cyber_v1_CyberThreat'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListCyberThreatsResponse contains cyber threats matching the request.
        worldmonitor_cyber_v1_CyberThreat:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Unique threat identifier.
                type:
                    type: string
                    enum:
                        - CYBER_THREAT_TYPE_UNSPECIFIED
                        - CYBER_THREAT_TYPE_C2_SERVER
                        - CYBER_THREAT_TYPE_MALWARE_HOST
                        - CYBER_THREAT_TYPE_PHISHING
                        - CYBER_THREAT_TYPE_MALICIOUS_URL
                    description: |-
                        CyberThreatType represents the classification of a cyber threat.
                         Maps to TS union: 'c2_server' | 'malware_host' | 'phishing' | 'malicious_url'.
                source:
                    type: string
                    enum:
                        - CYBER_THREAT_SOURCE_UNSPECIFIED
                        - CYBER_THREAT_SOURCE_FEODO
                        - CYBER_THREAT_SOURCE_URLHAUS
                        - CYBER_THREAT_SOURCE_C2INTEL
                        - CYBER_THREAT_SOURCE_OTX
                        - CYBER_THREAT_SOURCE_ABUSEIPDB
                    description: |-
                        CyberThreatSource represents the intelligence source of a cyber threat.
                         Maps to TS union: 'feodo' | 'urlhaus' | 'c2intel' | 'otx' | 'abuseipdb'.
                indicator:
                    type: string
                    description: Threat indicator value (IP, domain, or URL).
                indicatorType:
                    type: string
                    enum:
                        - CYBER_THREAT_INDICATOR_TYPE_UNSPECIFIED
                        - CYBER_THREAT_INDICATOR_TYPE_IP
                        - CYBER_THREAT_INDICATOR_TYPE_DOMAIN
                        - CYBER_THREAT_INDICATOR_TYPE_URL
                    description: |-
                        CyberThreatIndicatorType represents the type of threat indicator.
                         Maps to TS union: 'ip' | 'domain' | 'url'.
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                country:
                    type: string
                    description: Country of origin (ISO 3166-1 alpha-2).
                severity:
                    type: string
                    enum:
                        - CRITICALITY_LEVEL_UNSPECIFIED
                        - CRITICALITY_LEVEL_LOW
                        - CRITICALITY_LEVEL_MEDIUM
                        - CRITICALITY_LEVEL_HIGH
                        - CRITICALITY_LEVEL_CRITICAL
                    description: |-
                        CriticalityLevel represents a four-tier criticality classification for cyber and risk domains.
                         Maps to existing TS union: 'low' | 'medium' | 'high' | 'critical'.
                malwareFamily:
                    type: string
                    description: Associated malware family, if known.
                tags:
                    type: array
                    items:
                        type: string
                        description: Descriptive tags.
                firstSeenAt:
                    type: integer
                    format: int64
                    description: 'First seen time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                lastSeenAt:
                    type: integer
                    format: int64
                    description: 'Last seen time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            required:
                - id
            description: |-
                CyberThreat represents a cyber threat indicator aggregated from multiple sources.
                 Sources include Feodo Tracker, URLhaus, OTX, AbuseIPDB, and C2Intel.
        worldmonitor_displacement_v1_GetDisplacementSummaryRequest:
            type: object
            properties:
                year:
                    type: integer
                    minimum: 0
                    format: int32
                    description: Data year to retrieve (e.g., 2023). Uses latest available if zero.
                countryLimit:
                    type: integer
                    minimum: 0
                    format: int32
                    description: Maximum number of country entries to return.
                flowLimit:
                    type: integer
                    minimum: 0
                    format: int32
                    description: Maximum number of displacement flows to return.
            description: GetDisplacementSummaryRequest specifies parameters for retrieving displacement data.
        worldmonitor_displacement_v1_GetDisplacementSummaryResponse:
            type: object
            properties:
                summary:
                    $ref: '#/components/schemas/worldmonitor_displacement_v1_DisplacementSummary'
                fetchedAt:
                    type: integer
                    format: int64
                    description: |-
                        Time the seed or live fallback snapshot was fetched, as Unix epoch
                         milliseconds. A value of 0 means the snapshot is unavailable/degraded, not
                         that global displacement is zero.. Warning: Values > 2^53 may lose precision in JavaScript
                dataAvailable:
                    type: boolean
                    description: |-
                        True when summary came from a seed snapshot or live fallback. False means
                         an absent/empty summary is graceful degradation because the snapshot is
                         unavailable.
            description: GetDisplacementSummaryResponse contains the global displacement summary.
        worldmonitor_displacement_v1_DisplacementSummary:
            type: object
            properties:
                year:
                    type: integer
                    format: int32
                    description: Data year.
                globalTotals:
                    $ref: '#/components/schemas/worldmonitor_displacement_v1_GlobalDisplacementTotals'
                countries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_displacement_v1_CountryDisplacement'
                topFlows:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_displacement_v1_DisplacementFlow'
            description: DisplacementSummary represents a global overview of displacement data from UNHCR.
        worldmonitor_displacement_v1_GlobalDisplacementTotals:
            type: object
            properties:
                refugees:
                    type: integer
                    minimum: 0
                    format: int64
                    description: 'Total recognized refugees worldwide.. Warning: Values > 2^53 may lose precision in JavaScript'
                asylumSeekers:
                    type: integer
                    minimum: 0
                    format: int64
                    description: 'Total asylum seekers worldwide.. Warning: Values > 2^53 may lose precision in JavaScript'
                idps:
                    type: integer
                    minimum: 0
                    format: int64
                    description: 'Total internally displaced persons worldwide.. Warning: Values > 2^53 may lose precision in JavaScript'
                stateless:
                    type: integer
                    minimum: 0
                    format: int64
                    description: 'Total stateless persons worldwide.. Warning: Values > 2^53 may lose precision in JavaScript'
                total:
                    type: integer
                    minimum: 0
                    format: int64
                    description: 'Grand total of displaced persons.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: GlobalDisplacementTotals represents worldwide displacement figures.
        worldmonitor_displacement_v1_CountryDisplacement:
            type: object
            properties:
                code:
                    type: string
                    minLength: 1
                    description: ISO 3166-1 alpha-2 country code.
                name:
                    type: string
                    description: Country name.
                refugees:
                    type: integer
                    format: int64
                    description: 'Refugees originating from this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                asylumSeekers:
                    type: integer
                    format: int64
                    description: 'Asylum seekers from this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                idps:
                    type: integer
                    format: int64
                    description: 'Internally displaced persons within this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                stateless:
                    type: integer
                    format: int64
                    description: 'Stateless persons associated with this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                totalDisplaced:
                    type: integer
                    format: int64
                    description: 'Total displaced from this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                hostRefugees:
                    type: integer
                    format: int64
                    description: 'Refugees hosted by this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                hostAsylumSeekers:
                    type: integer
                    format: int64
                    description: 'Asylum seekers hosted by this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                hostTotal:
                    type: integer
                    format: int64
                    description: 'Total persons hosted by this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
            required:
                - code
            description: CountryDisplacement represents displacement metrics for a single country.
        worldmonitor_displacement_v1_DisplacementFlow:
            type: object
            properties:
                originCode:
                    type: string
                    minLength: 1
                    description: ISO 3166-1 alpha-2 code of the origin country.
                originName:
                    type: string
                    description: Origin country name.
                asylumCode:
                    type: string
                    minLength: 1
                    description: ISO 3166-1 alpha-2 code of the asylum country.
                asylumName:
                    type: string
                    description: Asylum country name.
                refugees:
                    type: integer
                    format: int64
                    description: 'Number of refugees in this flow.. Warning: Values > 2^53 may lose precision in JavaScript'
                originLocation:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                asylumLocation:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
            required:
                - originCode
                - asylumCode
            description: DisplacementFlow represents a refugee movement corridor between two countries.
        worldmonitor_displacement_v1_GetPopulationExposureRequest:
            type: object
            properties:
                mode:
                    type: string
                    description: 'Mode: "countries" (default) or "exposure".'
                lat:
                    type: number
                    maximum: 90
                    minimum: -90
                    format: double
                    description: Latitude (required for exposure mode).
                lon:
                    type: number
                    maximum: 180
                    minimum: -180
                    format: double
                    description: Longitude (required for exposure mode).
                radius:
                    type: number
                    minimum: 0
                    format: double
                    description: Radius in km (required for exposure mode, defaults to 50).
            description: |-
                GetPopulationExposureRequest supports two modes:
                 - countries mode (default): returns the priority countries list
                 - exposure mode: estimates population within a radius of a point
        worldmonitor_displacement_v1_GetPopulationExposureResponse:
            type: object
            properties:
                success:
                    type: boolean
                    description: True if the request succeeded.
                countries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_displacement_v1_CountryPopulationEntry'
                exposure:
                    $ref: '#/components/schemas/worldmonitor_displacement_v1_ExposureResult'
            description: GetPopulationExposureResponse returns either a countries list or an exposure estimate.
        worldmonitor_displacement_v1_CountryPopulationEntry:
            type: object
            properties:
                code:
                    type: string
                    description: ISO 3166-1 alpha-3 country code.
                name:
                    type: string
                    description: Country name.
                population:
                    type: integer
                    format: int64
                    description: 'Total population.. Warning: Values > 2^53 may lose precision in JavaScript'
                densityPerKm2:
                    type: integer
                    format: int32
                    description: Population density per square kilometer.
            description: CountryPopulationEntry represents a country with population data.
        worldmonitor_displacement_v1_ExposureResult:
            type: object
            properties:
                exposedPopulation:
                    type: integer
                    format: int64
                    description: 'Estimated exposed population.. Warning: Values > 2^53 may lose precision in JavaScript'
                exposureRadiusKm:
                    type: number
                    format: double
                    description: Radius used for the estimate in km.
                nearestCountry:
                    type: string
                    description: ISO3 code of nearest priority country.
                densityPerKm2:
                    type: integer
                    format: int32
                    description: Population density used for the estimate.
            description: ExposureResult contains the population exposure estimate.
        worldmonitor_economic_v1_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.
        worldmonitor_economic_v1_GetFredSeriesResponse:
            type: object
            properties:
                series:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_FredSeries'
            description: GetFredSeriesResponse contains the requested FRED series data.
        worldmonitor_economic_v1_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/worldmonitor_economic_v1_FredObservation'
            required:
                - seriesId
            description: FredSeries represents a FRED time series with metadata.
        worldmonitor_economic_v1_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.
        worldmonitor_economic_v1_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.
        worldmonitor_economic_v1_ListWorldBankIndicatorsResponse:
            type: object
            properties:
                data:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_WorldBankCountryData'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListWorldBankIndicatorsResponse contains World Bank indicator data.
        worldmonitor_economic_v1_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.
        worldmonitor_economic_v1_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.
        worldmonitor_economic_v1_GetEnergyPricesResponse:
            type: object
            properties:
                prices:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_EnergyPrice'
            description: GetEnergyPricesResponse contains energy price data.
        worldmonitor_economic_v1_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: Current price in USD.
                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: 'Price date, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            required:
                - commodity
            description: EnergyPrice represents a current energy commodity price from EIA.
        worldmonitor_economic_v1_GetMacroSignalsRequest:
            type: object
            description: GetMacroSignalsRequest requests the current macro signal dashboard.
        worldmonitor_economic_v1_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/worldmonitor_economic_v1_MacroSignals'
                meta:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_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.
        worldmonitor_economic_v1_MacroSignals:
            type: object
            properties:
                liquidity:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_LiquiditySignal'
                flowStructure:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_FlowStructureSignal'
                macroRegime:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_MacroRegimeSignal'
                technicalTrend:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_TechnicalTrendSignal'
                hashRate:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_HashRateSignal'
                priceMomentum:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_PriceMomentumSignal'
                fearGreed:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_FearGreedSignal'
            description: MacroSignals contains all 7 individual signal computations.
        worldmonitor_economic_v1_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.
        worldmonitor_economic_v1_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.
        worldmonitor_economic_v1_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.
        worldmonitor_economic_v1_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.
        worldmonitor_economic_v1_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.
        worldmonitor_economic_v1_PriceMomentumSignal:
            type: object
            properties:
                status:
                    type: string
                    description: '"STRONG", "MODERATE", "WEAK", or "UNKNOWN".'
            description: PriceMomentumSignal uses the Mayer Multiple (price/SMA200) as a market-adaptive signal.
        worldmonitor_economic_v1_FearGreedSignal:
            type: object
            properties:
                status:
                    type: string
                    description: Classification label (e.g., "Extreme Fear", "Greed").
                value:
                    type: integer
                    format: int32
                    description: Current index value (0-100).
                history:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_FearGreedHistoryEntry'
            description: FearGreedSignal tracks the Crypto Fear & Greed index.
        worldmonitor_economic_v1_FearGreedHistoryEntry:
            type: object
            properties:
                value:
                    type: integer
                    maximum: 100
                    minimum: 0
                    format: int32
                    description: Index value (0-100).
                date:
                    type: string
                    description: Date string (YYYY-MM-DD).
            description: FearGreedHistoryEntry is a single day's Fear & Greed index reading.
        worldmonitor_economic_v1_MacroMeta:
            type: object
            properties:
                qqqSparkline:
                    type: array
                    items:
                        type: number
                        format: double
                        description: Last 30 QQQ close prices for sparkline.
            description: MacroMeta contains supplementary chart data.
        worldmonitor_economic_v1_GetEnergyCapacityRequest:
            type: object
            properties:
                energySources:
                    type: array
                    items:
                        type: string
                        description: |-
                            Energy source codes to query (e.g., "SUN", "WND", "COL").
                             Empty returns all tracked sources (SUN, WND, COL).
                years:
                    type: integer
                    format: int32
                    description: |-
                        Number of years of historical data. Default 20 if not set.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
        worldmonitor_economic_v1_GetEnergyCapacityResponse:
            type: object
            properties:
                series:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_EnergyCapacitySeries'
        worldmonitor_economic_v1_EnergyCapacitySeries:
            type: object
            properties:
                energySource:
                    type: string
                name:
                    type: string
                data:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_EnergyCapacityYear'
        worldmonitor_economic_v1_EnergyCapacityYear:
            type: object
            properties:
                year:
                    type: integer
                    format: int32
                capacityMw:
                    type: number
                    format: double
        worldmonitor_economic_v1_GetBisPolicyRatesRequest:
            type: object
            description: GetBisPolicyRatesRequest requests central bank policy rates.
        worldmonitor_economic_v1_GetBisPolicyRatesResponse:
            type: object
            properties:
                rates:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_BisPolicyRate'
            description: GetBisPolicyRatesResponse contains BIS policy rate data.
        worldmonitor_economic_v1_BisPolicyRate:
            type: object
            properties:
                countryCode:
                    type: string
                    description: ISO 2-letter country code (US, GB, JP, etc.)
                countryName:
                    type: string
                    description: Country or region name.
                rate:
                    type: number
                    format: double
                    description: Current policy rate percentage.
                previousRate:
                    type: number
                    format: double
                    description: Previous period rate percentage.
                date:
                    type: string
                    description: Date as YYYY-MM.
                centralBank:
                    type: string
                    description: Central bank name (e.g. "Federal Reserve").
            description: BisPolicyRate represents a central bank policy rate from BIS.
        worldmonitor_economic_v1_GetBisExchangeRatesRequest:
            type: object
            description: GetBisExchangeRatesRequest requests effective exchange rates.
        worldmonitor_economic_v1_GetBisExchangeRatesResponse:
            type: object
            properties:
                rates:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_BisExchangeRate'
            description: GetBisExchangeRatesResponse contains BIS effective exchange rate data.
        worldmonitor_economic_v1_BisExchangeRate:
            type: object
            properties:
                countryCode:
                    type: string
                    description: ISO 2-letter country code.
                countryName:
                    type: string
                    description: Country or region name.
                realEer:
                    type: number
                    format: double
                    description: Real effective exchange rate index.
                nominalEer:
                    type: number
                    format: double
                    description: Nominal effective exchange rate index.
                realChange:
                    type: number
                    format: double
                    description: Percentage change from previous period (real).
                date:
                    type: string
                    description: Date as YYYY-MM.
            description: BisExchangeRate represents effective exchange rate indices from BIS.
        worldmonitor_economic_v1_GetBisCreditRequest:
            type: object
            description: GetBisCreditRequest requests credit-to-GDP ratio data.
        worldmonitor_economic_v1_GetBisCreditResponse:
            type: object
            properties:
                entries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_BisCreditToGdp'
            description: GetBisCreditResponse contains BIS credit-to-GDP data.
        worldmonitor_economic_v1_BisCreditToGdp:
            type: object
            properties:
                countryCode:
                    type: string
                    description: ISO 2-letter country code.
                countryName:
                    type: string
                    description: Country or region name.
                creditGdpRatio:
                    type: number
                    format: double
                    description: Total credit as percentage of GDP.
                previousRatio:
                    type: number
                    format: double
                    description: Previous quarter ratio.
                date:
                    type: string
                    description: Date as YYYY-QN.
            description: BisCreditToGdp represents total credit as percentage of GDP from BIS.
        worldmonitor_economic_v1_GetFredSeriesBatchRequest:
            type: object
            properties:
                seriesIds:
                    type: array
                    items:
                        type: string
                        maxItems: 10
                        minItems: 1
                        description: FRED series IDs (e.g., "WALCL", "FEDFUNDS"). Max 10.
                    maxItems: 10
                    minItems: 1
                limit:
                    type: integer
                    format: int32
                    description: Maximum number of observations per series. Defaults to 120.
            description: GetFredSeriesBatchRequest looks up multiple FRED series in a single call.
        worldmonitor_economic_v1_GetFredSeriesBatchResponse:
            type: object
            properties:
                results:
                    type: object
                    additionalProperties:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_FredSeries'
                    description: Map of series_id -> FRED series for found series.
                fetched:
                    type: integer
                    format: int32
                    description: Number of series successfully fetched.
                requested:
                    type: integer
                    format: int32
                    description: Number of series requested.
            description: GetFredSeriesBatchResponse contains the requested FRED series data.
        worldmonitor_economic_v1_GetFredSeriesBatchResponse_ResultsEntry:
            type: object
            properties:
                key:
                    type: string
                value:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_FredSeries'
        worldmonitor_economic_v1_ListGroceryBasketPricesRequest:
            type: object
        worldmonitor_economic_v1_ListGroceryBasketPricesResponse:
            type: object
            properties:
                countries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_CountryBasket'
                fetchedAt:
                    type: string
                cheapestCountry:
                    type: string
                mostExpensiveCountry:
                    type: string
                upstreamUnavailable:
                    type: boolean
                wowAvgPct:
                    type: number
                    format: double
                wowAvailable:
                    type: boolean
                prevFetchedAt:
                    type: string
        worldmonitor_economic_v1_CountryBasket:
            type: object
            properties:
                code:
                    type: string
                name:
                    type: string
                currency:
                    type: string
                flag:
                    type: string
                totalUsd:
                    type: number
                    format: double
                fxRate:
                    type: number
                    format: double
                items:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_GroceryItemPrice'
                wowPct:
                    type: number
                    format: double
        worldmonitor_economic_v1_GroceryItemPrice:
            type: object
            properties:
                itemId:
                    type: string
                itemName:
                    type: string
                unit:
                    type: string
                localPrice:
                    type: number
                    format: double
                usdPrice:
                    type: number
                    format: double
                currency:
                    type: string
                sourceSite:
                    type: string
                available:
                    type: boolean
        worldmonitor_economic_v1_ListBigMacPricesRequest:
            type: object
        worldmonitor_economic_v1_ListBigMacPricesResponse:
            type: object
            properties:
                countries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_BigMacCountryPrice'
                fetchedAt:
                    type: string
                cheapestCountry:
                    type: string
                mostExpensiveCountry:
                    type: string
                wowAvgPct:
                    type: number
                    format: double
                wowAvailable:
                    type: boolean
                prevFetchedAt:
                    type: string
        worldmonitor_economic_v1_BigMacCountryPrice:
            type: object
            properties:
                code:
                    type: string
                name:
                    type: string
                currency:
                    type: string
                flag:
                    type: string
                localPrice:
                    type: number
                    format: double
                usdPrice:
                    type: number
                    format: double
                fxRate:
                    type: number
                    format: double
                sourceSite:
                    type: string
                available:
                    type: boolean
                wowPct:
                    type: number
                    format: double
        worldmonitor_economic_v1_GetNationalDebtRequest:
            type: object
            description: GetNationalDebtRequest requests national debt data for all countries.
        worldmonitor_economic_v1_GetNationalDebtResponse:
            type: object
            properties:
                entries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_NationalDebtEntry'
                seededAt:
                    type: string
                    description: ISO 8601 timestamp when seed data was written.
                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: GetNationalDebtResponse wraps the full list of national debt entries.
        worldmonitor_economic_v1_NationalDebtEntry:
            type: object
            properties:
                iso3:
                    type: string
                    description: ISO3 country code (e.g. "USA").
                debtUsd:
                    type: number
                    format: double
                    description: Total debt in USD at baseline_ts.
                gdpUsd:
                    type: number
                    format: double
                    description: GDP in USD (nominal, latest year).
                debtToGdp:
                    type: number
                    format: double
                    description: Debt as % of GDP.
                annualGrowth:
                    type: number
                    format: double
                    description: Year-over-year debt growth percent (2023->2024).
                perSecondRate:
                    type: number
                    format: double
                    description: Deficit-derived accrual in USD per second.
                perDayRate:
                    type: number
                    format: double
                    description: Deficit-derived accrual in USD per day.
                baselineTs:
                    type: string
                    format: int64
                    description: UTC ms timestamp anchoring the debt_usd figure (2024-01-01T00:00:00Z).
                source:
                    type: string
                    description: Human-readable source string.
            description: NationalDebtEntry holds debt data for a single country.
        worldmonitor_economic_v1_ListFuelPricesRequest:
            type: object
        worldmonitor_economic_v1_ListFuelPricesResponse:
            type: object
            properties:
                countries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_FuelCountryPrice'
                fetchedAt:
                    type: string
                cheapestGasoline:
                    type: string
                cheapestDiesel:
                    type: string
                mostExpensiveGasoline:
                    type: string
                mostExpensiveDiesel:
                    type: string
                wowAvailable:
                    type: boolean
                prevFetchedAt:
                    type: string
                sourceCount:
                    type: integer
                    format: int32
                countryCount:
                    type: integer
                    format: int32
        worldmonitor_economic_v1_FuelCountryPrice:
            type: object
            properties:
                code:
                    type: string
                name:
                    type: string
                currency:
                    type: string
                flag:
                    type: string
                gasoline:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_FuelPrice'
                diesel:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_FuelPrice'
                fxRate:
                    type: number
                    format: double
        worldmonitor_economic_v1_FuelPrice:
            type: object
            properties:
                usdPrice:
                    type: number
                    format: double
                localPrice:
                    type: number
                    format: double
                grade:
                    type: string
                source:
                    type: string
                available:
                    type: boolean
                wowPct:
                    type: number
                    format: double
                observedAt:
                    type: string
        worldmonitor_economic_v1_GetBlsSeriesRequest:
            type: object
            properties:
                seriesId:
                    type: string
                    description: 'BLS/FRED-backed series ID. Supported values: "USPRIV", "ECIALLCIV".'
                limit:
                    type: integer
                    format: int32
                    description: Maximum number of observations to return. Defaults to 60.
            description: GetBlsSeriesRequest specifies which BLS series to retrieve.
        worldmonitor_economic_v1_GetBlsSeriesResponse:
            type: object
            properties:
                series:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_BlsSeries'
            description: GetBlsSeriesResponse contains the requested BLS series data.
        worldmonitor_economic_v1_BlsSeries:
            type: object
            properties:
                seriesId:
                    type: string
                    description: BLS series ID (e.g. "CES0500000001").
                title:
                    type: string
                    description: Human-readable series title.
                units:
                    type: string
                    description: Unit of measure.
                observations:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_BlsObservation'
            description: BlsSeries is a BLS time series with metadata and observations.
        worldmonitor_economic_v1_BlsObservation:
            type: object
            properties:
                year:
                    type: string
                    description: Year of the observation.
                period:
                    type: string
                    description: Period code (e.g. "M01" for January, "A01" for annual).
                periodName:
                    type: string
                    description: Human-readable period name.
                value:
                    type: string
                    description: Observed value.
            description: BlsObservation is a single BLS data point.
        worldmonitor_economic_v1_GetEconomicCalendarRequest:
            type: object
            properties:
                fromDate:
                    type: string
                    description: Accepted but currently ignored; no-op until this handler supports the parameter.
                toDate:
                    type: string
                    description: Accepted but currently ignored; no-op until this handler supports the parameter.
        worldmonitor_economic_v1_GetEconomicCalendarResponse:
            type: object
            properties:
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_EconomicEvent'
                fromDate:
                    type: string
                toDate:
                    type: string
                total:
                    type: integer
                    format: int32
                unavailable:
                    type: boolean
                    description: |-
                        True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
        worldmonitor_economic_v1_EconomicEvent:
            type: object
            properties:
                event:
                    type: string
                country:
                    type: string
                date:
                    type: string
                impact:
                    type: string
                actual:
                    type: string
                estimate:
                    type: string
                previous:
                    type: string
                unit:
                    type: string
        worldmonitor_economic_v1_GetCrudeInventoriesRequest:
            type: object
            description: GetCrudeInventoriesRequest is the request message for GetCrudeInventories.
        worldmonitor_economic_v1_GetCrudeInventoriesResponse:
            type: object
            properties:
                weeks:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_CrudeInventoryWeek'
                latestPeriod:
                    type: string
                    description: Timestamp of the most recent EIA data point (ISO 8601).
            description: GetCrudeInventoriesResponse contains the 8 most recent weeks of US crude oil inventory data.
        worldmonitor_economic_v1_CrudeInventoryWeek:
            type: object
            properties:
                period:
                    type: string
                    description: ISO week period (YYYY-MM-DD, Monday of the EIA report week).
                stocksMb:
                    type: number
                    format: double
                    description: Total crude oil stocks in millions of barrels.
                weeklyChangeMb:
                    type: number
                    format: double
                    description: |-
                        Week-over-week change in millions of barrels. Positive = build (bearish), negative = draw (bullish).
                         Absent for the oldest week when no prior week is available for comparison.
            description: CrudeInventoryWeek represents one week of US crude oil stockpile data from EIA WCRSTUS1.
        worldmonitor_economic_v1_GetNatGasStorageRequest:
            type: object
            description: GetNatGasStorageRequest is the request message for GetNatGasStorage.
        worldmonitor_economic_v1_GetNatGasStorageResponse:
            type: object
            properties:
                weeks:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_NatGasStorageWeek'
                latestPeriod:
                    type: string
                    description: Timestamp of the most recent EIA data point (ISO 8601).
            description: GetNatGasStorageResponse contains the 8 most recent weeks of US natural gas storage data.
        worldmonitor_economic_v1_NatGasStorageWeek:
            type: object
            properties:
                period:
                    type: string
                    description: ISO week period (YYYY-MM-DD, Monday of the EIA report week).
                storBcf:
                    type: number
                    format: double
                    description: Working gas in underground storage, Lower-48 States, in Bcf.
                weeklyChangeBcf:
                    type: number
                    format: double
                    description: |-
                        Week-over-week change in Bcf. Positive = build (bearish for gas prices), negative = draw (bullish).
                         Absent for the oldest week when no prior week is available for comparison.
            description: NatGasStorageWeek represents one week of US natural gas working gas storage data from EIA.
        worldmonitor_economic_v1_GetEcbFxRatesRequest:
            type: object
            description: GetEcbFxRatesRequest is empty; returns all tracked EUR pairs.
        worldmonitor_economic_v1_GetEcbFxRatesResponse:
            type: object
            properties:
                rates:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_EcbFxRate'
                updatedAt:
                    type: string
                    description: ISO 8601 timestamp of the ECB publication.
                seededAt:
                    type: string
                    format: int64
                    description: Unix ms when the data was last seeded.
                unavailable:
                    type: boolean
                    description: |-
                        True when Redis key is missing or data is unavailable.
                         True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
            description: GetEcbFxRatesResponse contains the latest ECB reference rates.
        worldmonitor_economic_v1_EcbFxRate:
            type: object
            properties:
                pair:
                    type: string
                    description: Currency pair label, e.g. "EURUSD".
                rate:
                    type: number
                    format: double
                    description: Exchange rate (units of quote currency per 1 EUR).
                date:
                    type: string
                    description: Date of the observation in YYYY-MM-DD format.
                change1d:
                    type: number
                    format: double
                    description: 1-day change in rate (absolute).
            description: EcbFxRate is a single ECB official reference rate for a currency pair.
        worldmonitor_economic_v1_GetEurostatCountryDataRequest:
            type: object
            description: GetEurostatCountryDataRequest requests Eurostat per-country economic data.
        worldmonitor_economic_v1_GetEurostatCountryDataResponse:
            type: object
            properties:
                countries:
                    type: object
                    additionalProperties:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_EurostatCountryEntry'
                    description: Map of ISO2 country code to economic metrics (e.g. "DE", "FR", "IT").
                seededAt:
                    type: string
                    format: int64
                    description: UTC ms timestamp when seed data was written.
                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: GetEurostatCountryDataResponse contains per-country CPI, unemployment, and GDP growth.
        worldmonitor_economic_v1_GetEurostatCountryDataResponse_CountriesEntry:
            type: object
            properties:
                key:
                    type: string
                value:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_EurostatCountryEntry'
        worldmonitor_economic_v1_EurostatCountryEntry:
            type: object
            properties:
                cpi:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_EurostatMetric'
                unemployment:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_EurostatMetric'
                gdpGrowth:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_EurostatMetric'
            description: EurostatCountryEntry holds all available metrics for one EU country.
        worldmonitor_economic_v1_EurostatMetric:
            type: object
            properties:
                value:
                    type: number
                    format: double
                    description: Numeric value (e.g. 2.3 for 2.3%).
                date:
                    type: string
                    description: Period string (e.g. "2024-01" for monthly, "2024-Q1" for quarterly).
                unit:
                    type: string
                    description: Unit of measurement (e.g. "%").
                priorValue:
                    type: number
                    format: double
                    description: Prior period value for delta calculation (e.g. previous month/quarter).
                hasPrior:
                    type: boolean
                    description: True when prior_value is present (proto3 can't distinguish 0 from absent).
            description: EurostatMetric holds a single economic metric value for a country.
        worldmonitor_economic_v1_GetEuGasStorageRequest:
            type: object
            description: GetEuGasStorageRequest is empty — returns latest EU aggregate snapshot.
        worldmonitor_economic_v1_GetEuGasStorageResponse:
            type: object
            properties:
                fillPct:
                    type: number
                    format: double
                    description: Current storage fill level as a percentage of working gas volume (0–100).
                fillPctChange1d:
                    type: number
                    format: double
                    description: 1-day change in fill percentage (positive = injecting, negative = withdrawing).
                gasDaysConsumption:
                    type: number
                    format: double
                    description: Approximate days of consumption remaining at average EU winter drawdown rate.
                trend:
                    type: string
                    description: 'Current storage trend: "injecting", "withdrawing", or "stable".'
                history:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_EuGasStorageHistoryEntry'
                seededAt:
                    type: string
                    format: int64
                    description: UTC ms timestamp when seed data was written.
                updatedAt:
                    type: string
                    description: Calendar date of the most recent data point (YYYY-MM-DD).
                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: GetEuGasStorageResponse contains the EU aggregate gas storage snapshot.
        worldmonitor_economic_v1_EuGasStorageHistoryEntry:
            type: object
            properties:
                date:
                    type: string
                    description: Calendar date (YYYY-MM-DD).
                fillPct:
                    type: number
                    format: double
                    description: Storage fill level as a percentage of working gas volume capacity.
                gasTwh:
                    type: number
                    format: double
                    description: Working gas volume in storage (TWh).
            description: EuGasStorageHistoryEntry represents one day of EU aggregate gas storage data.
        worldmonitor_economic_v1_GetEuYieldCurveRequest:
            type: object
            description: GetEuYieldCurveRequest fetches the ECB Euro Area AAA sovereign yield curve.
        worldmonitor_economic_v1_GetEuYieldCurveResponse:
            type: object
            properties:
                data:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_EuYieldCurveData'
                unavailable:
                    type: boolean
                    description: |-
                        True if data is not yet available in cache.
                         True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
            description: GetEuYieldCurveResponse contains the latest ECB Euro Area AAA sovereign yield curve.
        worldmonitor_economic_v1_EuYieldCurveData:
            type: object
            properties:
                date:
                    type: string
                    description: Date of the observation (YYYY-MM or YYYY-MM-DD).
                rates:
                    type: object
                    additionalProperties:
                        type: number
                        format: double
                    description: 'Spot rates by tenor. Keys: "1Y", "2Y", "5Y", "10Y", "20Y", "30Y".'
                source:
                    type: string
                    description: Data source identifier (e.g. "ecb-aaa").
                updatedAt:
                    type: string
                    description: ISO 8601 timestamp when this was last seeded.
            description: EuYieldCurveData holds a single observation of the ECB Euro Area AAA yield curve.
        worldmonitor_economic_v1_EuYieldCurveData_RatesEntry:
            type: object
            properties:
                key:
                    type: string
                value:
                    type: number
                    format: double
        worldmonitor_economic_v1_GetEuFsiRequest:
            type: object
        worldmonitor_economic_v1_GetEuFsiResponse:
            type: object
            properties:
                latestValue:
                    type: number
                    format: double
                latestDate:
                    type: string
                label:
                    type: string
                history:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_EuFsiObservation'
                seededAt:
                    type: string
                unavailable:
                    type: boolean
                    description: |-
                        True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
                stale:
                    type: boolean
                    description: |-
                        True when latest_date is older than the CISS content-age budget -- the ECB
                         series has stopped publishing (issue #3845). Consumers must not present a
                         stale reading as current. Seeder-side detection is content-age
                         (STALE_CONTENT in /api/health); this flag is the per-request equivalent.
        worldmonitor_economic_v1_EuFsiObservation:
            type: object
            properties:
                date:
                    type: string
                value:
                    type: number
                    format: double
        worldmonitor_economic_v1_GetEconomicStressRequest:
            type: object
        worldmonitor_economic_v1_GetEconomicStressResponse:
            type: object
            properties:
                compositeScore:
                    type: number
                    format: double
                label:
                    type: string
                components:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_EconomicStressComponent'
                seededAt:
                    type: string
                unavailable:
                    type: boolean
                    description: |-
                        True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
        worldmonitor_economic_v1_EconomicStressComponent:
            type: object
            properties:
                id:
                    type: string
                label:
                    type: string
                rawValue:
                    type: number
                    format: double
                score:
                    type: number
                    format: double
                weight:
                    type: number
                    format: double
                missing:
                    type: boolean
        worldmonitor_economic_v1_GetFaoFoodPriceIndexRequest:
            type: object
        worldmonitor_economic_v1_GetFaoFoodPriceIndexResponse:
            type: object
            properties:
                points:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_FaoFoodPricePoint'
                fetchedAt:
                    type: string
                currentFfpi:
                    type: number
                    format: double
                momPct:
                    type: number
                    format: double
                yoyPct:
                    type: number
                    format: double
        worldmonitor_economic_v1_FaoFoodPricePoint:
            type: object
            properties:
                date:
                    type: string
                ffpi:
                    type: number
                    format: double
                meat:
                    type: number
                    format: double
                dairy:
                    type: number
                    format: double
                cereals:
                    type: number
                    format: double
                oils:
                    type: number
                    format: double
                sugar:
                    type: number
                    format: double
        worldmonitor_economic_v1_GetOilStocksAnalysisRequest:
            type: object
            description: GetOilStocksAnalysisRequest is empty — returns the latest global analysis snapshot.
        worldmonitor_economic_v1_GetOilStocksAnalysisResponse:
            type: object
            properties:
                updatedAt:
                    type: string
                    description: UTC ISO-8601 timestamp when this analysis was written.
                dataMonth:
                    type: string
                    description: 'Data month in YYYY-MM format (source: IEA monthly release).'
                ieaMembers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_OilStocksAnalysisMember'
                belowObligation:
                    type: array
                    items:
                        type: string
                        description: ISO2 codes of countries currently below the 90-day obligation.
                regionalSummary:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_OilStocksRegionalSummary'
                unavailable:
                    type: boolean
                    description: |-
                        True when upstream seed 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: GetOilStocksAnalysisResponse contains the IEA oil stocks days-of-cover analysis.
        worldmonitor_economic_v1_OilStocksAnalysisMember:
            type: object
            properties:
                iso2:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                daysOfCover:
                    type: integer
                    format: int32
                    description: Days of supply cover (absent when country is a net exporter or data anomaly).
                netExporter:
                    type: boolean
                    description: True when the country is classified as a net exporter by IEA.
                belowObligation:
                    type: boolean
                    description: True when days_of_cover < 90 (IEA 90-day obligation threshold).
                obligationMet:
                    type: boolean
                    description: True when the 90-day obligation is met (net exporters always true).
                rank:
                    type: integer
                    format: int32
                    description: Rank within the IEA member ranking (1-indexed, net exporters ranked last).
                vsObligation:
                    type: integer
                    format: int32
                    description: days_of_cover - 90; absent for net exporters.
            description: OilStocksAnalysisMember holds days-of-cover data and obligation status for one IEA member country.
        worldmonitor_economic_v1_OilStocksRegionalSummary:
            type: object
            properties:
                europe:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_OilStocksRegionalSummaryEurope'
                asiaPacific:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_OilStocksRegionalSummaryAsiaPacific'
                northAmerica:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_OilStocksRegionalSummaryNorthAmerica'
            description: OilStocksRegionalSummary holds regional aggregates for the three IEA regions.
        worldmonitor_economic_v1_OilStocksRegionalSummaryEurope:
            type: object
            properties:
                avgDays:
                    type: integer
                    format: int32
                    description: Mean days of cover across non-net-exporter European members.
                minDays:
                    type: integer
                    format: int32
                    description: Minimum days of cover across non-net-exporter European members.
                countBelowObligation:
                    type: integer
                    format: int32
                    description: Count of European members below the 90-day obligation.
            description: OilStocksRegionalSummaryEurope aggregates days-of-cover for European IEA members.
        worldmonitor_economic_v1_OilStocksRegionalSummaryAsiaPacific:
            type: object
            properties:
                avgDays:
                    type: integer
                    format: int32
                    description: Mean days of cover across Asia-Pacific members (AU, JP, KR, NZ).
                minDays:
                    type: integer
                    format: int32
                    description: Minimum days of cover across Asia-Pacific members.
                countBelowObligation:
                    type: integer
                    format: int32
                    description: Count of Asia-Pacific members below the 90-day obligation.
            description: OilStocksRegionalSummaryAsiaPacific aggregates days-of-cover for Asia-Pacific IEA members.
        worldmonitor_economic_v1_OilStocksRegionalSummaryNorthAmerica:
            type: object
            properties:
                netExporters:
                    type: integer
                    format: int32
                    description: Count of net exporters in North America (CA, MX, US).
                avgDays:
                    type: integer
                    format: int32
                    description: Average days of cover for non-exporter North American members (if any).
            description: OilStocksRegionalSummaryNorthAmerica aggregates data for North American IEA members.
        worldmonitor_economic_v1_GetOilInventoriesRequest:
            type: object
        worldmonitor_economic_v1_GetOilInventoriesResponse:
            type: object
            properties:
                crudeWeeks:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_CrudeInventoryWeekRef'
                spr:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_OilInventoriesSprSnapshot'
                natGasWeeks:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_NatGasWeekRef'
                euGas:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_OilInventoriesEuGas'
                ieaStocks:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_OilInventoriesIeaStocks'
                refinery:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_OilInventoriesRefinery'
                updatedAt:
                    type: string
        worldmonitor_economic_v1_CrudeInventoryWeekRef:
            type: object
            properties:
                period:
                    type: string
                stocksMb:
                    type: number
                    format: double
                weeklyChangeMb:
                    type: number
                    format: double
        worldmonitor_economic_v1_OilInventoriesSprSnapshot:
            type: object
            properties:
                latestStocksMb:
                    type: number
                    format: double
                changeWow:
                    type: number
                    format: double
                weeks:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_OilInventoriesSprWeek'
        worldmonitor_economic_v1_OilInventoriesSprWeek:
            type: object
            properties:
                period:
                    type: string
                stocksMb:
                    type: number
                    format: double
        worldmonitor_economic_v1_NatGasWeekRef:
            type: object
            properties:
                period:
                    type: string
                storBcf:
                    type: number
                    format: double
                weeklyChangeBcf:
                    type: number
                    format: double
        worldmonitor_economic_v1_OilInventoriesEuGas:
            type: object
            properties:
                fillPct:
                    type: number
                    format: double
                fillPctChange1d:
                    type: number
                    format: double
                trend:
                    type: string
                history:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_OilInventoriesEuGasDay'
        worldmonitor_economic_v1_OilInventoriesEuGasDay:
            type: object
            properties:
                date:
                    type: string
                fillPct:
                    type: number
                    format: double
        worldmonitor_economic_v1_OilInventoriesIeaStocks:
            type: object
            properties:
                dataMonth:
                    type: string
                members:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_OilInventoriesIeaMember'
                europe:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_OilInventoriesRegionStats'
                asiaPacific:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_OilInventoriesRegionStats'
                northAmerica:
                    $ref: '#/components/schemas/worldmonitor_economic_v1_OilInventoriesRegionStats'
        worldmonitor_economic_v1_OilInventoriesIeaMember:
            type: object
            properties:
                iso2:
                    type: string
                daysOfCover:
                    type: number
                    format: double
                netExporter:
                    type: boolean
                belowObligation:
                    type: boolean
        worldmonitor_economic_v1_OilInventoriesRegionStats:
            type: object
            properties:
                avgDays:
                    type: number
                    format: double
                minDays:
                    type: number
                    format: double
                countBelowObligation:
                    type: integer
                    format: int32
        worldmonitor_economic_v1_OilInventoriesRefinery:
            type: object
            properties:
                inputsMbpd:
                    type: number
                    format: double
                period:
                    type: string
        worldmonitor_economic_v1_GetEnergyCrisisPoliciesRequest:
            type: object
            properties:
                countryCode:
                    type: string
                    description: Optional ISO-2 country code filter.
                category:
                    type: string
                    description: 'Optional category filter: "conservation" or "consumer_support".'
            description: GetEnergyCrisisPoliciesRequest allows optional filtering by country or category.
        worldmonitor_economic_v1_GetEnergyCrisisPoliciesResponse:
            type: object
            properties:
                source:
                    type: string
                    description: Source attribution.
                sourceUrl:
                    type: string
                    description: Source URL.
                context:
                    type: string
                    description: Context description.
                policies:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_economic_v1_EnergyCrisisPolicy'
                updatedAt:
                    type: string
                    description: UTC ISO-8601 timestamp when this data was last updated.
                unavailable:
                    type: boolean
                    description: |-
                        True when upstream seed 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: GetEnergyCrisisPoliciesResponse contains energy crisis policy data from the IEA tracker.
        worldmonitor_economic_v1_EnergyCrisisPolicy:
            type: object
            properties:
                country:
                    type: string
                    description: Country name.
                countryCode:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                category:
                    type: string
                    description: 'Policy category: "conservation" or "consumer_support".'
                sector:
                    type: string
                    description: 'Affected sector: transport, buildings, industry, electricity, agriculture, general.'
                measure:
                    type: string
                    description: Description of the policy measure.
                dateAnnounced:
                    type: string
                    description: Date announced in ISO-8601 (YYYY-MM-DD) format.
                status:
                    type: string
                    description: 'Status of the policy: active, planned, or ended.'
            description: EnergyCrisisPolicy represents a single government policy response to the 2026 energy crisis.
        worldmonitor_forecast_v1_GetForecastsRequest:
            type: object
            properties:
                domain:
                    type: string
                    description: Forecast domain to retrieve, such as geopolitics, markets, or climate.
                region:
                    type: string
                    description: Optional geographic or thematic region filter for forecasts.
        worldmonitor_forecast_v1_GetForecastsResponse:
            type: object
            properties:
                forecasts:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_forecast_v1_Forecast'
                generatedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                degraded:
                    type: boolean
                    description: |-
                        True when the forecast backend could not read the canonical cache.
                         Distinguishes an outage from a healthy empty forecast set.
                stale:
                    type: boolean
                    description: |-
                        True when forecasts are served from a stale fallback. Currently false for
                         this endpoint because get-forecasts does not have a stale fallback cache.
                error:
                    type: string
                    description: |-
                        Stable machine-readable reason when degraded=true, empty otherwise.
                         Value: "forecast_backend_unavailable" on Redis/backend read failures.
        worldmonitor_forecast_v1_Forecast:
            type: object
            properties:
                id:
                    type: string
                domain:
                    type: string
                region:
                    type: string
                title:
                    type: string
                scenario:
                    type: string
                feedSummary:
                    type: string
                probability:
                    type: number
                    format: double
                confidence:
                    type: number
                    format: double
                timeHorizon:
                    type: string
                signals:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_forecast_v1_ForecastSignal'
                cascades:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_forecast_v1_CascadeEffect'
                trend:
                    type: string
                    description: |-
                        Forecast trend direction. Current values are "rising", "falling", and
                         "stable". The seeder compares probability against the prior forecast
                         snapshot and uses a +/-0.05 deadband: deltas above +0.05 are rising,
                         below -0.05 are falling, and everything inside the band is stable.
                priorProbability:
                    type: number
                    format: double
                calibration:
                    $ref: '#/components/schemas/worldmonitor_forecast_v1_CalibrationInfo'
                createdAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                perspectives:
                    $ref: '#/components/schemas/worldmonitor_forecast_v1_Perspectives'
                projections:
                    $ref: '#/components/schemas/worldmonitor_forecast_v1_Projections'
                caseFile:
                    $ref: '#/components/schemas/worldmonitor_forecast_v1_ForecastCase'
                simulationAdjustment:
                    type: number
                    format: double
                    description: |-
                        Simulation-scoring fields — populated when the deep forecast simulation pipeline
                         has run for this forecast's state and produced a non-zero adjustment.
                         simulation_adjustment: raw score delta (+0.08–+0.12 positive, -0.12/-0.15 negative).
                         sim_path_confidence: clamped [0,1] confidence of the matched sim top-path; 0 = not set.
                         demoted_by_simulation: true when a negative adjustment crossed the 0.50 acceptance threshold.
                simPathConfidence:
                    type: number
                    format: double
                demotedBySimulation:
                    type: boolean
                resolution:
                    $ref: '#/components/schemas/worldmonitor_forecast_v1_ResolutionSpec'
        worldmonitor_forecast_v1_ForecastSignal:
            type: object
            properties:
                type:
                    type: string
                value:
                    type: string
                weight:
                    type: number
                    format: double
        worldmonitor_forecast_v1_CascadeEffect:
            type: object
            properties:
                domain:
                    type: string
                effect:
                    type: string
                probability:
                    type: number
                    format: double
        worldmonitor_forecast_v1_CalibrationInfo:
            type: object
            properties:
                marketTitle:
                    type: string
                marketPrice:
                    type: number
                    format: double
                drift:
                    type: number
                    format: double
                source:
                    type: string
        worldmonitor_forecast_v1_Perspectives:
            type: object
            properties:
                strategic:
                    type: string
                regional:
                    type: string
                contrarian:
                    type: string
        worldmonitor_forecast_v1_Projections:
            type: object
            properties:
                h24:
                    type: number
                    format: double
                    description: Projected 24-hour probability after domain-curve normalization.
                d7:
                    type: number
                    format: double
                    description: Projected 7-day probability after domain-curve normalization.
                d30:
                    type: number
                    format: double
                    description: Projected 30-day probability after domain-curve normalization.
            description: |-
                Projections contains bounded presentation-path probabilities derived from
                 domain curves. Market forecasts are peak-anchored, so the projected value at
                 the forecast's own time_horizon can intentionally differ from the headline
                 probability; non-market forecasts preserve their emitted horizon as anchor.
        worldmonitor_forecast_v1_ForecastCase:
            type: object
            properties:
                supportingEvidence:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_forecast_v1_ForecastCaseEvidence'
                counterEvidence:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_forecast_v1_ForecastCaseEvidence'
                triggers:
                    type: array
                    items:
                        type: string
                actorLenses:
                    type: array
                    items:
                        type: string
                baseCase:
                    type: string
                escalatoryCase:
                    type: string
                contrarianCase:
                    type: string
                changeSummary:
                    type: string
                changeItems:
                    type: array
                    items:
                        type: string
                actors:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_forecast_v1_ForecastActor'
                worldState:
                    $ref: '#/components/schemas/worldmonitor_forecast_v1_ForecastWorldState'
                branches:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_forecast_v1_ForecastBranch'
        worldmonitor_forecast_v1_ForecastCaseEvidence:
            type: object
            properties:
                type:
                    type: string
                summary:
                    type: string
                weight:
                    type: number
                    format: double
        worldmonitor_forecast_v1_ForecastActor:
            type: object
            properties:
                id:
                    type: string
                name:
                    type: string
                category:
                    type: string
                role:
                    type: string
                objectives:
                    type: array
                    items:
                        type: string
                constraints:
                    type: array
                    items:
                        type: string
                likelyActions:
                    type: array
                    items:
                        type: string
                influenceScore:
                    type: number
                    format: double
        worldmonitor_forecast_v1_ForecastWorldState:
            type: object
            properties:
                summary:
                    type: string
                activePressures:
                    type: array
                    items:
                        type: string
                stabilizers:
                    type: array
                    items:
                        type: string
                keyUnknowns:
                    type: array
                    items:
                        type: string
        worldmonitor_forecast_v1_ForecastBranch:
            type: object
            properties:
                kind:
                    type: string
                title:
                    type: string
                summary:
                    type: string
                outcome:
                    type: string
                projectedProbability:
                    type: number
                    format: double
                rounds:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_forecast_v1_ForecastBranchRound'
        worldmonitor_forecast_v1_ForecastBranchRound:
            type: object
            properties:
                round:
                    type: integer
                    format: int32
                focus:
                    type: string
                developments:
                    type: array
                    items:
                        type: string
                actorMoves:
                    type: array
                    items:
                        type: string
                probabilityShift:
                    type: number
                    format: double
        worldmonitor_forecast_v1_ResolutionSpec:
            type: object
            properties:
                kind:
                    type: string
                metricKey:
                    type: string
                operator:
                    type: string
                threshold:
                    type: number
                    format: double
                baselineValue:
                    type: number
                    format: double
                window:
                    type: string
                deadline:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                sourceFeed:
                    type: string
                question:
                    type: string
            description: |-
                Machine-checkable resolution spec — makes a forecast a scoreable *bet*.
                 Every forecast carries exactly one spec, either "hard" or "judged":
                   - "hard":   auto-resolvable by a free metric comparison against a
                               WorldMonitor feed the detector already scored from. Sets
                               metric_key (feed + path expression), operator, threshold,
                               window, and source_feed (a RESOLUTION_FEED_KEYS allowlist
                               member). baseline_value is set only when operator is
                               "crosses" (the emission-time metric value the move is
                               measured from).
                   - "judged": resolved by a later LLM judge against the question string;
                               no numeric threshold, but still a resolution deadline.
                 kind and operator are strings, not proto enums, mirroring the trend field
                 above so a new operator/kind never requires a proto migration to land in
                 the 45-day history. Current kind values are "hard" and "judged"; current
                 operator values are ">=", "<=", and "crosses".
                 kind and deadline are always set; every other field is optional and absent
                 (persisted as JSON null) when it does not apply to the kind — a judged spec
                 carries no threshold/baseline_value so "no threshold" is never confused
                 with a real threshold of 0, and a hard spec carries no question.
        worldmonitor_forecast_v1_GetForecastScorecardRequest:
            type: object
        worldmonitor_forecast_v1_GetForecastScorecardResponse:
            type: object
            properties:
                schemaVersion:
                    type: integer
                    format: int32
                generatedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                rollingWindowDays:
                    type: integer
                    format: int32
                methodology:
                    type: string
                totals:
                    $ref: '#/components/schemas/worldmonitor_forecast_v1_ScorecardTotals'
                overall:
                    $ref: '#/components/schemas/worldmonitor_forecast_v1_ScorecardSummary'
                byDomain:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_forecast_v1_ScorecardDomainGroup'
                byGenerationOrigin:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_forecast_v1_ScorecardGenerationOriginGroup'
                calibration:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_forecast_v1_ScorecardCalibrationBucket'
                vsMarketSkill:
                    $ref: '#/components/schemas/worldmonitor_forecast_v1_ScorecardMarketSkill'
                degraded:
                    type: boolean
                stale:
                    type: boolean
                error:
                    type: string
                skill:
                    $ref: '#/components/schemas/worldmonitor_forecast_v1_ScorecardSkill'
        worldmonitor_forecast_v1_ScorecardTotals:
            type: object
            properties:
                entries:
                    type: integer
                    format: int32
                resolved:
                    type: integer
                    format: int32
                pending:
                    type: integer
                    format: int32
                pendingJudge:
                    type: integer
                    format: int32
                scored:
                    type: integer
                    format: int32
                void:
                    type: integer
                    format: int32
                voidRate:
                    type: number
                    format: double
                publicationCoverage:
                    type: number
                    format: double
        worldmonitor_forecast_v1_ScorecardSummary:
            type: object
            properties:
                count:
                    type: integer
                    format: int32
                brier:
                    type: number
                    format: double
                logScore:
                    type: number
                    format: double
        worldmonitor_forecast_v1_ScorecardDomainGroup:
            type: object
            properties:
                domain:
                    type: string
                resolved:
                    type: integer
                    format: int32
                scored:
                    type: integer
                    format: int32
                void:
                    type: integer
                    format: int32
                voidRate:
                    type: number
                    format: double
                brier:
                    type: number
                    format: double
                logScore:
                    type: number
                    format: double
        worldmonitor_forecast_v1_ScorecardGenerationOriginGroup:
            type: object
            properties:
                generationOrigin:
                    type: string
                resolved:
                    type: integer
                    format: int32
                scored:
                    type: integer
                    format: int32
                void:
                    type: integer
                    format: int32
                voidRate:
                    type: number
                    format: double
                brier:
                    type: number
                    format: double
                logScore:
                    type: number
                    format: double
        worldmonitor_forecast_v1_ScorecardCalibrationBucket:
            type: object
            properties:
                bucket:
                    type: string
                minProbability:
                    type: number
                    format: double
                maxProbability:
                    type: number
                    format: double
                count:
                    type: integer
                    format: int32
                predictedMean:
                    type: number
                    format: double
                realizedRate:
                    type: number
                    format: double
                brier:
                    type: number
                    format: double
        worldmonitor_forecast_v1_ScorecardMarketSkill:
            type: object
            properties:
                count:
                    type: integer
                    format: int32
                forecastBrier:
                    type: number
                    format: double
                marketBrier:
                    type: number
                    format: double
                brierDelta:
                    type: number
                    format: double
        worldmonitor_forecast_v1_ScorecardSkill:
            type: object
            properties:
                count:
                    type: integer
                    format: int32
                brier:
                    type: number
                    format: double
                logScore:
                    type: number
                    format: double
                excludedScored:
                    type: integer
                    format: int32
                excludedOrigins:
                    type: array
                    items:
                        type: string
            description: |-
                Headline "real skill" summary: Brier/log score over scored entries whose
                 generation origin is NOT synthetic backfill or an unpromoted shadow stream.
                 count 0 with excluded_scored > 0 means the headline is unmeasurable because
                 everything scored was synthetic — the honest signal for a collapsed funnel.
        worldmonitor_forecast_v1_GetSimulationPackageRequest:
            type: object
            properties:
                runId:
                    type: string
                    description: |-
                        Optional run identifier. Does not select the package — the latest stored package is
                         always returned regardless of this value. When supplied and it differs from the
                         returned package's runId, the response `note` field is populated to warn that per-run
                         filtering is not yet active. Reserved for Phase 3 per-run lookup.
        worldmonitor_forecast_v1_GetSimulationPackageResponse:
            type: object
            properties:
                found:
                    type: boolean
                runId:
                    type: string
                schemaVersion:
                    type: string
                theaterCount:
                    type: integer
                    format: int32
                generatedAt:
                    type: integer
                    format: int64
                    description: 'Unix timestamp in milliseconds (from Date.now()). Warning: Values > 2^53 may lose precision in JavaScript.. Warning: Values > 2^53 may lose precision in JavaScript'
                note:
                    type: string
                    description: |-
                        Populated when req.runId was supplied but does not match the returned package's runId.
                         Indicates that per-run filtering is not yet active and the latest package was returned instead.
                error:
                    type: string
                    description: |-
                        Populated when the Redis lookup failed. Distinguish from healthy not-found (found=false, error="").
                         Value: "redis_unavailable" on Redis errors.
        worldmonitor_forecast_v1_GetSimulationOutcomeRequest:
            type: object
            properties:
                runId:
                    type: string
                    description: |-
                        Filter is active for outcomes within the 24h retention window (#3734).
                         If runId is supplied:
                           - Hit on the by-run key → returns that outcome, processing=false.
                           - By-run lookup returns the tombstone (worker write transiently failed) →
                             falls through to :latest with a 'note' describing the transient failure.
                           - No by-run match but runId is in the queue → returns processing=true.
                           - No match anywhere → falls back to :latest with a 'note' describing
                             expiry-or-mismatch.
                         If runId is empty: returns :latest (existing behavior).
        worldmonitor_forecast_v1_GetSimulationOutcomeResponse:
            type: object
            properties:
                found:
                    type: boolean
                runId:
                    type: string
                schemaVersion:
                    type: string
                theaterCount:
                    type: integer
                    format: int32
                generatedAt:
                    type: integer
                    format: int64
                    description: 'Unix timestamp in milliseconds (from Date.now()). Warning: Values > 2^53 may lose precision in JavaScript.. Warning: Values > 2^53 may lose precision in JavaScript'
                note:
                    type: string
                    description: |-
                        Populated when req.runId was supplied but does not match the returned outcome's runId,
                         or when the by-run lookup returned a tombstone (Redis transient write failure).
                         Distinguishes "your runId expired beyond 24h retention" from "by-run lookup failed
                         (Redis transient); returned latest" so callers can react differently.
                error:
                    type: string
                    description: |-
                        Populated when the Redis lookup failed. Distinguish from healthy not-found (found=false, error="").
                         Value: "redis_unavailable" on Redis errors.
                theaterSummariesJson:
                    type: string
                    description: |-
                        JSON-encoded array of theater summaries for the UI (populated when found=true).
                         Shape: Array<{ theaterId, theaterLabel, stateKind, topPaths: [{label, summary, confidence, keyActors}], dominantReactions, stabilizers, invalidators }>
                         Parse with JSON.parse() on the client. Empty string when found=false.
                processing:
                    type: boolean
                    description: |-
                        True when req.runId was supplied AND the runId is currently in the simulation
                         queue (worker hasn't drained yet). Distinguishes "your run is processing"
                         from "your run expired beyond retention" — both previously returned NOT_FOUND.
                         Added in #3734 to prevent the 30-day demand experiment from being contaminated
                         by the queued-vs-expired indistinguishability.
                eligibleTheaterCount:
                    type: integer
                    format: int32
                    description: Number of theaters eligible for simulation in the package used by this outcome.
                failedTheaterCount:
                    type: integer
                    format: int32
                    description: Number of eligible theaters that failed before producing a Round 2 result.
                allTheatersFailed:
                    type: boolean
                    description: True when eligible_theater_count > 0 and no theater produced an outcome.
                completionStatus:
                    type: string
                    description: |-
                        Machine-readable completion status. Current values:
                         "completed", "partial", "no_eligible_theaters", or "all_theaters_failed".
        worldmonitor_forecast_v1_TriggerSimulationRequest:
            type: object
            properties:
                clientVersion:
                    type: string
                    description: |-
                        Optional opaque client-version string for debugging (e.g., "claude-
                         desktop/0.6.1", "mcp-client/0.2"). Server LOGS this with the success
                         breadcrumb but never persists or branches on it. Present primarily so
                         the generated client/server code has at least one field to reference
                         (sebuf v0.11.1 emits a typecheck-broken POST client for fully-empty
                         request messages). Safe to omit; default empty string.
            description: |-
                TriggerSimulationRequest enqueues a simulation task for the current
                 SIMULATION_PACKAGE_LATEST_KEY package pointer. Caller-supplied
                 run_id is intentionally absent — the runId is server-derived from
                 the package pointer (avoids lock-key collision, queue stuffing, and
                 race against cron rotation). See #3734 / docs/plans/2026-05-18-003-
                 feat-simulation-trigger-and-runid-filter-plan.md D1.
        worldmonitor_forecast_v1_TriggerSimulationResponse:
            type: object
            properties:
                queued:
                    type: boolean
                    description: |-
                        True when the task was newly enqueued; false on idempotency hit or
                         no_package.
                runId:
                    type: string
                    description: |-
                        Server-derived runId from SIMULATION_PACKAGE_LATEST_KEY. Empty
                         string when reason='no_package' (no package pointer was available).
                pkgFingerprint:
                    type: string
                    description: |-
                        Opaque fingerprint of the simulation package input (first 16 hex
                         chars of sha256 over the package's R2 object key). Stable identifier
                         for drift detection across trigger/read calls — clients can compare
                         this against the fingerprint inside the by-run outcome payload to
                         detect cron rotation. Do NOT decode. Returns empty string when
                         reason='no_package'.
                reason:
                    type: string
                    description: |-
                        External reason taxonomy:
                           ''                  - happy path (queued=true)
                           'no_package'        - SIMULATION_PACKAGE_LATEST_KEY pointer absent
                           'already-handled'   - idempotency hit (covers both "already queued"
                                                 and "already completed this cycle"; collapsed
                                                 externally to avoid a cron-timing oracle —
                                                 server logs retain the distinction).
            description: |-
                TriggerSimulationResponse carries the outcome of an enqueue attempt.
                 On error states (premium gate, queue capacity, Redis transport), the
                 handler throws ApiError with the appropriate HTTP status — there is
                 NO error field on this message. All paths that return this message
                 represent HTTP 200.
        worldmonitor_giving_v1_GetGivingSummaryRequest:
            type: object
            properties:
                platformLimit:
                    type: integer
                    format: int32
                    description: Number of platforms to include (0 = all).
                categoryLimit:
                    type: integer
                    format: int32
                    description: Number of category breakdowns to include (0 = all).
            description: GetGivingSummaryRequest specifies parameters for retrieving the global giving summary.
        worldmonitor_giving_v1_GetGivingSummaryResponse:
            type: object
            properties:
                summary:
                    $ref: '#/components/schemas/worldmonitor_giving_v1_GivingSummary'
                fetchedAt:
                    type: integer
                    format: int64
                    description: |-
                        Time the summary was generated, as Unix epoch milliseconds. A value of 0
                         means the snapshot is unavailable/degraded, not that giving activity is
                         zero.. Warning: Values > 2^53 may lose precision in JavaScript
                dataAvailable:
                    type: boolean
                    description: |-
                        True when summary is populated. False means an absent/empty summary is
                         graceful degradation because the snapshot is unavailable.
            description: GetGivingSummaryResponse contains the global giving activity summary.
        worldmonitor_giving_v1_GivingSummary:
            type: object
            properties:
                generatedAt:
                    type: string
                    description: Timestamp of the summary generation (ISO 8601).
                activityIndex:
                    type: number
                    format: double
                    description: Global giving activity index (0-100 composite score).
                trend:
                    type: string
                    description: Index trend direction.
                estimatedDailyFlowUsd:
                    type: number
                    format: double
                    description: Estimated daily global giving flow in USD (directional, not precise).
                platforms:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_giving_v1_PlatformGiving'
                categories:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_giving_v1_CategoryBreakdown'
                crypto:
                    $ref: '#/components/schemas/worldmonitor_giving_v1_CryptoGivingSummary'
                institutional:
                    $ref: '#/components/schemas/worldmonitor_giving_v1_InstitutionalGiving'
            description: GivingSummary represents a global overview of personal giving activity across platforms.
        worldmonitor_giving_v1_PlatformGiving:
            type: object
            properties:
                platform:
                    type: string
                    minLength: 1
                    description: Platform name (e.g., "GoFundMe", "GlobalGiving", "JustGiving").
                dailyVolumeUsd:
                    type: number
                    format: double
                    description: Estimated daily donation volume in USD.
                activeCampaignsSampled:
                    type: integer
                    format: int32
                    description: Number of active campaigns being sampled.
                newCampaigns24h:
                    type: integer
                    format: int32
                    description: New campaigns created in the last 24 hours.
                donationVelocity:
                    type: number
                    format: double
                    description: Average donation velocity (donations per hour).
                dataFreshness:
                    type: string
                    description: 'Data freshness: "live", "daily", "weekly", "annual".'
                lastUpdated:
                    type: string
                    description: Last data update timestamp (ISO 8601).
            required:
                - platform
            description: PlatformGiving represents aggregated giving data from a single crowdfunding platform.
        worldmonitor_giving_v1_CategoryBreakdown:
            type: object
            properties:
                category:
                    type: string
                    description: Category name (e.g., "Medical", "Disaster Relief", "Education").
                share:
                    type: number
                    format: double
                    description: Share of total giving activity (0-1).
                change24h:
                    type: number
                    format: double
                    description: 24-hour change in share percentage points.
                activeCampaigns:
                    type: integer
                    format: int32
                    description: Number of active campaigns in this category.
                trending:
                    type: boolean
                    description: Trending indicator.
            description: CategoryBreakdown represents giving activity within a specific cause category.
        worldmonitor_giving_v1_CryptoGivingSummary:
            type: object
            properties:
                dailyInflowUsd:
                    type: number
                    format: double
                    description: Total 24h inflow to tracked charity wallets (USD equivalent).
                trackedWallets:
                    type: integer
                    format: int32
                    description: Number of tracked charity wallets.
                transactions24h:
                    type: integer
                    format: int32
                    description: Number of transactions in the last 24 hours.
                topReceivers:
                    type: array
                    items:
                        type: string
                        description: Top receiving platforms / DAOs.
                pctOfTotal:
                    type: number
                    format: double
                    description: Percentage of total giving that is on-chain.
            description: CryptoGivingSummary tracks transparent on-chain philanthropy.
        worldmonitor_giving_v1_InstitutionalGiving:
            type: object
            properties:
                oecdOdaAnnualUsdBn:
                    type: number
                    format: double
                    description: Latest OECD ODA total (annual, USD billions).
                oecdDataYear:
                    type: integer
                    format: int32
                    description: Year of latest OECD data.
                cafWorldGivingIndex:
                    type: number
                    format: double
                    description: CAF World Giving Index score (latest).
                cafDataYear:
                    type: integer
                    format: int32
                    description: Year of latest CAF data.
                candidGrantsTracked:
                    type: integer
                    format: int32
                    description: Number of foundation grants tracked (Candid).
                dataLag:
                    type: string
                    description: Data lag description (e.g., "Quarterly", "Annual").
            description: InstitutionalGiving tracks large-scale structured philanthropy and ODA.
        worldmonitor_health_v1_ListDiseaseOutbreaksRequest:
            type: object
        worldmonitor_health_v1_ListDiseaseOutbreaksResponse:
            type: object
            properties:
                outbreaks:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_health_v1_DiseaseOutbreakItem'
                fetchedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                alertLevelMethodologyVersion:
                    type: string
                    description: |-
                        Version of the editorial alert-level classifier (keyword sets, regexes,
                         promotion rules) used to label each item's alert_level. Bumping this
                         signals to downstream clients that the labelling rules changed so cached
                         comparisons across versions are no longer apples-to-apples. See
                         docs/methodology/disease-alert-level.mdx for the change protocol.
        worldmonitor_health_v1_DiseaseOutbreakItem:
            type: object
            properties:
                id:
                    type: string
                    description: Unique identifier (URL-derived).
                disease:
                    type: string
                    description: Disease or outbreak name.
                location:
                    type: string
                    description: Affected country or region.
                countryCode:
                    type: string
                    description: ISO2 country code when known.
                alertLevel:
                    type: string
                    description: 'Alert level: "watch" | "warning" | "alert".'
                summary:
                    type: string
                    description: Short description from the source.
                sourceUrl:
                    type: string
                    description: Source URL.
                publishedAt:
                    type: integer
                    format: int64
                    description: 'Unix epoch milliseconds when published.. Warning: Values > 2^53 may lose precision in JavaScript'
                sourceName:
                    type: string
                    description: Source name (e.g., "WHO", "ProMED", "HealthMap").
                lat:
                    type: number
                    format: double
                    description: Precise latitude from source (overrides country centroid on map when non-zero).
                lng:
                    type: number
                    format: double
                    description: Precise longitude from source (overrides country centroid on map when non-zero).
                cases:
                    type: integer
                    format: int32
                    description: Case count if reported by source (0 = unknown).
            description: DiseaseOutbreakItem represents a single disease outbreak event.
        worldmonitor_health_v1_ListAirQualityAlertsRequest:
            type: object
        worldmonitor_health_v1_ListAirQualityAlertsResponse:
            type: object
            properties:
                alerts:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_health_v1_AirQualityAlert'
                fetchedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
        worldmonitor_health_v1_AirQualityAlert:
            type: object
            properties:
                city:
                    type: string
                countryCode:
                    type: string
                lat:
                    type: number
                    format: double
                lng:
                    type: number
                    format: double
                pm25:
                    type: number
                    format: double
                aqi:
                    type: integer
                    format: int32
                riskLevel:
                    type: string
                pollutant:
                    type: string
                measuredAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                source:
                    type: string
        worldmonitor_imagery_v1_SearchImageryRequest:
            type: object
            properties:
                bbox:
                    type: string
                    description: Bounding box filter for imagery search, encoded as west,south,east,north.
                datetime:
                    type: string
                    description: ISO 8601 datetime or datetime range for matching imagery scenes.
                source:
                    type: string
                    description: Optional imagery source filter, such as satellite or provider name.
                limit:
                    type: integer
                    format: int32
                    description: Maximum number of imagery scenes to return.
        worldmonitor_imagery_v1_SearchImageryResponse:
            type: object
            properties:
                scenes:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_imagery_v1_ImageryScene'
                totalResults:
                    type: integer
                    format: int32
                cacheHit:
                    type: boolean
        worldmonitor_imagery_v1_ImageryScene:
            type: object
            properties:
                id:
                    type: string
                satellite:
                    type: string
                datetime:
                    type: string
                resolutionM:
                    type: number
                    format: double
                mode:
                    type: string
                geometryGeojson:
                    type: string
                previewUrl:
                    type: string
                assetUrl:
                    type: string
        worldmonitor_infrastructure_v1_ListInternetOutagesRequest:
            type: object
            properties:
                start:
                    type: integer
                    format: int64
                    description: 'Start of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                end:
                    type: integer
                    format: int64
                    description: 'End of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                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.
                country:
                    type: string
                    description: Optional country filter (ISO 3166-1 alpha-2).
            description: ListInternetOutagesRequest specifies filters for retrieving internet outages.
        worldmonitor_infrastructure_v1_ListInternetOutagesResponse:
            type: object
            properties:
                outages:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_infrastructure_v1_InternetOutage'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListInternetOutagesResponse contains internet outages matching the request.
        worldmonitor_infrastructure_v1_InternetOutage:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Unique outage identifier.
                title:
                    type: string
                    description: Outage title.
                link:
                    type: string
                    description: URL to the outage report.
                description:
                    type: string
                    description: Outage description.
                detectedAt:
                    type: integer
                    format: int64
                    description: 'Detection time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                country:
                    type: string
                    description: Affected country (ISO 3166-1 alpha-2).
                region:
                    type: string
                    description: Affected region within the country.
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                severity:
                    type: string
                    enum:
                        - OUTAGE_SEVERITY_UNSPECIFIED
                        - OUTAGE_SEVERITY_PARTIAL
                        - OUTAGE_SEVERITY_MAJOR
                        - OUTAGE_SEVERITY_TOTAL
                    description: |-
                        OutageSeverity represents the severity of an internet outage.
                         Maps to TS union: 'partial' | 'major' | 'total'.
                categories:
                    type: array
                    items:
                        type: string
                        description: Affected infrastructure categories.
                cause:
                    type: string
                    description: Root cause, if determined.
                outageType:
                    type: string
                    description: Outage type classification.
                endedAt:
                    type: integer
                    format: int64
                    description: 'End time of the outage, as Unix epoch milliseconds. Zero if ongoing.. Warning: Values > 2^53 may lose precision in JavaScript'
            required:
                - id
            description: InternetOutage represents a detected internet outage event from Cloudflare Radar.
        worldmonitor_infrastructure_v1_ListServiceStatusesRequest:
            type: object
            properties:
                status:
                    type: string
                    enum:
                        - SERVICE_OPERATIONAL_STATUS_UNSPECIFIED
                        - SERVICE_OPERATIONAL_STATUS_OPERATIONAL
                        - SERVICE_OPERATIONAL_STATUS_DEGRADED
                        - SERVICE_OPERATIONAL_STATUS_PARTIAL_OUTAGE
                        - SERVICE_OPERATIONAL_STATUS_MAJOR_OUTAGE
                        - SERVICE_OPERATIONAL_STATUS_MAINTENANCE
                    description: ServiceOperationalStatus represents the current status of a service.
            description: ListServiceStatusesRequest specifies filters for retrieving service statuses.
        worldmonitor_infrastructure_v1_ListServiceStatusesResponse:
            type: object
            properties:
                statuses:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_infrastructure_v1_ServiceStatus'
            description: ListServiceStatusesResponse contains service operational statuses.
        worldmonitor_infrastructure_v1_ServiceStatus:
            type: object
            properties:
                id:
                    type: string
                    description: Service identifier.
                name:
                    type: string
                    description: Service display name.
                status:
                    type: string
                    enum:
                        - SERVICE_OPERATIONAL_STATUS_UNSPECIFIED
                        - SERVICE_OPERATIONAL_STATUS_OPERATIONAL
                        - SERVICE_OPERATIONAL_STATUS_DEGRADED
                        - SERVICE_OPERATIONAL_STATUS_PARTIAL_OUTAGE
                        - SERVICE_OPERATIONAL_STATUS_MAJOR_OUTAGE
                        - SERVICE_OPERATIONAL_STATUS_MAINTENANCE
                    description: ServiceOperationalStatus represents the current status of a service.
                description:
                    type: string
                    description: Status description.
                url:
                    type: string
                    description: Service URL or homepage.
                checkedAt:
                    type: integer
                    format: int64
                    description: 'Last status check time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                latencyMs:
                    type: integer
                    format: int32
                    description: Response latency in milliseconds.
            description: ServiceStatus represents the operational status of a monitored external service.
        worldmonitor_infrastructure_v1_GetTemporalBaselineRequest:
            type: object
            properties:
                type:
                    type: string
                    minLength: 1
                    description: 'Activity type: "military_flights", "vessels", "protests", "news", "ais_gaps", "satellite_fires".'
                region:
                    type: string
                    description: Geographic region key, defaults to "global".
                count:
                    type: number
                    format: double
                    description: Current observed count to compare against baseline.
            required:
                - type
            description: GetTemporalBaselineRequest checks current activity count against stored baseline.
        worldmonitor_infrastructure_v1_GetTemporalBaselineResponse:
            type: object
            properties:
                anomaly:
                    $ref: '#/components/schemas/worldmonitor_infrastructure_v1_BaselineAnomaly'
                baseline:
                    $ref: '#/components/schemas/worldmonitor_infrastructure_v1_BaselineStats'
                learning:
                    type: boolean
                    description: True if insufficient samples have been collected.
                sampleCount:
                    type: integer
                    format: int32
                    description: Current number of samples stored.
                samplesNeeded:
                    type: integer
                    format: int32
                    description: Minimum samples required before anomaly detection activates.
                error:
                    type: string
                    description: Error message if request was invalid.
            description: GetTemporalBaselineResponse returns anomaly info or learning status.
        worldmonitor_infrastructure_v1_BaselineAnomaly:
            type: object
            properties:
                zScore:
                    type: number
                    format: double
                    description: Number of standard deviations from the mean.
                severity:
                    type: string
                    description: 'Severity label: "critical", "high", "medium", "normal".'
                multiplier:
                    type: number
                    format: double
                    description: Ratio of current count to baseline mean.
            description: BaselineAnomaly describes a detected deviation from historical baseline.
        worldmonitor_infrastructure_v1_BaselineStats:
            type: object
            properties:
                mean:
                    type: number
                    format: double
                    description: Running mean of observed counts.
                stdDev:
                    type: number
                    format: double
                    description: Standard deviation derived from Welford's M2.
                sampleCount:
                    type: integer
                    format: int32
                    description: Number of samples incorporated so far.
            description: BaselineStats contains the running statistics for a baseline key.
        worldmonitor_infrastructure_v1_GetIpGeoRequest:
            type: object
            description: GetIpGeoRequest defined for future parameters (e.g., specific IP).
        worldmonitor_infrastructure_v1_GetIpGeoResponse:
            type: object
            properties:
                country:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                region:
                    type: string
                    description: Region or city (if available).
                city:
                    type: string
            description: GetIpGeoResponse contains geographic information derived from the request IP.
        worldmonitor_infrastructure_v1_ReverseGeocodeRequest:
            type: object
            properties:
                lat:
                    type: number
                    format: double
                    description: Latitude of the point to reverse geocode.
                lon:
                    type: number
                    format: double
                    description: Longitude of the point to reverse geocode.
            description: ReverseGeocodeRequest parameters for coordinate-to-address lookups.
        worldmonitor_infrastructure_v1_ReverseGeocodeResponse:
            type: object
            properties:
                country:
                    type: string
                    description: Human-readable country name.
                code:
                    type: string
                    description: ISO country code.
                displayName:
                    type: string
                    description: Full display name/address.
                error:
                    type: string
                    description: Optional error message.
            description: ReverseGeocodeResponse containing the resolved location details.
        worldmonitor_infrastructure_v1_GetBootstrapDataRequest:
            type: object
            properties:
                tier:
                    type: string
                    description: Predefined tiers or specific keys.
                keys:
                    type: array
                    items:
                        type: string
                        description: Specific bootstrap cache keys to fetch when tier is not sufficient.
            description: GetBootstrapDataRequest parameters for multi-key fetching.
        worldmonitor_infrastructure_v1_GetBootstrapDataResponse:
            type: object
            properties:
                data:
                    type: object
                    additionalProperties:
                        type: string
                    description: Map of keys to JSON-encoded data strings.
                missing:
                    type: array
                    items:
                        type: string
                        description: List of keys that were not found in cache.
            description: GetBootstrapDataResponse containing pooled data objects.
        worldmonitor_infrastructure_v1_GetBootstrapDataResponse_DataEntry:
            type: object
            properties:
                key:
                    type: string
                value:
                    type: string
        worldmonitor_infrastructure_v1_RecordBaselineSnapshotRequest:
            type: object
            properties:
                updates:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_infrastructure_v1_BaselineUpdate'
            description: RecordBaselineSnapshotRequest batch-updates baselines using Welford's online algorithm.
        worldmonitor_infrastructure_v1_BaselineUpdate:
            type: object
            properties:
                type:
                    type: string
                    minLength: 1
                    description: Activity type key.
                region:
                    type: string
                    description: Geographic region key, defaults to "global".
                count:
                    type: number
                    format: double
                    description: Observed count value.
            required:
                - type
            description: BaselineUpdate is a single metric observation to incorporate into the running baseline.
        worldmonitor_infrastructure_v1_RecordBaselineSnapshotResponse:
            type: object
            properties:
                updated:
                    type: integer
                    format: int32
                    description: Number of baselines that were written.
                error:
                    type: string
                    description: Error message if the request was invalid.
            description: RecordBaselineSnapshotResponse reports how many baselines were successfully updated.
        worldmonitor_infrastructure_v1_GetCableHealthRequest:
            type: object
            description: GetCableHealthRequest requests the current health status of all monitored submarine cables.
        worldmonitor_infrastructure_v1_GetCableHealthResponse:
            type: object
            properties:
                generatedAt:
                    type: integer
                    format: int64
                    description: 'Generation timestamp, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                cables:
                    type: object
                    additionalProperties:
                        $ref: '#/components/schemas/worldmonitor_infrastructure_v1_CableHealthRecord'
                    description: Health records keyed by cable identifier.
            description: GetCableHealthResponse contains health status for submarine cables with active signals.
        worldmonitor_infrastructure_v1_GetCableHealthResponse_CablesEntry:
            type: object
            properties:
                key:
                    type: string
                value:
                    $ref: '#/components/schemas/worldmonitor_infrastructure_v1_CableHealthRecord'
        worldmonitor_infrastructure_v1_CableHealthRecord:
            type: object
            properties:
                status:
                    type: string
                    enum:
                        - CABLE_HEALTH_STATUS_UNSPECIFIED
                        - CABLE_HEALTH_STATUS_OK
                        - CABLE_HEALTH_STATUS_DEGRADED
                        - CABLE_HEALTH_STATUS_FAULT
                    description: CableHealthStatus represents the computed health status of a submarine cable.
                score:
                    type: number
                    format: double
                    description: Composite health score (0.0 = healthy, 1.0 = confirmed fault).
                confidence:
                    type: number
                    format: double
                    description: Confidence in the health assessment (0.0–1.0).
                lastUpdated:
                    type: integer
                    format: int64
                    description: 'Last signal update time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                evidence:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_infrastructure_v1_CableHealthEvidence'
            description: CableHealthRecord contains the computed health status and supporting evidence for a cable.
        worldmonitor_infrastructure_v1_CableHealthEvidence:
            type: object
            properties:
                source:
                    type: string
                    description: Evidence source (e.g. "NGA").
                summary:
                    type: string
                    description: Human-readable summary of the evidence.
                ts:
                    type: integer
                    format: int64
                    description: 'Evidence timestamp, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: CableHealthEvidence represents a single piece of evidence supporting a health assessment.
        worldmonitor_infrastructure_v1_ListTemporalAnomaliesRequest:
            type: object
        worldmonitor_infrastructure_v1_ListTemporalAnomaliesResponse:
            type: object
            properties:
                anomalies:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_infrastructure_v1_TemporalAnomaly'
                trackedTypes:
                    type: array
                    items:
                        type: string
                computedAt:
                    type: string
        worldmonitor_infrastructure_v1_TemporalAnomaly:
            type: object
            properties:
                type:
                    type: string
                region:
                    type: string
                currentCount:
                    type: integer
                    format: int32
                expectedCount:
                    type: integer
                    format: int32
                zScore:
                    type: number
                    format: double
                severity:
                    type: string
                multiplier:
                    type: number
                    format: double
                message:
                    type: string
        worldmonitor_infrastructure_v1_ListInternetDdosAttacksRequest:
            type: object
            description: ListInternetDdosAttacksRequest specifies filters for retrieving DDoS attack summaries.
        worldmonitor_infrastructure_v1_ListInternetDdosAttacksResponse:
            type: object
            properties:
                protocol:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_infrastructure_v1_DdosAttackSummaryEntry'
                vector:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_infrastructure_v1_DdosAttackSummaryEntry'
                dateRangeStart:
                    type: string
                    description: ISO 8601 start of the data window.
                dateRangeEnd:
                    type: string
                    description: ISO 8601 end of the data window.
                topTargetLocations:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_infrastructure_v1_DdosLocationHit'
            description: ListInternetDdosAttacksResponse contains DDoS attack protocol and vector breakdowns.
        worldmonitor_infrastructure_v1_DdosAttackSummaryEntry:
            type: object
            properties:
                label:
                    type: string
                    description: Protocol or vector name (e.g. "TCP", "UDP", "networkFlood").
                percentage:
                    type: number
                    format: float
                    description: Percentage share of total DDoS traffic (0–100).
            description: DdosAttackSummaryEntry represents a single protocol or vector and its share of DDoS traffic.
        worldmonitor_infrastructure_v1_DdosLocationHit:
            type: object
            properties:
                countryCode:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                countryName:
                    type: string
                    description: Country display name.
                percentage:
                    type: number
                    format: float
                    description: Percentage share of total DDoS traffic targeting this location (0-100).
                latitude:
                    type: number
                    format: float
                    description: Latitude of the target location.
                longitude:
                    type: number
                    format: float
                    description: Longitude of the target location.
            description: DdosLocationHit represents a top DDoS target location with geo coordinates.
        worldmonitor_infrastructure_v1_ListInternetTrafficAnomaliesRequest:
            type: object
            properties:
                country:
                    type: string
                    description: Optional ISO 3166-1 alpha-2 country code filter.
            description: ListInternetTrafficAnomaliesRequest specifies filters for traffic anomalies.
        worldmonitor_infrastructure_v1_ListInternetTrafficAnomaliesResponse:
            type: object
            properties:
                anomalies:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_infrastructure_v1_TrafficAnomaly'
                totalCount:
                    type: integer
                    format: int32
                    description: Total anomaly count before filtering.
            description: ListInternetTrafficAnomaliesResponse contains detected traffic anomalies.
        worldmonitor_infrastructure_v1_TrafficAnomaly:
            type: object
            properties:
                uuid:
                    type: string
                    description: Unique identifier for the anomaly.
                type:
                    type: string
                    description: Anomaly type (e.g. "ANOMALY_DNS", "ANOMALY_BGP").
                status:
                    type: string
                    description: Current status ("ONGOING" or "HISTORICAL").
                startDate:
                    type: integer
                    format: int64
                    description: 'Start of the anomaly, Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                endDate:
                    type: integer
                    format: int64
                    description: 'End of the anomaly, Unix epoch milliseconds. Zero if ongoing.. Warning: Values > 2^53 may lose precision in JavaScript'
                asn:
                    type: string
                    description: Autonomous System Number affected.
                asnName:
                    type: string
                    description: ASN display name.
                locationCode:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                locationName:
                    type: string
                    description: Country display name.
                latitude:
                    type: number
                    format: float
                    description: Latitude of the affected location.
                longitude:
                    type: number
                    format: float
                    description: Longitude of the affected location.
            description: TrafficAnomaly represents an anomalous traffic pattern detected by Cloudflare Radar.
        worldmonitor_intelligence_v1_GetRiskScoresRequest:
            type: object
            properties:
                region:
                    type: string
                    description: Optional region filter. Empty returns all tracked regions.
            description: GetRiskScoresRequest specifies parameters for retrieving risk scores.
        worldmonitor_intelligence_v1_GetRiskScoresResponse:
            type: object
            properties:
                ciiScores:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_CiiScore'
                strategicRisks:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_StrategicRisk'
                degraded:
                    type: boolean
                    description: |-
                        True when upstream scoring inputs failed and the response is served from
                         a stale cache or from the baseline-only cold fallback.
                stale:
                    type: boolean
                    description: |-
                        True when degraded=true because a stale cached score payload was served.
                         Baseline-only cold fallback sets degraded=true and stale=false.
            description: GetRiskScoresResponse contains composite risk scores and strategic assessments.
        worldmonitor_intelligence_v1_CiiScore:
            type: object
            properties:
                region:
                    type: string
                    description: Region or country identifier.
                staticBaseline:
                    type: number
                    maximum: 100
                    minimum: 0
                    format: double
                    description: Static baseline score (0-100).
                dynamicScore:
                    type: number
                    maximum: 100
                    minimum: -100
                    format: double
                    description: |-
                        Approximate 24-hour score movement delta (-100 to 100). Positive means rising,
                         negative means falling, and 0 means stable or no valid prior snapshot.
                combinedScore:
                    type: number
                    maximum: 100
                    minimum: 0
                    format: double
                    description: Combined weighted score (0-100).
                trend:
                    type: string
                    enum:
                        - TREND_DIRECTION_UNSPECIFIED
                        - TREND_DIRECTION_RISING
                        - TREND_DIRECTION_STABLE
                        - TREND_DIRECTION_FALLING
                    description: |-
                        TrendDirection represents the directional movement of a metric over time.
                         Used in markets, GDELT tension scores, and risk assessments.
                components:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_CiiComponents'
                computedAt:
                    type: integer
                    format: int64
                    description: 'Last computation time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                methodologyVersion:
                    type: string
                    description: |-
                        Methodology version string for this score (for example, the current CII formula version).
                         Bumped whenever CII_FORMULA_VERSION changes so API clients can detect
                         score or movement-semantics drift. See docs/methodology/cii-risk-scores.mdx.
                eventMultiplier:
                    type: number
                    maximum: 10
                    minimum: 0
                    format: double
                    description: |-
                        Editorial per-country event multiplier applied to live signals before
                         they roll into the composite score. Published for transparency — issue
                         #3725. See docs/methodology/cii-risk-scores.mdx.

                         Bounds: [0, 10]. The editorial de-facto maximum across the published
                         table is ~3.0 (KP). The upper bound of 10 gives ~3.3x headroom for
                         future weight changes while still catching obviously-wrong inputs (e.g.
                         a runaway computation producing 1e6 or NaN-coerced values). Added in
                         PR #3780 review.
                advisoryLevel:
                    type: string
                    description: |-
                        Travel advisory level used by the score, when any advisory input applies.
                         Empty means no live or fallback advisory level affected boosts/floors.
                advisoryProvenance:
                    type: string
                    pattern: ^(live|fallback|absent)$
                    description: |-
                        Provenance for advisory_level: "live" when sourced from the Redis advisory
                         feed, "fallback" when using the embedded State Department fallback table,
                         and "absent" when no advisory input affected this score.
            description: CiiScore represents a Composite Instability Index score for a region or country.
        worldmonitor_intelligence_v1_CiiComponents:
            type: object
            properties:
                newsActivity:
                    type: number
                    maximum: 100
                    minimum: 0
                    format: double
                    description: Information-environment contribution from news urgency and threat-summary signals (0-100).
                ciiContribution:
                    type: number
                    maximum: 100
                    minimum: 0
                    format: double
                    description: Domestic unrest contribution from protests, riots, fatalities, severity, and outages (0-100).
                geoConvergence:
                    type: number
                    maximum: 100
                    minimum: 0
                    format: double
                    description: Armed-conflict contribution from ACLED events, fatalities, civilian violence, strikes, and OREF alerts (0-100).
                militaryActivity:
                    type: number
                    maximum: 100
                    minimum: 0
                    format: double
                    description: Security-mobility contribution from military flights, military vessels, aviation disruption, and GPS interference (0-100).
            description: CiiComponents represents the contributing factors to a CII score.
        worldmonitor_intelligence_v1_StrategicRisk:
            type: object
            properties:
                region:
                    type: string
                    description: Country or region identifier.
                level:
                    type: string
                    enum:
                        - SEVERITY_LEVEL_UNSPECIFIED
                        - SEVERITY_LEVEL_LOW
                        - SEVERITY_LEVEL_MEDIUM
                        - SEVERITY_LEVEL_HIGH
                    description: |-
                        SeverityLevel represents a three-tier severity classification used across domains.
                         Maps to existing TS unions: 'low' | 'medium' | 'high'.
                score:
                    type: number
                    maximum: 100
                    minimum: 0
                    format: double
                    description: Risk score (0-100).
                factors:
                    type: array
                    items:
                        type: string
                        description: Risk factors contributing to the assessment.
                trend:
                    type: string
                    enum:
                        - TREND_DIRECTION_UNSPECIFIED
                        - TREND_DIRECTION_RISING
                        - TREND_DIRECTION_STABLE
                        - TREND_DIRECTION_FALLING
                    description: |-
                        TrendDirection represents the directional movement of a metric over time.
                         Used in markets, GDELT tension scores, and risk assessments.
            description: StrategicRisk represents a strategic risk assessment for a country or region.
        worldmonitor_intelligence_v1_GetPizzintStatusRequest:
            type: object
            properties:
                includeGdelt:
                    type: boolean
                    description: Whether to include GDELT tension pairs in the response.
            description: GetPizzintStatusRequest specifies parameters for retrieving PizzINT and GDELT data.
        worldmonitor_intelligence_v1_GetPizzintStatusResponse:
            type: object
            properties:
                pizzint:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_PizzintStatus'
                tensionPairs:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_GdeltTensionPair'
            description: GetPizzintStatusResponse contains Pentagon Pizza Index and GDELT tension data.
        worldmonitor_intelligence_v1_PizzintStatus:
            type: object
            properties:
                defconLevel:
                    type: integer
                    maximum: 5
                    minimum: 1
                    format: int32
                    description: DEFCON-style level (1-5).
                defconLabel:
                    type: string
                    description: Human-readable DEFCON label.
                aggregateActivity:
                    type: number
                    format: double
                    description: Aggregate activity score.
                activeSpikes:
                    type: integer
                    format: int32
                    description: Number of active spike locations.
                locationsMonitored:
                    type: integer
                    format: int32
                    description: Total monitored locations.
                locationsOpen:
                    type: integer
                    format: int32
                    description: Currently open locations.
                updatedAt:
                    type: integer
                    format: int64
                    description: 'Last data update time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                dataFreshness:
                    type: string
                    enum:
                        - DATA_FRESHNESS_UNSPECIFIED
                        - DATA_FRESHNESS_FRESH
                        - DATA_FRESHNESS_STALE
                    description: DataFreshness represents how current the data is.
                locations:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_PizzintLocation'
            description: PizzintStatus represents the Pentagon Pizza Index status (proxy for late-night DC activity).
        worldmonitor_intelligence_v1_PizzintLocation:
            type: object
            properties:
                placeId:
                    type: string
                    description: Google Places ID.
                name:
                    type: string
                    description: Location name.
                address:
                    type: string
                    description: Street address.
                currentPopularity:
                    type: integer
                    format: int32
                    description: Current popularity score (0-200+).
                percentageOfUsual:
                    type: integer
                    format: int32
                    description: Percentage of usual activity. Zero if unavailable.
                isSpike:
                    type: boolean
                    description: Whether activity constitutes a spike.
                spikeMagnitude:
                    type: number
                    format: double
                    description: Spike magnitude above baseline. Zero if no spike.
                dataSource:
                    type: string
                    description: Data source identifier.
                recordedAt:
                    type: string
                    description: Recording timestamp as ISO 8601 string.
                dataFreshness:
                    type: string
                    enum:
                        - DATA_FRESHNESS_UNSPECIFIED
                        - DATA_FRESHNESS_FRESH
                        - DATA_FRESHNESS_STALE
                    description: DataFreshness represents how current the data is.
                isClosedNow:
                    type: boolean
                    description: Whether the location is currently closed.
                lat:
                    type: number
                    format: double
                    description: Latitude of the location.
                lng:
                    type: number
                    format: double
                    description: Longitude of the location.
            description: PizzintLocation represents a single monitored pizza location near the Pentagon.
        worldmonitor_intelligence_v1_GdeltTensionPair:
            type: object
            properties:
                id:
                    type: string
                    description: Pair identifier.
                countries:
                    type: array
                    items:
                        type: string
                        description: Country pair (ISO 3166-1 alpha-2 codes).
                label:
                    type: string
                    description: Human-readable label (e.g., "US-China").
                score:
                    type: number
                    maximum: 100
                    minimum: 0
                    format: double
                    description: Tension score (0-100).
                trend:
                    type: string
                    enum:
                        - TREND_DIRECTION_UNSPECIFIED
                        - TREND_DIRECTION_RISING
                        - TREND_DIRECTION_STABLE
                        - TREND_DIRECTION_FALLING
                    description: |-
                        TrendDirection represents the directional movement of a metric over time.
                         Used in markets, GDELT tension scores, and risk assessments.
                changePercent:
                    type: number
                    format: double
                    description: Percentage change from previous period.
                region:
                    type: string
                    description: Geographic region.
            description: GdeltTensionPair represents a bilateral tension score between two countries from GDELT.
        worldmonitor_intelligence_v1_ClassifyEventRequest:
            type: object
            properties:
                title:
                    type: string
                    minLength: 1
                    description: Event title or headline.
                description:
                    type: string
                    description: Event description or body text.
                source:
                    type: string
                    description: Event source (e.g., "reuters", "acled").
                country:
                    type: string
                    description: Country context (ISO 3166-1 alpha-2).
            required:
                - title
            description: ClassifyEventRequest specifies an event to classify using AI.
        worldmonitor_intelligence_v1_ClassifyEventResponse:
            type: object
            properties:
                classification:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_EventClassification'
            description: ClassifyEventResponse contains the AI-generated event classification.
        worldmonitor_intelligence_v1_EventClassification:
            type: object
            properties:
                category:
                    type: string
                    description: Event category (e.g., "military", "economic", "social").
                subcategory:
                    type: string
                    description: Event subcategory.
                severity:
                    type: string
                    enum:
                        - SEVERITY_LEVEL_UNSPECIFIED
                        - SEVERITY_LEVEL_LOW
                        - SEVERITY_LEVEL_MEDIUM
                        - SEVERITY_LEVEL_HIGH
                    description: |-
                        SeverityLevel represents a three-tier severity classification used across domains.
                         Maps to existing TS unions: 'low' | 'medium' | 'high'.
                confidence:
                    type: number
                    maximum: 1
                    minimum: 0
                    format: double
                    description: Classification confidence (0.0 to 1.0).
                analysis:
                    type: string
                    description: Brief AI-generated analysis.
                entities:
                    type: array
                    items:
                        type: string
                        description: Related entities identified.
            description: EventClassification represents an AI-generated classification of a real-world event.
        worldmonitor_intelligence_v1_GetCountryRiskRequest:
            type: object
            properties:
                countryCode:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 country code.
            required:
                - countryCode
            description: GetCountryRiskRequest specifies which country to retrieve risk intelligence for.
        worldmonitor_intelligence_v1_GetCountryRiskResponse:
            type: object
            properties:
                countryCode:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                countryName:
                    type: string
                    description: Country name.
                cii:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_CiiScore'
                advisoryLevel:
                    type: string
                    description: Travel advisory level from government sources (e.g. "do-not-travel", "reconsider", "caution"). Empty if none.
                sanctionsActive:
                    type: boolean
                    description: Whether this country has active OFAC sanctions designations.
                sanctionsCount:
                    type: integer
                    format: int32
                    description: Count of sanctioned entities associated with this country.
                fetchedAt:
                    type: integer
                    format: int64
                    description: |-
                        Data freshness timestamp derived from CII computedAt, as Unix epoch milliseconds.
                         0 means the CII computation time is unknown, including no CII score for this country. Warning: Values > 2^53 may lose precision in JavaScript
                upstreamUnavailable:
                    type: boolean
                    description: True when all upstream Redis keys were unavailable. Signals CDN cache bypass.
            description: GetCountryRiskResponse contains composite risk intelligence for a specific country.
        worldmonitor_intelligence_v1_GetCountryIntelBriefRequest:
            type: object
            properties:
                countryCode:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 country code.
                framework:
                    type: string
                    description: Optional analytical framework instructions to append to system prompt. Max 2000 chars enforced at handler level.
            required:
                - countryCode
            description: GetCountryIntelBriefRequest specifies which country to generate a brief for.
        worldmonitor_intelligence_v1_GetCountryIntelBriefResponse:
            type: object
            properties:
                countryCode:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                countryName:
                    type: string
                    description: Country name.
                brief:
                    type: string
                    description: AI-generated intelligence brief text.
                model:
                    type: string
                    description: AI model used for generation.
                generatedAt:
                    type: integer
                    format: int64
                    description: 'Brief generation time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                sources:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_BriefSource'
            description: GetCountryIntelBriefResponse contains an AI-generated intelligence brief for a country.
        worldmonitor_intelligence_v1_BriefSource:
            type: object
            properties:
                title:
                    type: string
                    description: Source article headline.
                source:
                    type: string
                    description: Source outlet or feed label.
                url:
                    type: string
                    description: Absolute http(s) source article URL.
                publishedAt:
                    type: string
                    description: Article publication time, when available.
            description: BriefSource describes one article used to ground an AI-generated brief.
        worldmonitor_intelligence_v1_SearchGdeltDocumentsRequest:
            type: object
            properties:
                query:
                    type: string
                    minLength: 1
                    description: Search query string.
                maxRecords:
                    type: integer
                    maximum: 250
                    minimum: 1
                    format: int32
                    description: |-
                        Maximum number of articles to return. Defaults to 10 when omitted or <= 0. The
                         handler caps returned results at 20, so values above 20 (though accepted, up to the
                         validation limit of 250) still return at most 20 articles.
                timespan:
                    type: string
                    description: |-
                        Time span filter (e.g., "15min", "1h", "24h").
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                toneFilter:
                    type: string
                    description: |-
                        Tone filter appended to query (e.g., "tone>5" for positive, "tone<-5" for negative).
                         Left empty to skip tone filtering.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                sort:
                    type: string
                    description: |-
                        Sort mode: "DateDesc" (default), "ToneDesc", "ToneAsc", "HybridRel".
                         Accepted but currently ignored; no-op until this handler supports the parameter.
            required:
                - query
            description: SearchGdeltDocumentsRequest specifies filters for searching GDELT news articles.
        worldmonitor_intelligence_v1_SearchGdeltDocumentsResponse:
            type: object
            properties:
                articles:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_GdeltArticle'
                query:
                    type: string
                    description: Echo of the search query.
                error:
                    type: string
                    description: Error message if the search failed.
            description: SearchGdeltDocumentsResponse contains GDELT article search results.
        worldmonitor_intelligence_v1_GdeltArticle:
            type: object
            properties:
                title:
                    type: string
                    description: Article headline.
                url:
                    type: string
                    description: Article URL.
                source:
                    type: string
                    description: Source domain name.
                date:
                    type: string
                    description: Publication date string.
                image:
                    type: string
                    description: Article image URL.
                language:
                    type: string
                    description: Article language code.
                tone:
                    type: number
                    format: double
                    description: GDELT tone score (negative = negative tone, positive = positive tone).
            description: GdeltArticle represents a single article from the GDELT document API.
        worldmonitor_intelligence_v1_DeductSituationRequest:
            type: object
            properties:
                query:
                    type: string
                geoContext:
                    type: string
                framework:
                    type: string
                    description: Optional analytical framework instructions.
        worldmonitor_intelligence_v1_DeductSituationResponse:
            type: object
            properties:
                analysis:
                    type: string
                model:
                    type: string
                provider:
                    type: string
        worldmonitor_intelligence_v1_ListSatellitesRequest:
            type: object
            properties:
                country:
                    type: string
                    description: Filter by country code. Empty returns all.
            description: ListSatellitesRequest specifies filters for orbital data.
        worldmonitor_intelligence_v1_ListSatellitesResponse:
            type: object
            properties:
                satellites:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_Satellite'
            description: ListSatellitesResponse contains the current orbital snapshot.
        worldmonitor_intelligence_v1_Satellite:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: NORAD identifier (e.g., "25544").
                name:
                    type: string
                    description: Name of the satellite.
                country:
                    type: string
                    description: ISO country code of the operator/owner.
                type:
                    type: string
                    description: Purpose category (e.g., "sar", "optical", "military").
                alt:
                    type: number
                    format: double
                    description: Orbital altitude in kilometers.
                velocity:
                    type: number
                    format: double
                    description: Velocity in km/s.
                inclination:
                    type: number
                    format: double
                    description: Orbital inclination in degrees.
                line1:
                    type: string
                    description: TLE line 1.
                line2:
                    type: string
                    description: TLE line 2.
            required:
                - id
            description: Satellite represents an orbital asset tracked by WorldMonitor.
        worldmonitor_intelligence_v1_ListGpsInterferenceRequest:
            type: object
            properties:
                region:
                    type: string
                    description: Optional region filter.
            description: ListGpsInterferenceRequest specifies filters for GPS interference data.
        worldmonitor_intelligence_v1_ListGpsInterferenceResponse:
            type: object
            properties:
                hexes:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_GpsJamHex'
                stats:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_GpsJamStats'
                source:
                    type: string
                    description: Data source name.
                fetchedAt:
                    type: integer
                    format: int64
                    description: 'Data fetch time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: ListGpsInterferenceResponse contains GPS interference data and stats.
        worldmonitor_intelligence_v1_GpsJamHex:
            type: object
            properties:
                h3:
                    type: string
                    minLength: 1
                    description: H3 index of the hexagon.
                lat:
                    type: number
                    format: double
                    description: Centroid latitude.
                lon:
                    type: number
                    format: double
                    description: Centroid longitude.
                level:
                    type: string
                    enum:
                        - INTERFERENCE_LEVEL_UNSPECIFIED
                        - INTERFERENCE_LEVEL_LOW
                        - INTERFERENCE_LEVEL_MEDIUM
                        - INTERFERENCE_LEVEL_HIGH
                    description: InterferenceLevel represents the severity of detected signal interference.
                npAvg:
                    type: number
                    format: double
                    description: Average Navigation Precision (np) - lower means more interference.
                sampleCount:
                    type: integer
                    format: int32
                    description: Number of samples in this hex.
                aircraftCount:
                    type: integer
                    format: int32
                    description: Number of unique aircraft that reported in this hex.
            required:
                - h3
            description: GpsJamHex represents a geographic hexagon with detected GPS interference.
        worldmonitor_intelligence_v1_GpsJamStats:
            type: object
            properties:
                totalHexes:
                    type: integer
                    format: int32
                highCount:
                    type: integer
                    format: int32
                mediumCount:
                    type: integer
                    format: int32
            description: GpsJamStats contains aggregate statistics for GPS interference.
        worldmonitor_intelligence_v1_ListOrefAlertsRequest:
            type: object
            properties:
                mode:
                    type: string
                    enum:
                        - MODE_UNSPECIFIED
                        - MODE_HISTORY
            description: Request to fetch Israeli Red Alerts (OREF).
        worldmonitor_intelligence_v1_ListOrefAlertsResponse:
            type: object
            properties:
                configured:
                    type: boolean
                    description: Whether the OREF bridge is configured.
                alerts:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_OrefAlert'
                history:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_OrefWave'
                historyCount24h:
                    type: integer
                    format: int32
                    description: Number of alerts in the last 24 hours.
                totalHistoryCount:
                    type: integer
                    format: int32
                    description: Total alerts in the historical buffer.
                timestampMs:
                    type: integer
                    format: int64
                    description: 'Unix timestamp in milliseconds of the response generation.. Warning: Values > 2^53 may lose precision in JavaScript'
                error:
                    type: string
                    description: Optional error message from the relay.
            description: OREF alert wave snapshot.
        worldmonitor_intelligence_v1_OrefAlert:
            type: object
            properties:
                id:
                    type: string
                cat:
                    type: string
                title:
                    type: string
                data:
                    type: array
                    items:
                        type: string
                desc:
                    type: string
                timestampMs:
                    type: integer
                    format: int64
                    description: 'Unix timestamp in milliseconds for when the alert was issued.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: A single Red Alert event.
        worldmonitor_intelligence_v1_OrefWave:
            type: object
            properties:
                alerts:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_OrefAlert'
                timestampMs:
                    type: integer
                    format: int64
                    description: 'Unix timestamp in milliseconds for this wave.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: A wave of alerts occurring at the same time.
        worldmonitor_intelligence_v1_ListTelegramFeedRequest:
            type: object
            properties:
                limit:
                    type: integer
                    format: int32
                    description: Maximum number of messages to return (default 50).
                topic:
                    type: string
                    description: Filter by topic keyword (e.g. "military", "cyber").
                channel:
                    type: string
                    description: Filter by specific channel ID or name.
            description: Request to fetch real-time Telegram OSINT feed.
        worldmonitor_intelligence_v1_ListTelegramFeedResponse:
            type: object
            properties:
                enabled:
                    type: boolean
                    description: Whether the bridge is currently active.
                messages:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_TelegramMessage'
                count:
                    type: integer
                    format: int32
                    description: Total count of messages in the current window.
                error:
                    type: string
                    description: Detailed error message if the fetch failed.
            description: OSINT feed containing validated Telegram messages.
        worldmonitor_intelligence_v1_TelegramMessage:
            type: object
            properties:
                id:
                    type: string
                    description: Unique message identifier.
                channelId:
                    type: string
                    description: Identifier of the originating channel.
                channelName:
                    type: string
                    description: Human-readable name of the channel.
                text:
                    type: string
                    description: Sanitized message content.
                timestampMs:
                    type: integer
                    format: int64
                    description: 'Unix timestamp in milliseconds for when the message was posted.. Warning: Values > 2^53 may lose precision in JavaScript'
                mediaUrls:
                    type: array
                    items:
                        type: string
                        description: Direct links to associated media (images, videos).
                sourceUrl:
                    type: string
                    description: Link to the original post on Telegram.
                topic:
                    type: string
                    description: Auto-classified topic based on content.
            description: Validated OSINT post from Telegram channels.
        worldmonitor_intelligence_v1_GetCompanyEnrichmentRequest:
            type: object
            properties:
                domain:
                    type: string
                    description: Company domain to enrich, such as "github.com".
                name:
                    type: string
                    description: Company name to enrich when a domain is not available.
            description: |-
                Request to fetch enrichment data for a company.
                 NOTE: This endpoint is DISABLED — the handler returns an empty stub regardless of
                 input. Requires either domain (e.g. "github.com") or name (e.g. "GitHub") to pass
                 validation, but no enrichment is performed.
        worldmonitor_intelligence_v1_GetCompanyEnrichmentResponse:
            type: object
            properties:
                company:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_EnrichedCompany'
                github:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_EnrichedGithub'
                techStack:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_TechStackItem'
                secFilings:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_SecFilings'
                hackerNewsMentions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_HNMention'
                enrichedAtMs:
                    type: integer
                    format: int64
                    description: 'Unix timestamp in milliseconds when this data was fetched.. Warning: Values > 2^53 may lose precision in JavaScript'
                sources:
                    type: array
                    items:
                        type: string
                        description: List of sources successfully reached (e.g. "github", "sec_edgar").
            description: |-
                Company enrichment data. DISABLED: the handler returns an empty stub — `company`
                 echoes only the requested name/domain, and all other fields are empty/undefined.
        worldmonitor_intelligence_v1_EnrichedCompany:
            type: object
            properties:
                name:
                    type: string
                domain:
                    type: string
                description:
                    type: string
                location:
                    type: string
                website:
                    type: string
                founded:
                    type: integer
                    format: int32
        worldmonitor_intelligence_v1_EnrichedGithub:
            type: object
            properties:
                publicRepos:
                    type: integer
                    format: int32
                followers:
                    type: integer
                    format: int32
                avatarUrl:
                    type: string
        worldmonitor_intelligence_v1_TechStackItem:
            type: object
            properties:
                name:
                    type: string
                category:
                    type: string
                confidence:
                    type: number
                    format: float
        worldmonitor_intelligence_v1_SecFilings:
            type: object
            properties:
                totalFilings:
                    type: integer
                    format: int32
                recentFilings:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_SecFiling'
        worldmonitor_intelligence_v1_SecFiling:
            type: object
            properties:
                form:
                    type: string
                fileDate:
                    type: string
                description:
                    type: string
        worldmonitor_intelligence_v1_HNMention:
            type: object
            properties:
                title:
                    type: string
                url:
                    type: string
                points:
                    type: integer
                    format: int32
                comments:
                    type: integer
                    format: int32
                createdAtMs:
                    type: integer
                    format: int64
                    description: 'Unix timestamp in milliseconds when the post was created.. Warning: Values > 2^53 may lose precision in JavaScript'
        worldmonitor_intelligence_v1_ListCompanySignalsRequest:
            type: object
            properties:
                company:
                    type: string
                    description: Company name to discover signals for.
                domain:
                    type: string
                    description: Company domain to discover signals for.
            description: |-
                Request to discover and classify company signals (hiring, funding, tech changes).
                 NOTE: This endpoint is DISABLED — the handler returns an empty stub regardless of
                 input. `company` is still required to pass validation, but no signals are discovered.
        worldmonitor_intelligence_v1_ListCompanySignalsResponse:
            type: object
            properties:
                company:
                    type: string
                domain:
                    type: string
                signals:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_CompanySignal'
                summary:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_SignalSummary'
                discoveredAtMs:
                    type: integer
                    format: int64
                    description: 'Unix timestamp in milliseconds when signals were discovered.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: |-
                Discovered company signals with classification and engagement metrics.
                 DISABLED: the handler returns an empty stub — `signals` is always empty and `summary`
                 reports zero counts; only the echoed `company`/`domain` are populated.
        worldmonitor_intelligence_v1_CompanySignal:
            type: object
            properties:
                type:
                    type: string
                    description: Classification type (e.g. "Hiring", "Product Launch", "Expansion").
                title:
                    type: string
                url:
                    type: string
                source:
                    type: string
                sourceTier:
                    type: integer
                    format: int32
                    description: Data quality tier (1 is authoritative, 5 is low confidence).
                timestampMs:
                    type: integer
                    format: int64
                    description: 'Unix timestamp in milliseconds of the event occurrence.. Warning: Values > 2^53 may lose precision in JavaScript'
                strength:
                    type: string
                    description: Qualitative strength of the signal (e.g. "Strong", "Emerging").
                engagement:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_SignalEngagement'
        worldmonitor_intelligence_v1_SignalEngagement:
            type: object
            properties:
                points:
                    type: integer
                    format: int32
                comments:
                    type: integer
                    format: int32
                stars:
                    type: integer
                    format: int32
                forks:
                    type: integer
                    format: int32
                mentions:
                    type: integer
                    format: int32
        worldmonitor_intelligence_v1_SignalSummary:
            type: object
            properties:
                totalSignals:
                    type: integer
                    format: int32
                byType:
                    type: object
                    additionalProperties:
                        type: integer
                        format: int32
                strongestSignal:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_CompanySignal'
                signalDiversity:
                    type: integer
                    format: int32
        worldmonitor_intelligence_v1_SignalSummary_ByTypeEntry:
            type: object
            properties:
                key:
                    type: string
                value:
                    type: integer
                    format: int32
        worldmonitor_intelligence_v1_GetCountryFactsRequest:
            type: object
            properties:
                countryCode:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 country code for the facts lookup.
            required:
                - countryCode
        worldmonitor_intelligence_v1_GetCountryFactsResponse:
            type: object
            properties:
                headOfState:
                    type: string
                headOfStateTitle:
                    type: string
                wikipediaSummary:
                    type: string
                wikipediaThumbnailUrl:
                    type: string
                population:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                capital:
                    type: string
                languages:
                    type: array
                    items:
                        type: string
                currencies:
                    type: array
                    items:
                        type: string
                areaSqKm:
                    type: number
                    format: double
                countryName:
                    type: string
        worldmonitor_intelligence_v1_ListSecurityAdvisoriesRequest:
            type: object
        worldmonitor_intelligence_v1_ListSecurityAdvisoriesResponse:
            type: object
            properties:
                advisories:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_SecurityAdvisoryItem'
                byCountry:
                    type: object
                    additionalProperties:
                        type: string
        worldmonitor_intelligence_v1_ListSecurityAdvisoriesResponse_ByCountryEntry:
            type: object
            properties:
                key:
                    type: string
                value:
                    type: string
        worldmonitor_intelligence_v1_SecurityAdvisoryItem:
            type: object
            properties:
                title:
                    type: string
                link:
                    type: string
                pubDate:
                    type: string
                source:
                    type: string
                sourceCountry:
                    type: string
                level:
                    type: string
                country:
                    type: string
        worldmonitor_intelligence_v1_GetGdeltTopicTimelineRequest:
            type: object
            properties:
                topic:
                    type: string
                    description: Topic ID (military, cyber, nuclear, sanctions, intelligence, maritime).
            description: GetGdeltTopicTimelineRequest retrieves tone and volume timelines for a GDELT intel topic.
        worldmonitor_intelligence_v1_GetGdeltTopicTimelineResponse:
            type: object
            properties:
                topic:
                    type: string
                    description: Topic ID.
                tone:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_GdeltTimelinePoint'
                vol:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_GdeltTimelinePoint'
                fetchedAt:
                    type: string
                    description: ISO timestamp when this data was fetched.
                error:
                    type: string
                    description: Error message if fetch failed.
            description: GetGdeltTopicTimelineResponse contains tone and volume timelines for a topic.
        worldmonitor_intelligence_v1_GdeltTimelinePoint:
            type: object
            properties:
                date:
                    type: string
                    description: Date string from GDELT (e.g. "20240101T000000").
                value:
                    type: number
                    format: double
                    description: Tone or volume value at this point.
            description: GdeltTimelinePoint is a single data point in a tone or volume timeline.
        worldmonitor_intelligence_v1_ListCrossSourceSignalsRequest:
            type: object
            description: ListCrossSourceSignalsRequest has no required parameters (returns all signals).
        worldmonitor_intelligence_v1_ListCrossSourceSignalsResponse:
            type: object
            properties:
                signals:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_CrossSourceSignal'
                evaluatedAt:
                    type: integer
                    format: int64
                    description: 'Timestamp when the aggregator last ran (Unix epoch milliseconds).. Warning: Values > 2^53 may lose precision in JavaScript'
                compositeCount:
                    type: integer
                    format: int32
                    description: Total number of composite escalation zones detected.
            description: ListCrossSourceSignalsResponse contains ranked cross-domain signals.
        worldmonitor_intelligence_v1_CrossSourceSignal:
            type: object
            properties:
                id:
                    type: string
                    description: Unique signal identifier.
                type:
                    type: string
                    enum:
                        - CROSS_SOURCE_SIGNAL_TYPE_UNSPECIFIED
                        - CROSS_SOURCE_SIGNAL_TYPE_COMPOSITE_ESCALATION
                        - CROSS_SOURCE_SIGNAL_TYPE_THERMAL_SPIKE
                        - CROSS_SOURCE_SIGNAL_TYPE_GPS_JAMMING
                        - CROSS_SOURCE_SIGNAL_TYPE_MILITARY_FLIGHT_SURGE
                        - CROSS_SOURCE_SIGNAL_TYPE_UNREST_SURGE
                        - CROSS_SOURCE_SIGNAL_TYPE_OREF_ALERT_CLUSTER
                        - CROSS_SOURCE_SIGNAL_TYPE_VIX_SPIKE
                        - CROSS_SOURCE_SIGNAL_TYPE_COMMODITY_SHOCK
                        - CROSS_SOURCE_SIGNAL_TYPE_CYBER_ESCALATION
                        - CROSS_SOURCE_SIGNAL_TYPE_SHIPPING_DISRUPTION
                        - CROSS_SOURCE_SIGNAL_TYPE_SANCTIONS_SURGE
                        - CROSS_SOURCE_SIGNAL_TYPE_EARTHQUAKE_SIGNIFICANT
                        - CROSS_SOURCE_SIGNAL_TYPE_RADIATION_ANOMALY
                        - CROSS_SOURCE_SIGNAL_TYPE_INFRASTRUCTURE_OUTAGE
                        - CROSS_SOURCE_SIGNAL_TYPE_WILDFIRE_ESCALATION
                        - CROSS_SOURCE_SIGNAL_TYPE_DISPLACEMENT_SURGE
                        - CROSS_SOURCE_SIGNAL_TYPE_FORECAST_DETERIORATION
                        - CROSS_SOURCE_SIGNAL_TYPE_MARKET_STRESS
                        - CROSS_SOURCE_SIGNAL_TYPE_WEATHER_EXTREME
                        - CROSS_SOURCE_SIGNAL_TYPE_MEDIA_TONE_DETERIORATION
                        - CROSS_SOURCE_SIGNAL_TYPE_RISK_SCORE_SPIKE
                    description: CrossSourceSignalType enumerates all monitored cross-domain signal categories.
                theater:
                    type: string
                    description: Theater / geographic context (e.g. "Eastern Europe", "Red Sea", "Global Markets").
                summary:
                    type: string
                    description: Human-readable summary of the signal.
                severity:
                    type: string
                    enum:
                        - CROSS_SOURCE_SIGNAL_SEVERITY_UNSPECIFIED
                        - CROSS_SOURCE_SIGNAL_SEVERITY_LOW
                        - CROSS_SOURCE_SIGNAL_SEVERITY_MEDIUM
                        - CROSS_SOURCE_SIGNAL_SEVERITY_HIGH
                        - CROSS_SOURCE_SIGNAL_SEVERITY_CRITICAL
                    description: CrossSourceSignalSeverity indicates the urgency tier of a detected signal.
                severityScore:
                    type: number
                    format: double
                    description: 'Raw severity score used for ranking (higher = more severe).. Warning: Values > 2^53 may lose precision in JavaScript'
                detectedAt:
                    type: integer
                    format: int64
                    description: 'Detection timestamp (Unix epoch milliseconds).. Warning: Values > 2^53 may lose precision in JavaScript'
                contributingTypes:
                    type: array
                    items:
                        type: string
                        description: 'For COMPOSITE_ESCALATION: list of contributing signal type names.'
                signalCount:
                    type: integer
                    format: int32
                    description: 'For COMPOSITE_ESCALATION: number of co-firing signals in theater.'
            description: CrossSourceSignal represents a single detected cross-domain signal event.
        worldmonitor_intelligence_v1_ListMarketImplicationsRequest:
            type: object
            properties:
                frameworkId:
                    type: string
                    description: Framework identifier whose market implication cards should be listed.
        worldmonitor_intelligence_v1_ListMarketImplicationsResponse:
            type: object
            properties:
                cards:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_MarketImplicationCard'
                degraded:
                    type: boolean
                emptyReason:
                    type: string
                generatedAt:
                    type: string
        worldmonitor_intelligence_v1_MarketImplicationCard:
            type: object
            properties:
                ticker:
                    type: string
                name:
                    type: string
                direction:
                    type: string
                timeframe:
                    type: string
                confidence:
                    type: string
                title:
                    type: string
                narrative:
                    type: string
                riskCaveat:
                    type: string
                driver:
                    type: string
                transmissionChain:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_TransmissionNode'
        worldmonitor_intelligence_v1_TransmissionNode:
            type: object
            properties:
                node:
                    type: string
                impactType:
                    type: string
                logic:
                    type: string
        worldmonitor_intelligence_v1_GetSocialVelocityRequest:
            type: object
        worldmonitor_intelligence_v1_GetSocialVelocityResponse:
            type: object
            properties:
                posts:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_SocialVelocityPost'
                fetchedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
        worldmonitor_intelligence_v1_SocialVelocityPost:
            type: object
            properties:
                id:
                    type: string
                    description: Reddit post ID.
                title:
                    type: string
                    description: Post title.
                subreddit:
                    type: string
                    description: Subreddit name (without r/ prefix).
                url:
                    type: string
                    description: Direct URL to the post.
                score:
                    type: integer
                    format: int32
                    description: Reddit score (upvotes - downvotes).
                upvoteRatio:
                    type: number
                    format: double
                    description: Upvote ratio (0.0–1.0).
                numComments:
                    type: integer
                    format: int32
                    description: Number of comments.
                velocityScore:
                    type: number
                    format: double
                    description: Composite velocity score accounting for recency, score, and ratio.
                createdAt:
                    type: integer
                    format: int64
                    description: 'Unix epoch milliseconds when posted.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: SocialVelocityPost represents a trending Reddit post with velocity scoring.
        worldmonitor_intelligence_v1_GetCountryEnergyProfileRequest:
            type: object
            properties:
                countryCode:
                    type: string
                    description: ISO 3166-1 alpha-2 country code for the energy profile.
        worldmonitor_intelligence_v1_GetCountryEnergyProfileResponse:
            type: object
            properties:
                mixAvailable:
                    type: boolean
                    description: Phase 1 — OWID structural mix (~200 countries)
                mixYear:
                    type: integer
                    format: int32
                coalShare:
                    type: number
                    format: double
                gasShare:
                    type: number
                    format: double
                oilShare:
                    type: number
                    format: double
                nuclearShare:
                    type: number
                    format: double
                renewShare:
                    type: number
                    format: double
                windShare:
                    type: number
                    format: double
                solarShare:
                    type: number
                    format: double
                hydroShare:
                    type: number
                    format: double
                importShare:
                    type: number
                    format: double
                gasStorageAvailable:
                    type: boolean
                    description: Phase 2 — EU gas storage
                gasStorageFillPct:
                    type: number
                    format: double
                gasStorageChange1d:
                    type: number
                    format: double
                gasStorageTrend:
                    type: string
                gasStorageDate:
                    type: string
                electricityAvailable:
                    type: boolean
                    description: |-
                        Phase 2 — EU electricity (ENTSO-E countries: DE FR ES IT NL BE PL PT GB NO SE)
                         US electricity is stored by EIA balancing area, not ISO2 — not available here
                electricityPriceMwh:
                    type: number
                    format: double
                electricitySource:
                    type: string
                electricityDate:
                    type: string
                jodiOilAvailable:
                    type: boolean
                    description: Phase 2.5 — JODI Oil (~90+ countries)
                jodiOilDataMonth:
                    type: string
                gasolineDemandKbd:
                    type: number
                    format: double
                gasolineImportsKbd:
                    type: number
                    format: double
                dieselDemandKbd:
                    type: number
                    format: double
                dieselImportsKbd:
                    type: number
                    format: double
                jetDemandKbd:
                    type: number
                    format: double
                jetImportsKbd:
                    type: number
                    format: double
                lpgDemandKbd:
                    type: number
                    format: double
                crudeImportsKbd:
                    type: number
                    format: double
                lpgImportsKbd:
                    type: number
                    format: double
                jodiGasAvailable:
                    type: boolean
                    description: Phase 2.5 — JODI Gas
                jodiGasDataMonth:
                    type: string
                gasTotalDemandTj:
                    type: number
                    format: double
                gasLngImportsTj:
                    type: number
                    format: double
                gasPipeImportsTj:
                    type: number
                    format: double
                gasLngShare:
                    type: number
                    format: double
                ieaStocksAvailable:
                    type: boolean
                    description: Phase 2.5 — IEA oil stocks (~31 IEA members)
                ieaStocksDataMonth:
                    type: string
                ieaDaysOfCover:
                    type: integer
                    format: int32
                ieaNetExporter:
                    type: boolean
                ieaBelowObligation:
                    type: boolean
                emberFossilShare:
                    type: number
                    format: double
                    description: Phase 3 — Ember monthly electricity mix
                emberRenewShare:
                    type: number
                    format: double
                emberNuclearShare:
                    type: number
                    format: double
                emberCoalShare:
                    type: number
                    format: double
                emberGasShare:
                    type: number
                    format: double
                emberDemandTwh:
                    type: number
                    format: double
                emberDataMonth:
                    type: string
                emberAvailable:
                    type: boolean
                sprRegime:
                    type: string
                    description: Phase 4 — SPR policy classification
                sprCapacityMb:
                    type: number
                    format: double
                sprOperator:
                    type: string
                sprIeaMember:
                    type: boolean
                sprStockholdingModel:
                    type: string
                sprNote:
                    type: string
                sprSource:
                    type: string
                sprAsOf:
                    type: string
                sprAvailable:
                    type: boolean
        worldmonitor_intelligence_v1_ComputeEnergyShockScenarioRequest:
            type: object
            properties:
                countryCode:
                    type: string
                    description: ISO 3166-1 alpha-2 country code for the affected energy market.
                chokepointId:
                    type: string
                    description: Chokepoint identifier to model as disrupted.
                disruptionPct:
                    type: integer
                    format: int32
                    description: Percent of chokepoint flow disrupted, from 0 to 100.
                fuelMode:
                    type: string
                    description: 'Fuel mode to model: "oil", "gas", or "both". Defaults to "oil".'
        worldmonitor_intelligence_v1_ComputeEnergyShockScenarioResponse:
            type: object
            properties:
                countryCode:
                    type: string
                chokepointId:
                    type: string
                disruptionPct:
                    type: integer
                    format: int32
                gulfCrudeShare:
                    type: number
                    format: double
                crudeLossKbd:
                    type: number
                    format: double
                products:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_ProductImpact'
                effectiveCoverDays:
                    type: integer
                    format: int32
                assessment:
                    type: string
                dataAvailable:
                    type: boolean
                jodiOilCoverage:
                    type: boolean
                    description: v2 fields
                comtradeCoverage:
                    type: boolean
                ieaStocksCoverage:
                    type: boolean
                portwatchCoverage:
                    type: boolean
                coverageLevel:
                    type: string
                limitations:
                    type: array
                    items:
                        type: string
                degraded:
                    type: boolean
                chokepointConfidence:
                    type: string
                liveFlowRatio:
                    type: number
                    format: double
                gasImpact:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_GasImpact'
        worldmonitor_intelligence_v1_ProductImpact:
            type: object
            properties:
                product:
                    type: string
                outputLossKbd:
                    type: number
                    format: double
                demandKbd:
                    type: number
                    format: double
                deficitPct:
                    type: number
                    format: double
        worldmonitor_intelligence_v1_GasImpact:
            type: object
            properties:
                lngShareOfImports:
                    type: number
                    format: double
                lngImportsTj:
                    type: number
                    format: double
                lngDisruptionTj:
                    type: number
                    format: double
                totalDemandTj:
                    type: number
                    format: double
                deficitPct:
                    type: number
                    format: double
                dataAvailable:
                    type: boolean
                assessment:
                    type: string
                storage:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_GasStorageBuffer'
                dataSource:
                    type: string
        worldmonitor_intelligence_v1_GasStorageBuffer:
            type: object
            properties:
                fillPct:
                    type: number
                    format: double
                gasTwh:
                    type: number
                    format: double
                bufferDays:
                    type: number
                    format: double
                trend:
                    type: string
                date:
                    type: string
                scope:
                    type: string
        worldmonitor_intelligence_v1_GetCountryPortActivityRequest:
            type: object
            properties:
                countryCode:
                    type: string
                    description: ISO 3166-1 alpha-2 country code for port activity.
        worldmonitor_intelligence_v1_CountryPortActivityResponse:
            type: object
            properties:
                ports:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_PortActivityEntry'
                fetchedAt:
                    type: string
                available:
                    type: boolean
        worldmonitor_intelligence_v1_PortActivityEntry:
            type: object
            properties:
                portId:
                    type: string
                portName:
                    type: string
                lat:
                    type: number
                    format: double
                lon:
                    type: number
                    format: double
                tankerCalls30d:
                    type: integer
                    format: int32
                trendDeltaPct:
                    type: number
                    format: double
                importTankerDwt:
                    type: number
                    format: double
                exportTankerDwt:
                    type: number
                    format: double
                anomalySignal:
                    type: boolean
        worldmonitor_intelligence_v1_GetRegionalSnapshotRequest:
            type: object
            properties:
                regionId:
                    type: string
                    maxLength: 32
                    minLength: 1
                    pattern: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$
                    description: |-
                        Display region id (e.g. "mena", "east-asia", "europe"). See shared/geography.js.
                         Kebab-case: lowercase alphanumeric groups separated by single hyphens, no
                         trailing or consecutive hyphens.
            required:
                - regionId
            description: |-
                GetRegionalSnapshotRequest asks for the latest persisted RegionalSnapshot
                 for a given region. See shared/geography.ts for the canonical region ids.
        worldmonitor_intelligence_v1_GetRegionalSnapshotResponse:
            type: object
            properties:
                snapshot:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_RegionalSnapshot'
            description: |-
                GetRegionalSnapshotResponse returns the latest RegionalSnapshot for the
                 requested region. The snapshot is written by scripts/seed-regional-snapshots.mjs
                 on a 6h cron; this handler only reads canonical state.
        worldmonitor_intelligence_v1_RegionalSnapshot:
            type: object
            properties:
                regionId:
                    type: string
                generatedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                meta:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_SnapshotMeta'
                regime:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_RegimeState'
                balance:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_BalanceVector'
                actors:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_ActorState'
                leverageEdges:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_LeverageEdge'
                scenarioSets:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_ScenarioSet'
                transmissionPaths:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_TransmissionPath'
                triggers:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_TriggerLadder'
                mobility:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_MobilityState'
                evidence:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_EvidenceItem'
                narrative:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_RegionalNarrative'
            description: |-
                RegionalSnapshot is the canonical intelligence object for one region.
                 See docs/internal/pro-regional-intelligence-upgrade.md for the full spec
                 and shared/regions.types.d.ts for the authoritative TypeScript contract.
        worldmonitor_intelligence_v1_SnapshotMeta:
            type: object
            properties:
                snapshotId:
                    type: string
                modelVersion:
                    type: string
                scoringVersion:
                    type: string
                geographyVersion:
                    type: string
                snapshotConfidence:
                    type: number
                    format: double
                missingInputs:
                    type: array
                    items:
                        type: string
                staleInputs:
                    type: array
                    items:
                        type: string
                validUntil:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                triggerReason:
                    type: string
                    description: |-
                        trigger_reason: scheduled_6h | regime_shift | trigger_activation |
                                         corridor_break | leverage_shift
                narrativeProvider:
                    type: string
                narrativeModel:
                    type: string
            description: |-
                SnapshotMeta carries the trust trail (versions, confidence, input freshness,
                 narrative provenance, idempotency id).
        worldmonitor_intelligence_v1_RegimeState:
            type: object
            properties:
                label:
                    type: string
                    description: |-
                        label: calm | stressed_equilibrium | coercive_stalemate |
                                fragmentation_risk | managed_deescalation | escalation_ladder
                previousLabel:
                    type: string
                transitionedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                transitionDriver:
                    type: string
            description: RegimeState captures the current regime label and transition history.
        worldmonitor_intelligence_v1_BalanceVector:
            type: object
            properties:
                coercivePressure:
                    type: number
                    format: double
                    description: Pressures (high = bad)
                domesticFragility:
                    type: number
                    format: double
                capitalStress:
                    type: number
                    format: double
                energyVulnerability:
                    type: number
                    format: double
                allianceCohesion:
                    type: number
                    format: double
                    description: Buffers (high = good)
                maritimeAccess:
                    type: number
                    format: double
                energyLeverage:
                    type: number
                    format: double
                netBalance:
                    type: number
                    format: double
                    description: 'Derived: mean(buffers) - mean(pressures), range [-1, +1]'
                pressures:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_BalanceDriver'
                buffers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_BalanceDriver'
            description: |-
                BalanceVector is the 7-axis regional balance score with pressures/buffers
                 split. See docs/internal/pro-regional-intelligence-appendix-scoring.md for
                 the per-axis formulas.
        worldmonitor_intelligence_v1_BalanceDriver:
            type: object
            properties:
                axis:
                    type: string
                description:
                    type: string
                magnitude:
                    type: number
                    format: double
                evidenceIds:
                    type: array
                    items:
                        type: string
                orientation:
                    type: string
                    description: 'orientation: "pressure" | "buffer"'
            description: BalanceDriver is one contributor to an axis score. Links back to evidence.
        worldmonitor_intelligence_v1_ActorState:
            type: object
            properties:
                actorId:
                    type: string
                name:
                    type: string
                role:
                    type: string
                    description: 'role: aggressor | stabilizer | swing | broker'
                leverageDomains:
                    type: array
                    items:
                        type: string
                        description: 'leverage_domains: energy | military | diplomatic | economic | maritime'
                leverageScore:
                    type: number
                    format: double
                delta:
                    type: number
                    format: double
                evidenceIds:
                    type: array
                    items:
                        type: string
            description: ActorState is one geopolitical actor's leverage score in the region.
        worldmonitor_intelligence_v1_LeverageEdge:
            type: object
            properties:
                fromActorId:
                    type: string
                toActorId:
                    type: string
                mechanism:
                    type: string
                    description: 'mechanism: sanctions | naval_posture | energy_supply | alliance_shift | trade_friction'
                strength:
                    type: number
                    format: double
                evidenceIds:
                    type: array
                    items:
                        type: string
            description: LeverageEdge is a directed influence relationship between two actors.
        worldmonitor_intelligence_v1_ScenarioSet:
            type: object
            properties:
                horizon:
                    type: string
                    description: 'horizon: 24h | 7d | 30d'
                lanes:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_ScenarioLane'
            description: |-
                ScenarioSet bundles scenario lanes for one time horizon. Lane probabilities
                 sum to 1.0 within a set.
        worldmonitor_intelligence_v1_ScenarioLane:
            type: object
            properties:
                name:
                    type: string
                    description: 'name: base | escalation | containment | fragmentation'
                probability:
                    type: number
                    format: double
                triggerIds:
                    type: array
                    items:
                        type: string
                consequences:
                    type: array
                    items:
                        type: string
                transmissions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_TransmissionPath'
            description: ScenarioLane is one outcome branch within a horizon set.
        worldmonitor_intelligence_v1_TransmissionPath:
            type: object
            properties:
                start:
                    type: string
                mechanism:
                    type: string
                end:
                    type: string
                severity:
                    type: string
                    description: 'severity: critical | high | medium | low'
                corridorId:
                    type: string
                confidence:
                    type: number
                    format: double
                latencyHours:
                    type: integer
                    format: int32
                impactedAssetClass:
                    type: string
                    description: 'impacted_asset_class: crude | lng | container | fx | equity | agri | metals | ...'
                impactedRegions:
                    type: array
                    items:
                        type: string
                magnitudeLow:
                    type: number
                    format: double
                magnitudeHigh:
                    type: number
                    format: double
                magnitudeUnit:
                    type: string
                    description: 'magnitude_unit: usd_bbl | pct | usd_teu | basis_points | ...'
                templateId:
                    type: string
                templateVersion:
                    type: string
            description: |-
                TransmissionPath describes how a regional event propagates to markets,
                 logistics, mobility, or other domains. Typed for ranking and calibration.
        worldmonitor_intelligence_v1_TriggerLadder:
            type: object
            properties:
                active:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_Trigger'
                watching:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_Trigger'
                dormant:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_Trigger'
            description: TriggerLadder buckets triggers by activation state.
        worldmonitor_intelligence_v1_Trigger:
            type: object
            properties:
                id:
                    type: string
                description:
                    type: string
                threshold:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_TriggerThreshold'
                activated:
                    type: boolean
                activatedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                scenarioLane:
                    type: string
                    description: 'scenario_lane: base | escalation | containment | fragmentation'
                evidenceIds:
                    type: array
                    items:
                        type: string
            description: Trigger is a structured threshold assertion against a named metric.
        worldmonitor_intelligence_v1_TriggerThreshold:
            type: object
            properties:
                metric:
                    type: string
                operator:
                    type: string
                    description: 'operator: gt | gte | lt | lte | delta_gt | delta_lt'
                value:
                    type: number
                    format: double
                windowMinutes:
                    type: integer
                    format: int32
                baseline:
                    type: string
                    description: 'baseline: trailing_7d | trailing_30d | fixed'
            description: |-
                TriggerThreshold defines the metric/operator/value/window/baseline for
                 deterministic trigger evaluation.
        worldmonitor_intelligence_v1_MobilityState:
            type: object
            properties:
                airspace:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_AirspaceStatus'
                flightCorridors:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_FlightCorridorStress'
                airports:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_AirportNodeStatus'
                rerouteIntensity:
                    type: number
                    format: double
                notamClosures:
                    type: array
                    items:
                        type: string
            description: |-
                MobilityState captures airspace, flight corridor, and airport node status
                 for the region. Phase 0 ships empty; Phase 2 wires the data plane.
        worldmonitor_intelligence_v1_AirspaceStatus:
            type: object
            properties:
                airspaceId:
                    type: string
                status:
                    type: string
                    description: 'status: open | restricted | closed'
                reason:
                    type: string
            description: AirspaceStatus captures FIR-level airspace state.
        worldmonitor_intelligence_v1_FlightCorridorStress:
            type: object
            properties:
                corridor:
                    type: string
                stressLevel:
                    type: number
                    format: double
                reroutedFlights24h:
                    type: integer
                    format: int32
            description: FlightCorridorStress captures per-corridor reroute intensity.
        worldmonitor_intelligence_v1_AirportNodeStatus:
            type: object
            properties:
                icao:
                    type: string
                name:
                    type: string
                status:
                    type: string
                    description: 'status: normal | disrupted | closed'
                disruptionReason:
                    type: string
            description: AirportNodeStatus captures airport-level disruption state.
        worldmonitor_intelligence_v1_EvidenceItem:
            type: object
            properties:
                id:
                    type: string
                type:
                    type: string
                    description: |-
                        type: vessel_track | flight_surge | news_headline | cii_spike |
                               chokepoint_status | sanctions_move | market_signal | mobility_disruption
                source:
                    type: string
                    description: 'source: AIS | ADSB | GDELT | ACLED | Yahoo | OREF | NOTAM | ...'
                summary:
                    type: string
                confidence:
                    type: number
                    format: double
                observedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                theater:
                    type: string
                corridor:
                    type: string
            description: |-
                EvidenceItem is one upstream data point linked from balance drivers,
                 narrative sections, and triggers.
        worldmonitor_intelligence_v1_RegionalNarrative:
            type: object
            properties:
                situation:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_NarrativeSection'
                balanceAssessment:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_NarrativeSection'
                outlook24h:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_NarrativeSection'
                outlook7d:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_NarrativeSection'
                outlook30d:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_NarrativeSection'
                watchItems:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_NarrativeSection'
            description: |-
                RegionalNarrative is the LLM-synthesized narrative layer. Every section
                 links back to evidence via evidence_ids.
        worldmonitor_intelligence_v1_NarrativeSection:
            type: object
            properties:
                text:
                    type: string
                evidenceIds:
                    type: array
                    items:
                        type: string
            description: NarrativeSection is one block of narrative text plus its supporting evidence.
        worldmonitor_intelligence_v1_GetRegimeHistoryRequest:
            type: object
            properties:
                regionId:
                    type: string
                    maxLength: 32
                    minLength: 1
                    pattern: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$
                    description: |-
                        Display region id (e.g. "mena", "east-asia", "europe"). See shared/geography.js.
                         Kebab-case: lowercase alphanumeric groups separated by single hyphens, no
                         trailing or consecutive hyphens.
                limit:
                    type: integer
                    maximum: 100
                    minimum: 0
                    format: int32
                    description: |-
                        Optional cap on how many entries to return. Defaults to 50 server-side
                         when omitted or <= 0. Hard cap enforced by the handler at 100 (= the
                         writer-side LTRIM cap in regime-history.mjs).
            required:
                - regionId
            description: |-
                GetRegimeHistoryRequest asks for the recent regime transition log for a
                 region. Returns newest-first. Phase 3 PR1 — see
                 scripts/regional-snapshot/regime-history.mjs for the writer that
                 populates the underlying Redis list on every regime change.
        worldmonitor_intelligence_v1_GetRegimeHistoryResponse:
            type: object
            properties:
                transitions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_intelligence_v1_RegimeTransition'
            description: |-
                GetRegimeHistoryResponse returns the region's regime transition log
                 newest-first. The list is append-only from the seed writer's perspective:
                 only diffs with regime_changed set produce an entry, so this is a pure
                 transition stream (no steady-state noise).
        worldmonitor_intelligence_v1_RegimeTransition:
            type: object
            properties:
                regionId:
                    type: string
                label:
                    type: string
                    description: Current regime label (the label the region just moved INTO).
                previousLabel:
                    type: string
                    description: |-
                        Previous regime label (the label the region was in before). Empty for
                         the first-ever recorded transition for a region.
                transitionedAt:
                    type: integer
                    format: int64
                    description: |-
                        Unix ms when the transition was recorded. Mirrors
                         snapshot.regime.transitioned_at when available.. Warning: Values > 2^53 may lose precision in JavaScript
                transitionDriver:
                    type: string
                    description: |-
                        Free-text driver string from the seed writer (e.g. "cross_source_surge").
                         May be empty.
                snapshotId:
                    type: string
                    description: |-
                        Snapshot id that materialized this transition. Points back to the
                         full snapshot via intelligence:snapshot-by-id:v1:{snapshot_id}.
            description: |-
                RegimeTransition is a single recorded regime change moment. One of these
                 lands in the log each time diffRegionalSnapshot() reports regime_changed.
        worldmonitor_intelligence_v1_GetRegionalBriefRequest:
            type: object
            properties:
                regionId:
                    type: string
                    maxLength: 32
                    minLength: 1
                    pattern: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$
                    description: Stable regional brief identifier, such as "middle-east".
            required:
                - regionId
        worldmonitor_intelligence_v1_GetRegionalBriefResponse:
            type: object
            properties:
                brief:
                    $ref: '#/components/schemas/worldmonitor_intelligence_v1_RegionalBrief'
        worldmonitor_intelligence_v1_RegionalBrief:
            type: object
            properties:
                regionId:
                    type: string
                generatedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                periodStart:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                periodEnd:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                situationRecap:
                    type: string
                regimeTrajectory:
                    type: string
                keyDevelopments:
                    type: array
                    items:
                        type: string
                riskOutlook:
                    type: string
                provider:
                    type: string
                model:
                    type: string
            description: |-
                RegionalBrief is a weekly LLM-synthesized intelligence summary for one
                 region. Written by scripts/seed-regional-briefs.mjs on a weekly cron.
        worldmonitor_leads_v1_SubmitContactRequest:
            type: object
            properties:
                email:
                    type: string
                name:
                    type: string
                organization:
                    type: string
                phone:
                    type: string
                message:
                    type: string
                source:
                    type: string
                website:
                    type: string
                    description: Honeypot — bots auto-fill this hidden field; real submissions leave it empty.
                turnstileToken:
                    type: string
                    description: Cloudflare Turnstile token proving the submitter is human.
            required:
                - email
                - name
                - organization
                - phone
                - turnstileToken
            description: SubmitContactRequest carries an enterprise contact form submission.
        worldmonitor_leads_v1_SubmitContactResponse:
            type: object
            properties:
                status:
                    type: string
                    description: Always "sent" on success.
                emailSent:
                    type: boolean
                    description: True when the Resend notification to ops was delivered.
            description: SubmitContactResponse reports the outcome of storing the lead and notifying ops.
        worldmonitor_leads_v1_RegisterInterestRequest:
            type: object
            properties:
                email:
                    type: string
                source:
                    type: string
                appVersion:
                    type: string
                referredBy:
                    type: string
                website:
                    type: string
                    description: Honeypot — bots auto-fill this hidden field; real submissions leave it empty.
                turnstileToken:
                    type: string
                    description: Cloudflare Turnstile token. Desktop sources bypass Turnstile; see handler.
            required:
                - email
                - turnstileToken
            description: RegisterInterestRequest carries a Pro-waitlist signup.
        worldmonitor_leads_v1_RegisterInterestResponse:
            type: object
            properties:
                status:
                    type: string
                    description: '"registered" for a new signup; "already_registered" for a returning email.'
                referralCode:
                    type: string
                    description: Stable referral code for this email.
                referralCount:
                    type: integer
                    format: int32
                    description: Number of signups credited to this email.
                position:
                    type: integer
                    format: int32
                    description: Waitlist position at registration time. Present only when status == "registered".
                emailSuppressed:
                    type: boolean
                    description: True when the email is on the suppression list (prior bounce) and no confirmation was sent.
            description: RegisterInterestResponse mirrors the Convex registerInterest:register return shape.
        worldmonitor_maritime_v1_GetVesselSnapshotRequest:
            type: object
            properties:
                neLat:
                    type: number
                    format: double
                    description: North-east corner latitude of bounding box.
                neLon:
                    type: number
                    format: double
                    description: North-east corner longitude of bounding box.
                swLat:
                    type: number
                    format: double
                    description: South-west corner latitude of bounding box.
                swLon:
                    type: number
                    format: double
                    description: South-west corner longitude of bounding box.
                includeCandidates:
                    type: boolean
                    description: |-
                        When true, populate VesselSnapshot.candidate_reports with per-vessel
                         position reports. Clients with no position callbacks should leave this
                         false to keep responses small.
                includeTankers:
                    type: boolean
                    description: |-
                        When true, populate VesselSnapshot.tanker_reports with per-vessel
                         position reports for AIS ship-type 80-89 (tanker class). Used by the
                         Energy Atlas live-tanker map layer. Stored separately from
                         candidate_reports (which is military-only) so consumers self-select
                         via this flag rather than the response field changing meaning.
            description: GetVesselSnapshotRequest specifies filters for the vessel snapshot.
        worldmonitor_maritime_v1_GetVesselSnapshotResponse:
            type: object
            properties:
                snapshot:
                    $ref: '#/components/schemas/worldmonitor_maritime_v1_VesselSnapshot'
                fetchedAt:
                    type: integer
                    format: int64
                    description: |-
                        Time the relay snapshot was fetched, as Unix epoch milliseconds. A value
                         of 0 means the snapshot is unavailable/degraded, not that vessel traffic is
                         confirmed absent.. Warning: Values > 2^53 may lose precision in JavaScript
                dataAvailable:
                    type: boolean
                    description: |-
                        True when snapshot is populated. False means an absent snapshot is
                         graceful degradation because the relay snapshot is unavailable.
            description: GetVesselSnapshotResponse contains the vessel traffic snapshot.
        worldmonitor_maritime_v1_VesselSnapshot:
            type: object
            properties:
                snapshotAt:
                    type: integer
                    format: int64
                    description: 'Snapshot timestamp, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                densityZones:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_maritime_v1_AisDensityZone'
                disruptions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_maritime_v1_AisDisruption'
                sequence:
                    type: integer
                    format: int32
                    description: |-
                        Monotonic sequence number from the relay. Clients use this to detect stale
                         responses during polling.
                status:
                    $ref: '#/components/schemas/worldmonitor_maritime_v1_AisSnapshotStatus'
                candidateReports:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_maritime_v1_SnapshotCandidateReport'
                tankerReports:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_maritime_v1_SnapshotCandidateReport'
            description: VesselSnapshot represents a point-in-time view of civilian AIS vessel data.
        worldmonitor_maritime_v1_AisDensityZone:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Zone identifier.
                name:
                    type: string
                    description: Zone name (e.g., "Strait of Malacca").
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                intensity:
                    type: number
                    maximum: 100
                    minimum: 0
                    format: double
                    description: Traffic intensity score (0-100).
                deltaPct:
                    type: number
                    format: double
                    description: Change from baseline as a percentage.
                shipsPerDay:
                    type: integer
                    format: int32
                    description: Estimated ships per day.
                note:
                    type: string
                    description: Analyst note.
            required:
                - id
            description: AisDensityZone represents a zone of concentrated vessel traffic.
        worldmonitor_maritime_v1_AisDisruption:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Disruption identifier.
                name:
                    type: string
                    description: Descriptive name.
                type:
                    type: string
                    enum:
                        - AIS_DISRUPTION_TYPE_UNSPECIFIED
                        - AIS_DISRUPTION_TYPE_GAP_SPIKE
                        - AIS_DISRUPTION_TYPE_CHOKEPOINT_CONGESTION
                    description: |-
                        AisDisruptionType represents the type of AIS tracking anomaly.
                         Maps to TS union: 'gap_spike' | 'chokepoint_congestion'.
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                severity:
                    type: string
                    enum:
                        - AIS_DISRUPTION_SEVERITY_UNSPECIFIED
                        - AIS_DISRUPTION_SEVERITY_LOW
                        - AIS_DISRUPTION_SEVERITY_ELEVATED
                        - AIS_DISRUPTION_SEVERITY_HIGH
                    description: AisDisruptionSeverity represents the severity of an AIS disruption.
                changePct:
                    type: number
                    format: double
                    description: Percentage change from normal.
                windowHours:
                    type: integer
                    format: int32
                    description: Analysis window in hours.
                darkShips:
                    type: integer
                    format: int32
                    description: Number of dark ships (AIS off) detected.
                vesselCount:
                    type: integer
                    format: int32
                    description: Number of vessels in the affected area.
                region:
                    type: string
                    description: Region name.
                description:
                    type: string
                    description: Human-readable description.
            required:
                - id
            description: AisDisruption represents a detected anomaly in AIS vessel tracking data.
        worldmonitor_maritime_v1_AisSnapshotStatus:
            type: object
            properties:
                connected:
                    type: boolean
                    description: Whether the relay WebSocket is connected to the AIS provider.
                vessels:
                    type: integer
                    format: int32
                    description: Number of vessels currently tracked by the relay.
                messages:
                    type: integer
                    format: int32
                    description: Total AIS messages processed in the current session.
            description: AisSnapshotStatus reports relay health at the time of the snapshot.
        worldmonitor_maritime_v1_SnapshotCandidateReport:
            type: object
            properties:
                mmsi:
                    type: string
                    description: Maritime Mobile Service Identity.
                name:
                    type: string
                    description: Vessel name (may be empty if unknown).
                lat:
                    type: number
                    format: double
                    description: Latitude in decimal degrees.
                lon:
                    type: number
                    format: double
                    description: Longitude in decimal degrees.
                shipType:
                    type: integer
                    format: int32
                    description: AIS ship type code (0 if unknown).
                heading:
                    type: integer
                    format: int32
                    description: Heading in degrees (0-359, or 511 for unavailable).
                speed:
                    type: number
                    format: double
                    description: Speed over ground in knots.
                course:
                    type: integer
                    format: int32
                    description: Course over ground in degrees.
                timestamp:
                    type: integer
                    format: int64
                    description: 'Report timestamp, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: |-
                SnapshotCandidateReport is a per-vessel position report attached to a
                 snapshot. Used to drive the client-side position callback system.
        worldmonitor_maritime_v1_ListNavigationalWarningsRequest:
            type: object
            properties:
                pageSize:
                    type: integer
                    format: int32
                    description: |-
                        Maximum items per page (1-100).
                         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.
                area:
                    type: string
                    description: Optional area filter (e.g., "NAVAREA IV", "Persian Gulf").
            description: ListNavigationalWarningsRequest specifies filters for retrieving NGA warnings.
        worldmonitor_maritime_v1_ListNavigationalWarningsResponse:
            type: object
            properties:
                warnings:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_maritime_v1_NavigationalWarning'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListNavigationalWarningsResponse contains navigational warnings matching the request.
        worldmonitor_maritime_v1_NavigationalWarning:
            type: object
            properties:
                id:
                    type: string
                    description: Warning identifier.
                title:
                    type: string
                    description: Warning title.
                text:
                    type: string
                    description: Full warning text.
                area:
                    type: string
                    description: Geographic area affected.
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                issuedAt:
                    type: integer
                    format: int64
                    description: 'Warning issue date, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                expiresAt:
                    type: integer
                    format: int64
                    description: 'Warning expiry date, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                authority:
                    type: string
                    description: Warning source authority.
            description: NavigationalWarning represents a maritime safety warning from NGA.
        worldmonitor_market_v1_ListMarketQuotesRequest:
            type: object
            properties:
                symbols:
                    type: array
                    items:
                        type: string
                        description: Ticker symbols to retrieve (e.g., ["AAPL", "^GSPC"]). Empty returns defaults.
            description: ListMarketQuotesRequest specifies which stock/index symbols to retrieve.
        worldmonitor_market_v1_ListMarketQuotesResponse:
            type: object
            properties:
                quotes:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_MarketQuote'
                finnhubSkipped:
                    type: boolean
                    description: True when the Finnhub API key is not configured and stock quotes were skipped.
                skipReason:
                    type: string
                    description: Human-readable reason when Finnhub was skipped (e.g., "FINNHUB_API_KEY not configured").
                rateLimited:
                    type: boolean
                    description: True when the upstream API rate-limited the request.
            description: ListMarketQuotesResponse contains stock and index quotes.
        worldmonitor_market_v1_MarketQuote:
            type: object
            properties:
                symbol:
                    type: string
                    minLength: 1
                    description: Ticker symbol (e.g., "AAPL", "^GSPC").
                name:
                    type: string
                    description: Human-readable name.
                display:
                    type: string
                    description: Display label.
                price:
                    type: number
                    format: double
                    description: Current price.
                change:
                    type: number
                    format: double
                    description: Percentage change from previous close.
                sparkline:
                    type: array
                    items:
                        type: number
                        format: double
                        description: Sparkline data points (recent price history).
            required:
                - symbol
            description: MarketQuote represents a stock or index quote from Finnhub or Yahoo Finance.
        worldmonitor_market_v1_ListCryptoQuotesRequest:
            type: object
            properties:
                ids:
                    type: array
                    items:
                        type: string
                        description: Cryptocurrency IDs to retrieve (CoinGecko IDs). Empty returns defaults.
            description: ListCryptoQuotesRequest specifies which cryptocurrencies to retrieve.
        worldmonitor_market_v1_ListCryptoQuotesResponse:
            type: object
            properties:
                quotes:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_CryptoQuote'
            description: ListCryptoQuotesResponse contains cryptocurrency quotes.
        worldmonitor_market_v1_CryptoQuote:
            type: object
            properties:
                name:
                    type: string
                    description: Cryptocurrency name (e.g., "Bitcoin").
                symbol:
                    type: string
                    minLength: 1
                    description: Ticker symbol (e.g., "BTC").
                price:
                    type: number
                    format: double
                    description: Current price in USD.
                change:
                    type: number
                    format: double
                    description: 24-hour percentage change.
                sparkline:
                    type: array
                    items:
                        type: number
                        format: double
                        description: Sparkline data points (recent price history).
                change7d:
                    type: number
                    format: double
                    description: 7-day percentage change.
            required:
                - symbol
            description: CryptoQuote represents a cryptocurrency quote from CoinGecko.
        worldmonitor_market_v1_ListCommodityQuotesRequest:
            type: object
            properties:
                symbols:
                    type: array
                    items:
                        type: string
                        description: Commodity symbols to retrieve (Yahoo symbols). Empty returns defaults.
            description: ListCommodityQuotesRequest specifies which commodities to retrieve.
        worldmonitor_market_v1_ListCommodityQuotesResponse:
            type: object
            properties:
                quotes:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_CommodityQuote'
            description: ListCommodityQuotesResponse contains commodity quotes.
        worldmonitor_market_v1_CommodityQuote:
            type: object
            properties:
                symbol:
                    type: string
                    minLength: 1
                    description: Commodity symbol (e.g., "CL=F" for crude oil).
                name:
                    type: string
                    description: Human-readable name.
                display:
                    type: string
                    description: Display label.
                price:
                    type: number
                    format: double
                    description: Current price.
                change:
                    type: number
                    format: double
                    description: Percentage change from previous close.
                sparkline:
                    type: array
                    items:
                        type: number
                        format: double
                        description: Sparkline data points.
            required:
                - symbol
            description: CommodityQuote represents a commodity price quote from Yahoo Finance.
        worldmonitor_market_v1_GetSectorSummaryRequest:
            type: object
            properties:
                period:
                    type: string
                    description: |-
                        Time period for performance calculation (e.g., "1d", "1w", "1m"). Defaults to "1d".
                         Accepted but currently ignored; no-op until this handler supports the parameter.
            description: GetSectorSummaryRequest specifies parameters for retrieving sector performance.
        worldmonitor_market_v1_GetSectorSummaryResponse:
            type: object
            properties:
                sectors:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_SectorPerformance'
            description: GetSectorSummaryResponse contains sector performance data.
        worldmonitor_market_v1_SectorPerformance:
            type: object
            properties:
                symbol:
                    type: string
                    minLength: 1
                    description: Sector symbol.
                name:
                    type: string
                    description: Sector name.
                change:
                    type: number
                    format: double
                    description: Percentage change over the measured period.
            required:
                - symbol
            description: SectorPerformance represents performance data for a market sector.
        worldmonitor_market_v1_ListStablecoinMarketsRequest:
            type: object
            properties:
                coins:
                    type: array
                    items:
                        type: string
                        description: CoinGecko IDs to retrieve (e.g. "tether,usd-coin"). Empty returns defaults.
            description: ListStablecoinMarketsRequest specifies which stablecoins to retrieve.
        worldmonitor_market_v1_ListStablecoinMarketsResponse:
            type: object
            properties:
                timestamp:
                    type: string
                    description: Timestamp of the data fetch (ISO 8601).
                summary:
                    $ref: '#/components/schemas/worldmonitor_market_v1_StablecoinSummary'
                stablecoins:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_Stablecoin'
            description: ListStablecoinMarketsResponse contains stablecoin market data.
        worldmonitor_market_v1_StablecoinSummary:
            type: object
            properties:
                totalMarketCap:
                    type: number
                    format: double
                    description: Total market cap across all queried stablecoins.
                totalVolume24h:
                    type: number
                    format: double
                    description: Total 24h volume across all queried stablecoins.
                coinCount:
                    type: integer
                    format: int32
                    description: Number of stablecoins returned.
                depeggedCount:
                    type: integer
                    format: int32
                    description: Number of stablecoins in DEPEGGED state.
                healthStatus:
                    type: string
                    description: 'Overall health: "HEALTHY", "CAUTION", or "WARNING".'
            description: StablecoinSummary contains aggregate stablecoin market stats.
        worldmonitor_market_v1_Stablecoin:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: CoinGecko ID.
                symbol:
                    type: string
                    minLength: 1
                    description: Ticker symbol (e.g. "USDT").
                name:
                    type: string
                    description: Human-readable name.
                price:
                    type: number
                    minimum: 0
                    format: double
                    description: Current price in USD.
                deviation:
                    type: number
                    format: double
                    description: Deviation from $1.00 peg, as a percentage.
                pegStatus:
                    type: string
                    description: 'Peg status: "ON PEG", "SLIGHT DEPEG", or "DEPEGGED".'
                marketCap:
                    type: number
                    format: double
                    description: Market capitalization in USD.
                volume24h:
                    type: number
                    format: double
                    description: 24-hour trading volume in USD.
                change24h:
                    type: number
                    format: double
                    description: 24-hour price change percentage.
                change7d:
                    type: number
                    format: double
                    description: 7-day price change percentage.
                image:
                    type: string
                    description: Coin image URL.
            required:
                - id
                - symbol
            description: Stablecoin represents a single stablecoin with peg health data.
        worldmonitor_market_v1_ListEtfFlowsRequest:
            type: object
            description: ListEtfFlowsRequest is empty; the handler uses a fixed list of BTC spot ETFs.
        worldmonitor_market_v1_ListEtfFlowsResponse:
            type: object
            properties:
                timestamp:
                    type: string
                    description: Timestamp of the data fetch (ISO 8601).
                summary:
                    $ref: '#/components/schemas/worldmonitor_market_v1_EtfFlowsSummary'
                etfs:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_EtfFlow'
                rateLimited:
                    type: boolean
                    description: True when the upstream API rate-limited the request.
            description: ListEtfFlowsResponse contains BTC spot ETF flow data.
        worldmonitor_market_v1_EtfFlowsSummary:
            type: object
            properties:
                etfCount:
                    type: integer
                    format: int32
                    description: Number of ETFs with data.
                totalVolume:
                    type: integer
                    format: int64
                    description: 'Total volume across all ETFs.. Warning: Values > 2^53 may lose precision in JavaScript'
                totalEstFlow:
                    type: integer
                    format: int64
                    description: 'Total estimated flow across all ETFs.. Warning: Values > 2^53 may lose precision in JavaScript'
                netDirection:
                    type: string
                    description: 'Net direction: "NET INFLOW", "NET OUTFLOW", or "NEUTRAL".'
                inflowCount:
                    type: integer
                    format: int32
                    description: Number of ETFs with inflow.
                outflowCount:
                    type: integer
                    format: int32
                    description: Number of ETFs with outflow.
            description: EtfFlowsSummary contains aggregate ETF flow stats.
        worldmonitor_market_v1_EtfFlow:
            type: object
            properties:
                ticker:
                    type: string
                    minLength: 1
                    description: Ticker symbol (e.g. "IBIT").
                issuer:
                    type: string
                    description: Fund issuer (e.g. "BlackRock").
                price:
                    type: number
                    format: double
                    description: Latest closing price.
                priceChange:
                    type: number
                    format: double
                    description: Day-over-day price change percentage.
                volume:
                    type: integer
                    format: int64
                    description: 'Latest daily volume.. Warning: Values > 2^53 may lose precision in JavaScript'
                avgVolume:
                    type: integer
                    format: int64
                    description: 'Average volume over prior days.. Warning: Values > 2^53 may lose precision in JavaScript'
                volumeRatio:
                    type: number
                    format: double
                    description: Volume ratio (latest / average).
                direction:
                    type: string
                    description: 'Flow direction: "inflow", "outflow", or "neutral".'
                estFlow:
                    type: integer
                    format: int64
                    description: 'Estimated dollar flow magnitude.. Warning: Values > 2^53 may lose precision in JavaScript'
            required:
                - ticker
            description: EtfFlow represents a single ETF with estimated flow data.
        worldmonitor_market_v1_GetCountryStockIndexRequest:
            type: object
            properties:
                countryCode:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "JP").
            required:
                - countryCode
            description: GetCountryStockIndexRequest specifies which country's stock index to retrieve.
        worldmonitor_market_v1_GetCountryStockIndexResponse:
            type: object
            properties:
                available:
                    type: boolean
                    description: Whether stock index data is available for this country.
                code:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                symbol:
                    type: string
                    description: Ticker symbol (e.g., "^GSPC").
                indexName:
                    type: string
                    description: Index name (e.g., "S&P 500").
                price:
                    type: number
                    format: double
                    description: Latest closing price.
                weekChangePercent:
                    type: number
                    format: double
                    description: Weekly change percentage.
                currency:
                    type: string
                    description: Currency of the index.
                fetchedAt:
                    type: string
                    description: When the data was fetched (ISO 8601).
            description: GetCountryStockIndexResponse contains the country's primary stock index data.
        worldmonitor_market_v1_ListGulfQuotesRequest:
            type: object
        worldmonitor_market_v1_ListGulfQuotesResponse:
            type: object
            properties:
                quotes:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_GulfQuote'
                rateLimited:
                    type: boolean
        worldmonitor_market_v1_GulfQuote:
            type: object
            properties:
                symbol:
                    type: string
                name:
                    type: string
                flag:
                    type: string
                country:
                    type: string
                type:
                    type: string
                price:
                    type: number
                    format: double
                change:
                    type: number
                    format: double
                sparkline:
                    type: array
                    items:
                        type: number
                        format: double
            description: GulfQuote represents a Gulf region market quote (index, currency, or oil).
        worldmonitor_market_v1_AnalyzeStockRequest:
            type: object
            properties:
                symbol:
                    type: string
                    maxLength: 32
                    minLength: 1
                    description: Stock ticker symbol to analyze.
                name:
                    type: string
                    maxLength: 120
                    description: Optional company display name used to disambiguate the symbol.
                includeNews:
                    type: boolean
                    description: Whether to include recent news in the stock analysis.
            required:
                - symbol
        worldmonitor_market_v1_AnalyzeStockResponse:
            type: object
            properties:
                available:
                    type: boolean
                symbol:
                    type: string
                name:
                    type: string
                display:
                    type: string
                currency:
                    type: string
                currentPrice:
                    type: number
                    format: double
                changePercent:
                    type: number
                    format: double
                signalScore:
                    type: number
                    format: double
                signal:
                    type: string
                trendStatus:
                    type: string
                volumeStatus:
                    type: string
                macdStatus:
                    type: string
                rsiStatus:
                    type: string
                summary:
                    type: string
                action:
                    type: string
                confidence:
                    type: string
                technicalSummary:
                    type: string
                newsSummary:
                    type: string
                whyNow:
                    type: string
                bullishFactors:
                    type: array
                    items:
                        type: string
                riskFactors:
                    type: array
                    items:
                        type: string
                supportLevels:
                    type: array
                    items:
                        type: number
                        format: double
                resistanceLevels:
                    type: array
                    items:
                        type: number
                        format: double
                headlines:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_StockAnalysisHeadline'
                ma5:
                    type: number
                    format: double
                ma10:
                    type: number
                    format: double
                ma20:
                    type: number
                    format: double
                ma60:
                    type: number
                    format: double
                biasMa5:
                    type: number
                    format: double
                biasMa10:
                    type: number
                    format: double
                biasMa20:
                    type: number
                    format: double
                volumeRatio5d:
                    type: number
                    format: double
                rsi12:
                    type: number
                    format: double
                macdDif:
                    type: number
                    format: double
                macdDea:
                    type: number
                    format: double
                macdBar:
                    type: number
                    format: double
                provider:
                    type: string
                model:
                    type: string
                fallback:
                    type: boolean
                newsSearched:
                    type: boolean
                generatedAt:
                    type: string
                analysisId:
                    type: string
                analysisAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                stopLoss:
                    type: number
                    format: double
                takeProfit:
                    type: number
                    format: double
                engineVersion:
                    type: string
                analystConsensus:
                    $ref: '#/components/schemas/worldmonitor_market_v1_AnalystConsensus'
                priceTarget:
                    $ref: '#/components/schemas/worldmonitor_market_v1_PriceTarget'
                recentUpgrades:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_UpgradeDowngrade'
                dividendYield:
                    type: number
                    format: double
                trailingAnnualDividendRate:
                    type: number
                    format: double
                exDividendDate:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                payoutRatio:
                    type: number
                    format: double
                dividendFrequency:
                    type: string
                dividendCagr:
                    type: number
                    format: double
                marketSession:
                    type: string
                    description: |-
                        US-equity trading session at analysis time: "regular", "pre", "post" or
                         "closed". Empty when session detection does not apply (non-US symbols).
                extendedPrice:
                    type: number
                    format: double
                    description: |-
                        Latest pre/post-market price from Yahoo extended-hours candles. Only set
                         when market_session is "pre" or "post" and extended data is available.
                extendedChangePercent:
                    type: number
                    format: double
                    description: |-
                        Extended-hours change % vs the last regular-session close. Only set when
                         extended_price is set.
        worldmonitor_market_v1_StockAnalysisHeadline:
            type: object
            properties:
                title:
                    type: string
                source:
                    type: string
                link:
                    type: string
                publishedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
        worldmonitor_market_v1_AnalystConsensus:
            type: object
            properties:
                strongBuy:
                    type: integer
                    format: int32
                buy:
                    type: integer
                    format: int32
                hold:
                    type: integer
                    format: int32
                sell:
                    type: integer
                    format: int32
                strongSell:
                    type: integer
                    format: int32
                total:
                    type: integer
                    format: int32
                period:
                    type: string
        worldmonitor_market_v1_PriceTarget:
            type: object
            properties:
                high:
                    type: number
                    format: double
                low:
                    type: number
                    format: double
                mean:
                    type: number
                    format: double
                median:
                    type: number
                    format: double
                current:
                    type: number
                    format: double
                numberOfAnalysts:
                    type: integer
                    format: int32
        worldmonitor_market_v1_UpgradeDowngrade:
            type: object
            properties:
                firm:
                    type: string
                toGrade:
                    type: string
                fromGrade:
                    type: string
                action:
                    type: string
                epochGradeDate:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
        worldmonitor_market_v1_GetStockAnalysisHistoryRequest:
            type: object
            properties:
                symbols:
                    type: array
                    items:
                        type: string
                        description: Stock ticker symbols whose stored analysis history should be returned.
                limitPerSymbol:
                    type: integer
                    maximum: 32
                    minimum: 1
                    format: int32
                    description: Maximum number of history snapshots to return per symbol.
                includeNews:
                    type: boolean
                    description: Whether history snapshots should include stored news summaries.
        worldmonitor_market_v1_GetStockAnalysisHistoryResponse:
            type: object
            properties:
                items:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_StockAnalysisHistoryItem'
        worldmonitor_market_v1_StockAnalysisHistoryItem:
            type: object
            properties:
                symbol:
                    type: string
                snapshots:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_AnalyzeStockResponse'
        worldmonitor_market_v1_BacktestStockRequest:
            type: object
            properties:
                symbol:
                    type: string
                    maxLength: 32
                    minLength: 1
                    description: Stock ticker symbol to backtest.
                name:
                    type: string
                    maxLength: 120
                    description: Optional company display name used to disambiguate the symbol.
                evalWindowDays:
                    type: integer
                    maximum: 30
                    minimum: 3
                    format: int32
                    description: Evaluation window in days for simulated backtest outcomes.
            required:
                - symbol
        worldmonitor_market_v1_BacktestStockResponse:
            type: object
            properties:
                available:
                    type: boolean
                symbol:
                    type: string
                name:
                    type: string
                display:
                    type: string
                currency:
                    type: string
                evalWindowDays:
                    type: integer
                    format: int32
                evaluationsRun:
                    type: integer
                    format: int32
                actionableEvaluations:
                    type: integer
                    format: int32
                winRate:
                    type: number
                    format: double
                directionAccuracy:
                    type: number
                    format: double
                avgSimulatedReturnPct:
                    type: number
                    format: double
                cumulativeSimulatedReturnPct:
                    type: number
                    format: double
                latestSignal:
                    type: string
                latestSignalScore:
                    type: number
                    format: double
                summary:
                    type: string
                generatedAt:
                    type: string
                evaluations:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_BacktestStockEvaluation'
                engineVersion:
                    type: string
        worldmonitor_market_v1_BacktestStockEvaluation:
            type: object
            properties:
                analysisAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                signal:
                    type: string
                signalScore:
                    type: number
                    format: double
                entryPrice:
                    type: number
                    format: double
                exitPrice:
                    type: number
                    format: double
                simulatedReturnPct:
                    type: number
                    format: double
                directionCorrect:
                    type: boolean
                outcome:
                    type: string
                stopLoss:
                    type: number
                    format: double
                takeProfit:
                    type: number
                    format: double
                analysisId:
                    type: string
        worldmonitor_market_v1_ListStoredStockBacktestsRequest:
            type: object
            properties:
                symbols:
                    type: array
                    items:
                        type: string
                        description: Stock ticker symbols whose stored backtests should be returned.
                evalWindowDays:
                    type: integer
                    maximum: 30
                    minimum: 3
                    format: int32
                    description: Evaluation window in days used by stored backtests.
        worldmonitor_market_v1_ListStoredStockBacktestsResponse:
            type: object
            properties:
                items:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_BacktestStockResponse'
        worldmonitor_market_v1_ListCryptoSectorsRequest:
            type: object
            description: ListCryptoSectorsRequest retrieves crypto sector performance.
        worldmonitor_market_v1_ListCryptoSectorsResponse:
            type: object
            properties:
                sectors:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_CryptoSector'
            description: ListCryptoSectorsResponse contains crypto sector performance data.
        worldmonitor_market_v1_CryptoSector:
            type: object
            properties:
                id:
                    type: string
                    description: Sector identifier.
                name:
                    type: string
                    description: Sector display name.
                change:
                    type: number
                    format: double
                    description: Average 24h percentage change across sector tokens.
            description: CryptoSector represents performance data for a crypto market sector.
        worldmonitor_market_v1_ListDefiTokensRequest:
            type: object
            description: ListDefiTokensRequest retrieves DeFi token prices.
        worldmonitor_market_v1_ListDefiTokensResponse:
            type: object
            properties:
                tokens:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_CryptoQuote'
            description: ListDefiTokensResponse contains DeFi token price data.
        worldmonitor_market_v1_ListAiTokensRequest:
            type: object
            description: ListAiTokensRequest retrieves AI crypto token prices.
        worldmonitor_market_v1_ListAiTokensResponse:
            type: object
            properties:
                tokens:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_CryptoQuote'
            description: ListAiTokensResponse contains AI token price data.
        worldmonitor_market_v1_ListOtherTokensRequest:
            type: object
            description: ListOtherTokensRequest retrieves other/trending crypto token prices.
        worldmonitor_market_v1_ListOtherTokensResponse:
            type: object
            properties:
                tokens:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_CryptoQuote'
            description: ListOtherTokensResponse contains other token price data.
        worldmonitor_market_v1_GetFearGreedIndexRequest:
            type: object
        worldmonitor_market_v1_GetFearGreedIndexResponse:
            type: object
            properties:
                compositeScore:
                    type: number
                    format: double
                compositeLabel:
                    type: string
                previousScore:
                    type: number
                    format: double
                seededAt:
                    type: string
                sentiment:
                    $ref: '#/components/schemas/worldmonitor_market_v1_FearGreedCategory'
                volatility:
                    $ref: '#/components/schemas/worldmonitor_market_v1_FearGreedCategory'
                positioning:
                    $ref: '#/components/schemas/worldmonitor_market_v1_FearGreedCategory'
                trend:
                    $ref: '#/components/schemas/worldmonitor_market_v1_FearGreedCategory'
                breadth:
                    $ref: '#/components/schemas/worldmonitor_market_v1_FearGreedCategory'
                momentum:
                    $ref: '#/components/schemas/worldmonitor_market_v1_FearGreedCategory'
                liquidity:
                    $ref: '#/components/schemas/worldmonitor_market_v1_FearGreedCategory'
                credit:
                    $ref: '#/components/schemas/worldmonitor_market_v1_FearGreedCategory'
                macro:
                    $ref: '#/components/schemas/worldmonitor_market_v1_FearGreedCategory'
                crossAsset:
                    $ref: '#/components/schemas/worldmonitor_market_v1_FearGreedCategory'
                vix:
                    type: number
                    format: double
                hySpread:
                    type: number
                    format: double
                yield10y:
                    type: number
                    format: double
                putCallRatio:
                    type: number
                    format: double
                pctAbove200d:
                    type: number
                    format: double
                cnnFearGreed:
                    type: number
                    format: double
                cnnLabel:
                    type: string
                aaiiBull:
                    type: number
                    format: double
                aaiiBear:
                    type: number
                    format: double
                fedRate:
                    type: string
                unavailable:
                    type: boolean
                    description: |-
                        True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
                fsiValue:
                    type: number
                    format: double
                    description: |-
                        Bespoke Fear & Greed header stress ratio, not the KCFSI/ECB FSI panel
                         composite. Formula: (HYG / TLT) / (VIX * HY OAS / 100).
                fsiLabel:
                    type: string
                    description: |-
                        Label for fsi_value: Low Stress (>=1.5), Moderate Stress (>=0.8),
                         Elevated Stress (>=0.3), otherwise High Stress.
                hygPrice:
                    type: number
                    format: double
                    description: Latest HYG ETF price used in the Fear & Greed header stress ratio.
                tltPrice:
                    type: number
                    format: double
                    description: Latest TLT ETF price used in the Fear & Greed header stress ratio.
                sectorPerformance:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_FearGreedSectorPerformance'
        worldmonitor_market_v1_FearGreedCategory:
            type: object
            properties:
                score:
                    type: number
                    format: double
                weight:
                    type: number
                    format: double
                contribution:
                    type: number
                    format: double
                degraded:
                    type: boolean
                inputsJson:
                    type: string
        worldmonitor_market_v1_FearGreedSectorPerformance:
            type: object
            properties:
                symbol:
                    type: string
                name:
                    type: string
                change1d:
                    type: number
                    format: double
        worldmonitor_market_v1_ListEarningsCalendarRequest:
            type: object
            properties:
                fromDate:
                    type: string
                    description: Accepted but currently ignored; no-op until this handler supports the parameter.
                toDate:
                    type: string
                    description: Accepted but currently ignored; no-op until this handler supports the parameter.
        worldmonitor_market_v1_ListEarningsCalendarResponse:
            type: object
            properties:
                earnings:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_EarningsEntry'
                fromDate:
                    type: string
                toDate:
                    type: string
                total:
                    type: integer
                    format: int32
                unavailable:
                    type: boolean
                    description: |-
                        True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
        worldmonitor_market_v1_EarningsEntry:
            type: object
            properties:
                symbol:
                    type: string
                company:
                    type: string
                date:
                    type: string
                hour:
                    type: string
                epsEstimate:
                    type: number
                    format: double
                revenueEstimate:
                    type: number
                    format: double
                epsActual:
                    type: number
                    format: double
                revenueActual:
                    type: number
                    format: double
                hasActuals:
                    type: boolean
                surpriseDirection:
                    type: string
        worldmonitor_market_v1_GetCotPositioningRequest:
            type: object
        worldmonitor_market_v1_GetCotPositioningResponse:
            type: object
            properties:
                instruments:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_CotInstrument'
                reportDate:
                    type: string
                unavailable:
                    type: boolean
                    description: |-
                        True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
        worldmonitor_market_v1_CotInstrument:
            type: object
            properties:
                name:
                    type: string
                code:
                    type: string
                reportDate:
                    type: string
                assetManagerLong:
                    type: string
                    format: int64
                assetManagerShort:
                    type: string
                    format: int64
                leveragedFundsLong:
                    type: string
                    format: int64
                leveragedFundsShort:
                    type: string
                    format: int64
                dealerLong:
                    type: string
                    format: int64
                dealerShort:
                    type: string
                    format: int64
                netPct:
                    type: number
                    format: double
        worldmonitor_market_v1_GetInsiderTransactionsRequest:
            type: object
            properties:
                symbol:
                    type: string
                    maxLength: 32
                    minLength: 1
                    description: Stock ticker symbol for insider transaction lookup.
            required:
                - symbol
        worldmonitor_market_v1_GetInsiderTransactionsResponse:
            type: object
            properties:
                unavailable:
                    type: boolean
                    description: |-
                        True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
                symbol:
                    type: string
                totalBuys:
                    type: number
                    format: double
                totalSells:
                    type: number
                    format: double
                netValue:
                    type: number
                    format: double
                transactions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_InsiderTransaction'
                fetchedAt:
                    type: string
        worldmonitor_market_v1_InsiderTransaction:
            type: object
            properties:
                name:
                    type: string
                shares:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                value:
                    type: number
                    format: double
                transactionCode:
                    type: string
                transactionDate:
                    type: string
        worldmonitor_market_v1_GetMarketBreadthHistoryRequest:
            type: object
        worldmonitor_market_v1_GetMarketBreadthHistoryResponse:
            type: object
            properties:
                currentPctAbove20d:
                    type: number
                    format: double
                currentPctAbove50d:
                    type: number
                    format: double
                currentPctAbove200d:
                    type: number
                    format: double
                updatedAt:
                    type: string
                history:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_BreadthSnapshot'
                unavailable:
                    type: boolean
                    description: |-
                        True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
        worldmonitor_market_v1_BreadthSnapshot:
            type: object
            properties:
                date:
                    type: string
                pctAbove20d:
                    type: number
                    format: double
                    description: |-
                        Optional so a missing/failed Barchart reading serializes as JSON null
                         instead of collapsing to 0, which would render identically to a real 0%
                         reading (severe market dislocation with no S&P stocks above SMA).
                pctAbove50d:
                    type: number
                    format: double
                pctAbove200d:
                    type: number
                    format: double
        worldmonitor_market_v1_GetGoldIntelligenceRequest:
            type: object
        worldmonitor_market_v1_GetGoldIntelligenceResponse:
            type: object
            properties:
                goldPrice:
                    type: number
                    format: double
                goldChangePct:
                    type: number
                    format: double
                goldSparkline:
                    type: array
                    items:
                        type: number
                        format: double
                silverPrice:
                    type: number
                    format: double
                platinumPrice:
                    type: number
                    format: double
                palladiumPrice:
                    type: number
                    format: double
                goldSilverRatio:
                    type: number
                    format: double
                goldPlatinumPremiumPct:
                    type: number
                    format: double
                crossCurrencyPrices:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_GoldCrossCurrencyPrice'
                cot:
                    $ref: '#/components/schemas/worldmonitor_market_v1_GoldCotPositioning'
                updatedAt:
                    type: string
                unavailable:
                    type: boolean
                    description: |-
                        True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
                session:
                    $ref: '#/components/schemas/worldmonitor_market_v1_GoldSessionRange'
                returns:
                    $ref: '#/components/schemas/worldmonitor_market_v1_GoldReturns'
                range52w:
                    $ref: '#/components/schemas/worldmonitor_market_v1_GoldRange52w'
                drivers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_GoldDriver'
                etfFlows:
                    $ref: '#/components/schemas/worldmonitor_market_v1_GoldEtfFlows'
                cbReserves:
                    $ref: '#/components/schemas/worldmonitor_market_v1_GoldCbReserves'
        worldmonitor_market_v1_GoldCrossCurrencyPrice:
            type: object
            properties:
                currency:
                    type: string
                flag:
                    type: string
                price:
                    type: number
                    format: double
        worldmonitor_market_v1_GoldCotPositioning:
            type: object
            properties:
                reportDate:
                    type: string
                nextReleaseDate:
                    type: string
                openInterest:
                    type: string
                    format: int64
                managedMoney:
                    $ref: '#/components/schemas/worldmonitor_market_v1_GoldCotCategory'
                producerSwap:
                    $ref: '#/components/schemas/worldmonitor_market_v1_GoldCotCategory'
        worldmonitor_market_v1_GoldCotCategory:
            type: object
            properties:
                longPositions:
                    type: string
                    format: int64
                shortPositions:
                    type: string
                    format: int64
                netPct:
                    type: number
                    format: double
                oiSharePct:
                    type: number
                    format: double
                wowNetDelta:
                    type: string
                    format: int64
        worldmonitor_market_v1_GoldSessionRange:
            type: object
            properties:
                dayHigh:
                    type: number
                    format: double
                dayLow:
                    type: number
                    format: double
                prevClose:
                    type: number
                    format: double
        worldmonitor_market_v1_GoldReturns:
            type: object
            properties:
                w1:
                    type: number
                    format: double
                m1:
                    type: number
                    format: double
                ytd:
                    type: number
                    format: double
                y1:
                    type: number
                    format: double
        worldmonitor_market_v1_GoldRange52w:
            type: object
            properties:
                hi:
                    type: number
                    format: double
                lo:
                    type: number
                    format: double
                positionPct:
                    type: number
                    format: double
        worldmonitor_market_v1_GoldDriver:
            type: object
            properties:
                symbol:
                    type: string
                label:
                    type: string
                value:
                    type: number
                    format: double
                changePct:
                    type: number
                    format: double
                correlation30d:
                    type: number
                    format: double
        worldmonitor_market_v1_GoldEtfFlows:
            type: object
            properties:
                asOfDate:
                    type: string
                tonnes:
                    type: number
                    format: double
                aumUsd:
                    type: number
                    format: double
                nav:
                    type: number
                    format: double
                changeW1Tonnes:
                    type: number
                    format: double
                changeM1Tonnes:
                    type: number
                    format: double
                changeY1Tonnes:
                    type: number
                    format: double
                changeW1Pct:
                    type: number
                    format: double
                changeM1Pct:
                    type: number
                    format: double
                changeY1Pct:
                    type: number
                    format: double
                sparkline90d:
                    type: array
                    items:
                        type: number
                        format: double
        worldmonitor_market_v1_GoldCbReserves:
            type: object
            properties:
                asOfMonth:
                    type: string
                totalTonnes:
                    type: number
                    format: double
                topHolders:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_GoldCbHolder'
                topBuyers12m:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_GoldCbMover'
                topSellers12m:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_GoldCbMover'
        worldmonitor_market_v1_GoldCbHolder:
            type: object
            properties:
                iso3:
                    type: string
                name:
                    type: string
                tonnes:
                    type: number
                    format: double
                pctOfReserves:
                    type: number
                    format: double
        worldmonitor_market_v1_GoldCbMover:
            type: object
            properties:
                iso3:
                    type: string
                name:
                    type: string
                deltaTonnes12m:
                    type: number
                    format: double
        worldmonitor_market_v1_GetHyperliquidFlowRequest:
            type: object
        worldmonitor_market_v1_GetHyperliquidFlowResponse:
            type: object
            properties:
                ts:
                    type: string
                    format: int64
                fetchedAt:
                    type: string
                warmup:
                    type: boolean
                assetCount:
                    type: integer
                    format: int32
                assets:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_market_v1_HyperliquidAssetFlow'
                unavailable:
                    type: boolean
                    description: |-
                        True when the upstream or seed-backed variant is unavailable; empty payload fields
                         are graceful degradation, not confirmed zero data.
        worldmonitor_market_v1_HyperliquidAssetFlow:
            type: object
            properties:
                symbol:
                    type: string
                display:
                    type: string
                assetClass:
                    type: string
                group:
                    type: string
                funding:
                    type: string
                    description: Raw metrics (nullable as strings to preserve precision; "" = unavailable)
                openInterest:
                    type: string
                markPx:
                    type: string
                oraclePx:
                    type: string
                dayNotional:
                    type: string
                fundingScore:
                    type: number
                    format: double
                    description: Component scores 0-100
                volumeScore:
                    type: number
                    format: double
                oiScore:
                    type: number
                    format: double
                basisScore:
                    type: number
                    format: double
                composite:
                    type: number
                    format: double
                sparkFunding:
                    type: array
                    items:
                        type: number
                        format: double
                        description: Sparkline arrays (most recent last); up to 60 samples (5h @ 5min)
                sparkOi:
                    type: array
                    items:
                        type: number
                        format: double
                sparkScore:
                    type: array
                    items:
                        type: number
                        format: double
                warmup:
                    type: boolean
                    description: State flags
                stale:
                    type: boolean
                staleSince:
                    type: string
                    format: int64
                missingPolls:
                    type: integer
                    format: int32
                alerts:
                    type: array
                    items:
                        type: string
        worldmonitor_military_v1_ListMilitaryFlightsRequest:
            type: object
            properties:
                pageSize:
                    type: integer
                    format: int32
                    description: Maximum items per page (1-100).
                cursor:
                    type: string
                    description: |-
                        Cursor for next page.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                neLat:
                    type: number
                    format: double
                    description: North-east corner latitude of bounding box.
                neLon:
                    type: number
                    format: double
                    description: North-east corner longitude of bounding box.
                swLat:
                    type: number
                    format: double
                    description: South-west corner latitude of bounding box.
                swLon:
                    type: number
                    format: double
                    description: South-west corner longitude of bounding box.
                operator:
                    type: string
                    enum:
                        - MILITARY_OPERATOR_UNSPECIFIED
                        - MILITARY_OPERATOR_USAF
                        - MILITARY_OPERATOR_USN
                        - MILITARY_OPERATOR_USMC
                        - MILITARY_OPERATOR_USA
                        - MILITARY_OPERATOR_RAF
                        - MILITARY_OPERATOR_RN
                        - MILITARY_OPERATOR_FAF
                        - MILITARY_OPERATOR_GAF
                        - MILITARY_OPERATOR_PLAAF
                        - MILITARY_OPERATOR_PLAN
                        - MILITARY_OPERATOR_VKS
                        - MILITARY_OPERATOR_IAF
                        - MILITARY_OPERATOR_NATO
                        - MILITARY_OPERATOR_OTHER
                    description: MilitaryOperator represents the military branch or force operating an asset.
                aircraftType:
                    type: string
                    enum:
                        - MILITARY_AIRCRAFT_TYPE_UNSPECIFIED
                        - MILITARY_AIRCRAFT_TYPE_FIGHTER
                        - MILITARY_AIRCRAFT_TYPE_BOMBER
                        - MILITARY_AIRCRAFT_TYPE_TRANSPORT
                        - MILITARY_AIRCRAFT_TYPE_TANKER
                        - MILITARY_AIRCRAFT_TYPE_AWACS
                        - MILITARY_AIRCRAFT_TYPE_RECONNAISSANCE
                        - MILITARY_AIRCRAFT_TYPE_HELICOPTER
                        - MILITARY_AIRCRAFT_TYPE_DRONE
                        - MILITARY_AIRCRAFT_TYPE_PATROL
                        - MILITARY_AIRCRAFT_TYPE_SPECIAL_OPS
                        - MILITARY_AIRCRAFT_TYPE_VIP
                        - MILITARY_AIRCRAFT_TYPE_UNKNOWN
                    description: MilitaryAircraftType represents the classification of a military aircraft.
            description: ListMilitaryFlightsRequest specifies filters for retrieving military flight data.
        worldmonitor_military_v1_ListMilitaryFlightsResponse:
            type: object
            properties:
                flights:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_military_v1_MilitaryFlight'
                clusters:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_military_v1_MilitaryFlightCluster'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListMilitaryFlightsResponse contains military flights and clusters.
        worldmonitor_military_v1_MilitaryFlight:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Unique flight identifier.
                callsign:
                    type: string
                    description: Aircraft callsign.
                hexCode:
                    type: string
                    description: |-
                        ICAO 24-bit hex address. Canonical form is UPPERCASE — seeders and
                         handlers must uppercase before writing so hex-based lookups
                         (src/services/military-flights.ts:getFlightByHex) match regardless of
                         upstream source casing.
                registration:
                    type: string
                    description: Aircraft registration number.
                aircraftType:
                    type: string
                    enum:
                        - MILITARY_AIRCRAFT_TYPE_UNSPECIFIED
                        - MILITARY_AIRCRAFT_TYPE_FIGHTER
                        - MILITARY_AIRCRAFT_TYPE_BOMBER
                        - MILITARY_AIRCRAFT_TYPE_TRANSPORT
                        - MILITARY_AIRCRAFT_TYPE_TANKER
                        - MILITARY_AIRCRAFT_TYPE_AWACS
                        - MILITARY_AIRCRAFT_TYPE_RECONNAISSANCE
                        - MILITARY_AIRCRAFT_TYPE_HELICOPTER
                        - MILITARY_AIRCRAFT_TYPE_DRONE
                        - MILITARY_AIRCRAFT_TYPE_PATROL
                        - MILITARY_AIRCRAFT_TYPE_SPECIAL_OPS
                        - MILITARY_AIRCRAFT_TYPE_VIP
                        - MILITARY_AIRCRAFT_TYPE_UNKNOWN
                    description: MilitaryAircraftType represents the classification of a military aircraft.
                aircraftModel:
                    type: string
                    description: Specific aircraft model (e.g., "F-35A", "C-17A").
                operator:
                    type: string
                    enum:
                        - MILITARY_OPERATOR_UNSPECIFIED
                        - MILITARY_OPERATOR_USAF
                        - MILITARY_OPERATOR_USN
                        - MILITARY_OPERATOR_USMC
                        - MILITARY_OPERATOR_USA
                        - MILITARY_OPERATOR_RAF
                        - MILITARY_OPERATOR_RN
                        - MILITARY_OPERATOR_FAF
                        - MILITARY_OPERATOR_GAF
                        - MILITARY_OPERATOR_PLAAF
                        - MILITARY_OPERATOR_PLAN
                        - MILITARY_OPERATOR_VKS
                        - MILITARY_OPERATOR_IAF
                        - MILITARY_OPERATOR_NATO
                        - MILITARY_OPERATOR_OTHER
                    description: MilitaryOperator represents the military branch or force operating an asset.
                operatorCountry:
                    type: string
                    description: Country operating the aircraft (ISO 3166-1 alpha-2).
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                altitude:
                    type: number
                    format: double
                    description: Altitude in feet.
                heading:
                    type: number
                    format: double
                    description: Heading in degrees.
                speed:
                    type: number
                    format: double
                    description: Speed in knots.
                verticalRate:
                    type: number
                    format: double
                    description: Vertical rate in feet per minute.
                onGround:
                    type: boolean
                    description: Whether the aircraft is on the ground.
                squawk:
                    type: string
                    description: Transponder squawk code.
                origin:
                    type: string
                    description: ICAO code of the origin airport.
                destination:
                    type: string
                    description: ICAO code of the destination airport.
                lastSeenAt:
                    type: integer
                    format: int64
                    description: 'Last seen time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                firstSeenAt:
                    type: integer
                    format: int64
                    description: 'First seen time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                confidence:
                    type: string
                    enum:
                        - MILITARY_CONFIDENCE_UNSPECIFIED
                        - MILITARY_CONFIDENCE_LOW
                        - MILITARY_CONFIDENCE_MEDIUM
                        - MILITARY_CONFIDENCE_HIGH
                    description: MilitaryConfidence represents confidence in asset identification.
                isInteresting:
                    type: boolean
                    description: Whether flagged for unusual activity.
                note:
                    type: string
                    description: Analyst note.
                enrichment:
                    $ref: '#/components/schemas/worldmonitor_military_v1_FlightEnrichment'
            required:
                - id
            description: MilitaryFlight represents a tracked military aircraft from OpenSky or Wingbits.
        worldmonitor_military_v1_FlightEnrichment:
            type: object
            properties:
                manufacturer:
                    type: string
                    description: Aircraft manufacturer.
                owner:
                    type: string
                    description: Registered owner.
                operatorName:
                    type: string
                    description: Operator name.
                typeCode:
                    type: string
                    description: ICAO type code.
                builtYear:
                    type: string
                    description: Year the aircraft was built.
                confirmedMilitary:
                    type: boolean
                    description: Whether confirmed as military.
                militaryBranch:
                    type: string
                    description: Military branch designation.
            description: FlightEnrichment contains additional data from Wingbits aircraft database.
        worldmonitor_military_v1_MilitaryFlightCluster:
            type: object
            properties:
                id:
                    type: string
                    description: Unique cluster identifier.
                name:
                    type: string
                    description: Descriptive name of the cluster.
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                flightCount:
                    type: integer
                    format: int32
                    description: Number of flights in the cluster.
                flights:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_military_v1_MilitaryFlight'
                dominantOperator:
                    type: string
                    enum:
                        - MILITARY_OPERATOR_UNSPECIFIED
                        - MILITARY_OPERATOR_USAF
                        - MILITARY_OPERATOR_USN
                        - MILITARY_OPERATOR_USMC
                        - MILITARY_OPERATOR_USA
                        - MILITARY_OPERATOR_RAF
                        - MILITARY_OPERATOR_RN
                        - MILITARY_OPERATOR_FAF
                        - MILITARY_OPERATOR_GAF
                        - MILITARY_OPERATOR_PLAAF
                        - MILITARY_OPERATOR_PLAN
                        - MILITARY_OPERATOR_VKS
                        - MILITARY_OPERATOR_IAF
                        - MILITARY_OPERATOR_NATO
                        - MILITARY_OPERATOR_OTHER
                    description: MilitaryOperator represents the military branch or force operating an asset.
                activityType:
                    type: string
                    enum:
                        - MILITARY_ACTIVITY_TYPE_UNSPECIFIED
                        - MILITARY_ACTIVITY_TYPE_EXERCISE
                        - MILITARY_ACTIVITY_TYPE_PATROL
                        - MILITARY_ACTIVITY_TYPE_TRANSPORT
                        - MILITARY_ACTIVITY_TYPE_DEPLOYMENT
                        - MILITARY_ACTIVITY_TYPE_TRANSIT
                        - MILITARY_ACTIVITY_TYPE_UNKNOWN
                    description: MilitaryActivityType represents the assessed type of military activity.
            description: MilitaryFlightCluster represents a geographic cluster of military flights.
        worldmonitor_military_v1_GetTheaterPostureRequest:
            type: object
            properties:
                theater:
                    type: string
                    description: |-
                        Theater name (e.g., "indo-pacific", "european", "middle-east"). Empty for all theaters.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
            description: GetTheaterPostureRequest specifies the theater to assess.
        worldmonitor_military_v1_GetTheaterPostureResponse:
            type: object
            properties:
                theaters:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_military_v1_TheaterPosture'
            description: GetTheaterPostureResponse contains theater posture assessments.
        worldmonitor_military_v1_TheaterPosture:
            type: object
            properties:
                theater:
                    type: string
                    description: Theater name (e.g., "Indo-Pacific", "European", "Middle East").
                postureLevel:
                    type: string
                    description: Overall posture assessment.
                activeFlights:
                    type: integer
                    format: int32
                    description: Number of active flights in the theater.
                trackedVessels:
                    type: integer
                    format: int32
                    description: Number of tracked vessels in the theater.
                activeOperations:
                    type: array
                    items:
                        type: string
                        description: Notable ongoing operations.
                assessedAt:
                    type: integer
                    format: int64
                    description: 'Assessment timestamp, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: TheaterPosture represents an assessed military posture for a geographic theater.
        worldmonitor_military_v1_GetAircraftDetailsRequest:
            type: object
            properties:
                icao24:
                    type: string
                    minLength: 1
                    description: ICAO 24-bit hex address (lowercase).
            required:
                - icao24
            description: GetAircraftDetailsRequest looks up a single aircraft by ICAO 24-bit hex.
        worldmonitor_military_v1_GetAircraftDetailsResponse:
            type: object
            properties:
                details:
                    $ref: '#/components/schemas/worldmonitor_military_v1_AircraftDetails'
                configured:
                    type: boolean
                    description: Whether the Wingbits API is configured.
            description: GetAircraftDetailsResponse contains the aircraft enrichment data.
        worldmonitor_military_v1_AircraftDetails:
            type: object
            properties:
                icao24:
                    type: string
                    description: ICAO 24-bit hex address.
                registration:
                    type: string
                    description: Aircraft registration number.
                manufacturerIcao:
                    type: string
                    description: ICAO manufacturer code.
                manufacturerName:
                    type: string
                    description: Full manufacturer name.
                model:
                    type: string
                    description: Aircraft model.
                typecode:
                    type: string
                    description: ICAO type designator code.
                serialNumber:
                    type: string
                    description: Manufacturer serial number.
                icaoAircraftType:
                    type: string
                    description: ICAO aircraft type designator.
                operator:
                    type: string
                    description: Operator name.
                operatorCallsign:
                    type: string
                    description: Operator callsign.
                operatorIcao:
                    type: string
                    description: Operator ICAO code.
                owner:
                    type: string
                    description: Registered owner.
                built:
                    type: string
                    description: Build date.
                engines:
                    type: string
                    description: Engine description.
                categoryDescription:
                    type: string
                    description: ICAO category description.
            description: AircraftDetails contains Wingbits aircraft enrichment data.
        worldmonitor_military_v1_GetAircraftDetailsBatchRequest:
            type: object
            properties:
                icao24s:
                    type: array
                    items:
                        type: string
                        maxItems: 20
                        minItems: 1
                        description: |-
                            ICAO 24-bit hex addresses (lowercase). Up to 20 are accepted by validation, but the
                             handler de-duplicates, sorts, and processes at most the first 10 addresses.
                    maxItems: 20
                    minItems: 1
            description: GetAircraftDetailsBatchRequest looks up multiple aircraft by ICAO 24-bit hex.
        worldmonitor_military_v1_GetAircraftDetailsBatchResponse:
            type: object
            properties:
                results:
                    type: object
                    additionalProperties:
                        $ref: '#/components/schemas/worldmonitor_military_v1_AircraftDetails'
                    description: Map of icao24 -> aircraft details for found aircraft.
                fetched:
                    type: integer
                    format: int32
                    description: Number of aircraft successfully fetched from upstream.
                requested:
                    type: integer
                    format: int32
                    description: Number of aircraft requested.
                configured:
                    type: boolean
                    description: Whether the Wingbits API is configured.
            description: GetAircraftDetailsBatchResponse contains the batch lookup results.
        worldmonitor_military_v1_GetAircraftDetailsBatchResponse_ResultsEntry:
            type: object
            properties:
                key:
                    type: string
                value:
                    $ref: '#/components/schemas/worldmonitor_military_v1_AircraftDetails'
        worldmonitor_military_v1_GetWingbitsStatusRequest:
            type: object
            description: GetWingbitsStatusRequest checks whether the Wingbits enrichment API is configured.
        worldmonitor_military_v1_GetWingbitsStatusResponse:
            type: object
            properties:
                configured:
                    type: boolean
                    description: Whether the Wingbits API key is configured on the server.
            description: GetWingbitsStatusResponse indicates whether Wingbits is available.
        worldmonitor_military_v1_GetUSNIFleetReportRequest:
            type: object
            properties:
                forceRefresh:
                    type: boolean
                    description: When true, bypass cache and fetch fresh data from USNI.
            description: GetUSNIFleetReportRequest requests the latest USNI Fleet Tracker report.
        worldmonitor_military_v1_GetUSNIFleetReportResponse:
            type: object
            properties:
                report:
                    $ref: '#/components/schemas/worldmonitor_military_v1_USNIFleetReport'
                cached:
                    type: boolean
                    description: Whether the response was served from cache.
                stale:
                    type: boolean
                    description: Whether the cached data is stale (served after a fetch failure).
                error:
                    type: string
                    description: Error message, if any.
            description: GetUSNIFleetReportResponse returns the parsed USNI Fleet Tracker report.
        worldmonitor_military_v1_USNIFleetReport:
            type: object
            properties:
                articleUrl:
                    type: string
                    description: URL of the source article.
                articleDate:
                    type: string
                    description: Publication date of the article.
                articleTitle:
                    type: string
                    description: Title of the article.
                battleForceSummary:
                    $ref: '#/components/schemas/worldmonitor_military_v1_BattleForceSummary'
                vessels:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_military_v1_USNIVessel'
                strikeGroups:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_military_v1_USNIStrikeGroup'
                regions:
                    type: array
                    items:
                        type: string
                        description: Unique region names mentioned in the article.
                parsingWarnings:
                    type: array
                    items:
                        type: string
                        description: Warnings generated during parsing.
                timestamp:
                    type: integer
                    format: int64
                    description: 'Time the report was generated, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: USNIFleetReport is the full parsed output of a USNI Fleet Tracker article.
        worldmonitor_military_v1_BattleForceSummary:
            type: object
            properties:
                totalShips:
                    type: integer
                    minimum: 0
                    format: int32
                    description: Total ships in the battle force.
                deployed:
                    type: integer
                    minimum: 0
                    format: int32
                    description: Number of ships currently deployed.
                underway:
                    type: integer
                    minimum: 0
                    format: int32
                    description: Number of ships currently underway.
            description: BattleForceSummary contains fleet-wide ship count statistics.
        worldmonitor_military_v1_USNIVessel:
            type: object
            properties:
                name:
                    type: string
                    minLength: 1
                    description: Vessel name (e.g., "USS Abraham Lincoln").
                hullNumber:
                    type: string
                    minLength: 1
                    description: Hull designation (e.g., "CVN-72", "DDG-51").
                vesselType:
                    type: string
                    description: Vessel type classification (e.g., "carrier", "destroyer", "submarine").
                region:
                    type: string
                    description: Region name where the vessel is operating.
                regionLat:
                    type: number
                    format: double
                    description: Approximate latitude for the region.
                regionLon:
                    type: number
                    format: double
                    description: Approximate longitude for the region.
                deploymentStatus:
                    type: string
                    description: Deployment status (e.g., "deployed", "underway", "in-port", "unknown").
                homePort:
                    type: string
                    description: Home port, if identified from the article text.
                strikeGroup:
                    type: string
                    description: Strike group assignment, if any.
                activityDescription:
                    type: string
                    description: Brief activity description parsed from article prose.
                articleUrl:
                    type: string
                    description: URL of the USNI article this vessel was parsed from.
                articleDate:
                    type: string
                    description: Publication date of the USNI article.
            required:
                - name
                - hullNumber
            description: USNIVessel represents a single vessel parsed from a USNI Fleet Tracker article.
        worldmonitor_military_v1_USNIStrikeGroup:
            type: object
            properties:
                name:
                    type: string
                    description: Strike group name (e.g., "Abraham Lincoln Carrier Strike Group").
                carrier:
                    type: string
                    description: Carrier name and hull (e.g., "USS Abraham Lincoln (CVN-72)").
                airWing:
                    type: string
                    description: Assigned air wing (e.g., "Carrier Air Wing Nine").
                destroyerSquadron:
                    type: string
                    description: Assigned destroyer squadron.
                escorts:
                    type: array
                    items:
                        type: string
                        description: Escort vessels in the strike group.
            description: USNIStrikeGroup represents a carrier strike group parsed from the article.
        worldmonitor_military_v1_ListMilitaryBasesRequest:
            type: object
            properties:
                neLat:
                    type: number
                    format: double
                    description: North-east corner latitude of the map bounding box.
                neLon:
                    type: number
                    format: double
                    description: North-east corner longitude of the map bounding box.
                swLat:
                    type: number
                    format: double
                    description: South-west corner latitude of the map bounding box.
                swLon:
                    type: number
                    format: double
                    description: South-west corner longitude of the map bounding box.
                zoom:
                    type: integer
                    format: int32
                    description: Map zoom level used to decide whether to return bases or clusters.
                type:
                    type: string
                    description: Optional military base type filter.
                kind:
                    type: string
                    description: Optional military base kind filter.
                country:
                    type: string
                    description: Optional country filter for military bases.
        worldmonitor_military_v1_ListMilitaryBasesResponse:
            type: object
            properties:
                bases:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_military_v1_MilitaryBaseEntry'
                clusters:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_military_v1_MilitaryBaseCluster'
                totalInView:
                    type: integer
                    format: int32
                truncated:
                    type: boolean
        worldmonitor_military_v1_MilitaryBaseEntry:
            type: object
            properties:
                id:
                    type: string
                name:
                    type: string
                latitude:
                    type: number
                    format: double
                longitude:
                    type: number
                    format: double
                kind:
                    type: string
                countryIso2:
                    type: string
                type:
                    type: string
                tier:
                    type: integer
                    format: int32
                catAirforce:
                    type: boolean
                catNaval:
                    type: boolean
                catNuclear:
                    type: boolean
                catSpace:
                    type: boolean
                catTraining:
                    type: boolean
                branch:
                    type: string
                status:
                    type: string
        worldmonitor_military_v1_MilitaryBaseCluster:
            type: object
            properties:
                latitude:
                    type: number
                    format: double
                longitude:
                    type: number
                    format: double
                count:
                    type: integer
                    format: int32
                dominantType:
                    type: string
                expansionZoom:
                    type: integer
                    format: int32
        worldmonitor_military_v1_GetWingbitsLiveFlightRequest:
            type: object
            properties:
                icao24:
                    type: string
                    minLength: 1
                    description: ICAO 24-bit hex address (lowercase, 6 characters).
            required:
                - icao24
            description: GetWingbitsLiveFlightRequest fetches live Wingbits ECS data for a single aircraft.
        worldmonitor_military_v1_GetWingbitsLiveFlightResponse:
            type: object
            properties:
                flight:
                    $ref: '#/components/schemas/worldmonitor_military_v1_WingbitsLiveFlight'
            description: GetWingbitsLiveFlightResponse contains the live flight data, if available.
        worldmonitor_military_v1_WingbitsLiveFlight:
            type: object
            properties:
                icao24:
                    type: string
                    description: ICAO 24-bit hex address.
                callsign:
                    type: string
                    description: Live callsign.
                lat:
                    type: number
                    format: double
                    description: Latitude in decimal degrees.
                lon:
                    type: number
                    format: double
                    description: Longitude in decimal degrees.
                altitude:
                    type: number
                    format: double
                    description: Altitude in feet.
                speed:
                    type: number
                    format: double
                    description: Ground speed in knots.
                heading:
                    type: number
                    format: double
                    description: Track/heading in degrees.
                verticalRate:
                    type: number
                    format: double
                    description: Vertical rate in feet per minute (positive = climb, negative = descent).
                registration:
                    type: string
                    description: Aircraft registration number.
                model:
                    type: string
                    description: Aircraft model (e.g. "PC-12/45").
                operator:
                    type: string
                    description: Operator name.
                onGround:
                    type: boolean
                    description: True if the aircraft is on the ground.
                lastSeen:
                    type: string
                    format: int64
                    description: Unix timestamp of the last position update.
                depIata:
                    type: string
                    description: |-
                        Schedule — from ecs-api.wingbits.com/v1/flights/schedule/{callsign}
                         Departure airport IATA code (e.g. "FJR").
                arrIata:
                    type: string
                    description: Arrival airport IATA code (e.g. "BOM").
                depTimeUtc:
                    type: string
                    description: Scheduled departure time UTC (ISO 8601).
                arrTimeUtc:
                    type: string
                    description: Scheduled arrival time UTC (ISO 8601).
                depEstimatedUtc:
                    type: string
                    description: Estimated departure time UTC (ISO 8601).
                arrEstimatedUtc:
                    type: string
                    description: Estimated arrival time UTC (ISO 8601).
                depDelayedMin:
                    type: integer
                    format: int32
                    description: Departure delay in minutes (negative = early).
                arrDelayedMin:
                    type: integer
                    format: int32
                    description: Arrival delay in minutes (negative = early).
                flightStatus:
                    type: string
                    description: Flight status string (e.g. "en-route", "landed", "scheduled").
                flightDurationMin:
                    type: integer
                    format: int32
                    description: Scheduled flight duration in minutes.
                arrTerminal:
                    type: string
                    description: Arrival terminal (e.g. "2").
                photoUrl:
                    type: string
                    description: |-
                        Photo — from api.planespotters.net/pub/photos/hex/{icao24}
                         Aircraft photo URL (large thumbnail ~497x280).
                photoLink:
                    type: string
                    description: Permalink to the photo page on planespotters.net.
                photoCredit:
                    type: string
                    description: Photographer credit name.
                callsignIata:
                    type: string
                    description: |-
                        Airline — resolved server-side from the ICAO callsign prefix.
                         IATA-equivalent callsign (e.g. "EK528" for ICAO "UAE528"). Empty if no mapping.
                airlineName:
                    type: string
                    description: Airline name (e.g. "Emirates"). Empty if no mapping.
            description: WingbitsLiveFlight contains real-time flight position data from the Wingbits ECS network.
        worldmonitor_military_v1_ListDefensePatentsRequest:
            type: object
            properties:
                cpcCode:
                    type: string
                    description: CPC category filter (e.g. "H04B", "F42B"). Empty returns all categories.
                assignee:
                    type: string
                    description: Assignee keyword filter (case-insensitive substring match). Empty returns all.
                limit:
                    type: integer
                    format: int32
                    description: Maximum results to return (default 20, max 100).
            description: ListDefensePatentsRequest filters defense/dual-use patent filings.
        worldmonitor_military_v1_ListDefensePatentsResponse:
            type: object
            properties:
                patents:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_military_v1_DefensePatentFiling'
                total:
                    type: integer
                    format: int32
                    description: Total number of filings in the seeded dataset.
                fetchedAt:
                    type: string
                    description: ISO 8601 timestamp when data was seeded.
            description: ListDefensePatentsResponse contains recent defense/dual-use patent filings.
        worldmonitor_military_v1_DefensePatentFiling:
            type: object
            properties:
                patentId:
                    type: string
                    description: USPTO patent ID.
                title:
                    type: string
                    description: Patent title.
                date:
                    type: string
                    description: Filing date (YYYY-MM-DD).
                assignee:
                    type: string
                    description: Primary assignee organization name.
                cpcCode:
                    type: string
                    description: CPC classification code (e.g. "H04B", "F42B").
                cpcDesc:
                    type: string
                    description: CPC class description.
                abstract:
                    type: string
                    description: Patent abstract (truncated to 500 chars).
                url:
                    type: string
                    description: USPTO patent URL.
            description: DefensePatentFiling is a single patent filing from a defense/dual-use organization.
        worldmonitor_natural_v1_ListNaturalEventsRequest:
            type: object
            properties:
                days:
                    type: integer
                    format: int32
                    description: Accepted but currently ignored; no-op until this handler supports the parameter.
        worldmonitor_natural_v1_ListNaturalEventsResponse:
            type: object
            properties:
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_natural_v1_NaturalEvent'
                fetchedAt:
                    type: integer
                    format: int64
                    description: |-
                        Time the seed snapshot was fetched, as Unix epoch milliseconds. A value of
                         0 means the snapshot is unavailable/degraded, not that there are confirmed
                         zero natural events.. Warning: Values > 2^53 may lose precision in JavaScript
                dataAvailable:
                    type: boolean
                    description: |-
                        True when events came from a seed snapshot. False means an empty payload is
                         graceful degradation because the snapshot is unavailable.
        worldmonitor_natural_v1_NaturalEvent:
            type: object
            properties:
                id:
                    type: string
                title:
                    type: string
                description:
                    type: string
                category:
                    type: string
                categoryTitle:
                    type: string
                lat:
                    type: number
                    format: double
                lon:
                    type: number
                    format: double
                date:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                magnitude:
                    type: number
                    format: double
                magnitudeUnit:
                    type: string
                sourceUrl:
                    type: string
                sourceName:
                    type: string
                closed:
                    type: boolean
                stormId:
                    type: string
                    description: Optional tropical cyclone fields (populated for severeStorms from GDACS TC / NHC)
                stormName:
                    type: string
                basin:
                    type: string
                stormCategory:
                    type: integer
                    format: int32
                classification:
                    type: string
                windKt:
                    type: integer
                    format: int32
                pressureMb:
                    type: integer
                    format: int32
                movementDir:
                    type: integer
                    format: int32
                movementSpeedKt:
                    type: integer
                    format: int32
                forecastTrack:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_natural_v1_ForecastPoint'
                conePolygon:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_natural_v1_CoordRing'
                pastTrack:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_natural_v1_PastTrackPoint'
        worldmonitor_natural_v1_ForecastPoint:
            type: object
            properties:
                lat:
                    type: number
                    format: double
                lon:
                    type: number
                    format: double
                hour:
                    type: integer
                    format: int32
                windKt:
                    type: integer
                    format: int32
                category:
                    type: integer
                    format: int32
        worldmonitor_natural_v1_CoordRing:
            type: object
            properties:
                points:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_natural_v1_Coordinate'
        worldmonitor_natural_v1_Coordinate:
            type: object
            properties:
                lon:
                    type: number
                    format: double
                lat:
                    type: number
                    format: double
        worldmonitor_natural_v1_PastTrackPoint:
            type: object
            properties:
                lat:
                    type: number
                    format: double
                lon:
                    type: number
                    format: double
                windKt:
                    type: integer
                    format: int32
                timestamp:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
        worldmonitor_news_v1_SummarizeArticleRequest:
            type: object
            properties:
                provider:
                    type: string
                    minLength: 1
                    description: 'LLM provider: "ollama", "groq", "openrouter"'
                headlines:
                    type: array
                    items:
                        type: string
                        minItems: 1
                        description: |-
                            Headlines to summarize. Up to 10 raw headlines are used for request
                             identity/cache matching; the LLM prompt uses up to 5 unique, non-empty
                             sanitized headline/body pairs.
                    minItems: 1
                mode:
                    type: string
                    description: 'Summarization mode: "brief", "analysis", "translate", "" (default).'
                geoContext:
                    type: string
                    description: Geographic signal context to include in the prompt.
                variant:
                    type: string
                    description: 'Variant: "full", "tech", or target language for translate mode.'
                lang:
                    type: string
                    description: Output language code, default "en".
                systemAppend:
                    type: string
                    description: Optional system prompt append for analytical framework instructions.
                bodies:
                    type: array
                    items:
                        type: string
                        description: |-
                            Optional article bodies paired 1:1 with `headlines`. When bodies[i] is
                             non-empty, the prompt interleaves it as grounding context under
                             headlines[i]; when empty, behavior is identical to headline-only today.
                             Callers may supply a shorter array; missing entries are treated as empty.
                             Each body is subject to the same sanitisation as headlines before reaching
                             the LLM prompt.
            required:
                - provider
            description: SummarizeArticleRequest specifies parameters for LLM article summarization.
        worldmonitor_news_v1_SummarizeArticleResponse:
            type: object
            properties:
                summary:
                    type: string
                    description: The generated summary text.
                model:
                    type: string
                    description: Model identifier used for generation.
                provider:
                    type: string
                    description: Provider that produced the result (or "cache").
                tokens:
                    type: integer
                    format: int32
                    description: Token count from the LLM response.
                fallback:
                    type: boolean
                    description: Whether the client should try the next provider in the fallback chain.
                error:
                    type: string
                    description: Error message if the request failed.
                errorType:
                    type: string
                    description: Error type/name (e.g. "TypeError").
                status:
                    type: string
                    enum:
                        - SUMMARIZE_STATUS_UNSPECIFIED
                        - SUMMARIZE_STATUS_SUCCESS
                        - SUMMARIZE_STATUS_CACHED
                        - SUMMARIZE_STATUS_SKIPPED
                        - SUMMARIZE_STATUS_ERROR
                    description: SummarizeStatus indicates the outcome of a summarization request.
                statusDetail:
                    type: string
                    description: Human-readable detail for non-success statuses (skip reason, etc.).
            description: SummarizeArticleResponse contains the LLM summarization result.
        worldmonitor_news_v1_GetSummarizeArticleCacheRequest:
            type: object
            properties:
                cacheKey:
                    type: string
                    description: Deterministic cache key computed by buildSummaryCacheKey().
            description: GetSummarizeArticleCacheRequest looks up a pre-computed summary by cache key.
        worldmonitor_news_v1_ListFeedDigestRequest:
            type: object
            properties:
                variant:
                    type: string
                    description: 'Digest variant: full, tech, finance, happy, commodity. Unsupported site variants, including energy, currently fall back to full.'
                lang:
                    type: string
                    description: ISO 639-1 language code (en, fr, ar, etc.)
        worldmonitor_news_v1_ListFeedDigestResponse:
            type: object
            properties:
                categories:
                    type: object
                    additionalProperties:
                        $ref: '#/components/schemas/worldmonitor_news_v1_CategoryBucket'
                    description: Per-category buckets — keys match category names from feed config
                feedStatuses:
                    type: object
                    additionalProperties:
                        type: string
                    description: |-
                        Per-feed status — only non-ok states emitted; absent key implies ok.
                         Values: empty (feed returned 0 items), timeout (timed out during fetch),
                         all-undated (every parsed item lacked a usable date), partial-undated
                         (some parsed items lacked a usable date).
                generatedAt:
                    type: string
                    description: ISO 8601 timestamp of when this digest was generated
        worldmonitor_news_v1_ListFeedDigestResponse_CategoriesEntry:
            type: object
            properties:
                key:
                    type: string
                value:
                    $ref: '#/components/schemas/worldmonitor_news_v1_CategoryBucket'
        worldmonitor_news_v1_ListFeedDigestResponse_FeedStatusesEntry:
            type: object
            properties:
                key:
                    type: string
                value:
                    type: string
        worldmonitor_news_v1_CategoryBucket:
            type: object
            properties:
                items:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_news_v1_NewsItem'
        worldmonitor_news_v1_NewsItem:
            type: object
            properties:
                source:
                    type: string
                    minLength: 1
                    description: Source feed name.
                title:
                    type: string
                    minLength: 1
                    description: Article headline.
                link:
                    type: string
                    description: Article URL.
                publishedAt:
                    type: integer
                    format: int64
                    description: 'Publication time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                isAlert:
                    type: boolean
                    description: Whether this article triggered an alert condition.
                threat:
                    $ref: '#/components/schemas/worldmonitor_news_v1_ThreatClassification'
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                locationName:
                    type: string
                    description: Human-readable location name.
                importanceScore:
                    type: integer
                    format: int32
                    description: |-
                        Composite importance score. The base 0-100 score uses severity × 55% +
                         source tier × 20% + corroboration × 15% + recency × 10%, then may add an
                         18-point diplomacy/flashpoint boost and 4 points per entity-level
                         corroborating source, capped at five sources. The final score can exceed
                         100; with current boosts it is approximately capped at 138.
                corroborationCount:
                    type: integer
                    format: int32
                    description: |-
                        Number of distinct sources that reported the same story in this digest
                         cycle. "Same story" is determined by edit-tolerant story-identity
                         clustering (headlines describing one event with different wording,
                         ordering, source suffixes, truncation, or morphology corroborate each
                         other) — not exact-title matching. See shared/story-identity.js.
                storyMeta:
                    $ref: '#/components/schemas/worldmonitor_news_v1_StoryMeta'
                snippet:
                    type: string
                    description: |-
                        Cleaned article description from the RSS/Atom <description> /
                         <content:encoded> / <summary> / <content> tag: HTML-stripped,
                         entity-decoded, whitespace-normalised, clipped to 400 chars. Empty string
                         when unavailable or indistinguishable from the headline — consumers must
                         fall back to the headline for display/LLM grounding in that case.
                tickers:
                    type: array
                    items:
                        type: string
                        maxItems: 8
                        description: |-
                            Equity ticker symbols mentioned by the story, extracted at ingest from
                             cashtags ($AAPL) and the curated company dictionary
                             (shared/stocks.json). Uppercase symbols, deduplicated, capped at 8.
                             Empty when no tracked ticker is mentioned. See shared/ticker-extract.js.
                    maxItems: 8
            required:
                - source
                - title
            description: NewsItem represents a single news article from RSS feed aggregation.
        worldmonitor_news_v1_ThreatClassification:
            type: object
            properties:
                level:
                    type: string
                    enum:
                        - THREAT_LEVEL_UNSPECIFIED
                        - THREAT_LEVEL_LOW
                        - THREAT_LEVEL_MEDIUM
                        - THREAT_LEVEL_HIGH
                        - THREAT_LEVEL_CRITICAL
                    description: ThreatLevel represents the assessed threat level of a news event.
                category:
                    type: string
                    description: Event category.
                confidence:
                    type: number
                    maximum: 1
                    minimum: 0
                    format: double
                    description: Confidence score (0.0 to 1.0).
                source:
                    type: string
                    description: |-
                        Classification source — "keyword", "keyword-historical-downgrade", or
                         "llm".
            description: ThreatClassification represents an AI-assessed threat level for a news item.
        worldmonitor_news_v1_StoryMeta:
            type: object
            properties:
                firstSeen:
                    type: integer
                    format: int64
                    description: 'Epoch ms when the story first appeared in any digest cycle.. Warning: Values > 2^53 may lose precision in JavaScript'
                mentionCount:
                    type: integer
                    format: int32
                    description: Total number of digest cycles in which this story appeared.
                sourceCount:
                    type: integer
                    format: int32
                    description: |-
                        Number of unique sources reporting this story in the CURRENT digest
                         cycle (batch corroboration from fuzzy story clustering, #4919;
                         defaults to 1 for unclustered items). The cross-cycle Redis source
                         set (story:sources:v1) feeds importance scoring, not this field.
                phase:
                    type: string
                    enum:
                        - STORY_PHASE_UNSPECIFIED
                        - STORY_PHASE_BREAKING
                        - STORY_PHASE_DEVELOPING
                        - STORY_PHASE_SUSTAINED
                        - STORY_PHASE_FADING
                    description: StoryPhase represents the lifecycle stage of a tracked news story.
            description: StoryMeta carries cross-cycle persistence data attached to each news item.
        worldmonitor_positive_events_v1_ListPositiveGeoEventsRequest:
            type: object
        worldmonitor_positive_events_v1_ListPositiveGeoEventsResponse:
            type: object
            properties:
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_positive_events_v1_PositiveGeoEvent'
                fetchedAt:
                    type: integer
                    format: int64
                    description: |-
                        Unix epoch ms at which the underlying source data was last successfully
                         fetched. Always set when serving from cache or in-process fallback; 0 if
                         no data is available. Clients can use this to display a freshness
                         indicator or "data is X minutes old" warning. See issue #3706.. Warning: Values > 2^53 may lose precision in JavaScript
                stale:
                    type: boolean
                    description: |-
                        True when the response is being served from the in-process fallback
                         cache because the upstream source is unavailable or returned stale
                         data. Clients can surface a "data may be out of date" indicator. See
                         issue #3706.
        worldmonitor_positive_events_v1_PositiveGeoEvent:
            type: object
            properties:
                latitude:
                    type: number
                    format: double
                longitude:
                    type: number
                    format: double
                name:
                    type: string
                category:
                    type: string
                count:
                    type: integer
                    format: int32
                timestamp:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
        worldmonitor_prediction_v1_ListPredictionMarketsRequest:
            type: object
            properties:
                pageSize:
                    type: integer
                    format: int32
                    description: Maximum items per page (1-100).
                cursor:
                    type: string
                    description: |-
                        Cursor for next page.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                category:
                    type: string
                    description: Optional category filter (e.g., "Politics").
                query:
                    type: string
                    description: Optional search query for market titles.
            description: ListPredictionMarketsRequest specifies filters for retrieving prediction markets.
        worldmonitor_prediction_v1_ListPredictionMarketsResponse:
            type: object
            properties:
                markets:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_prediction_v1_PredictionMarket'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
                fetchedAt:
                    type: integer
                    format: int64
                    description: |-
                        Time the seed snapshot was fetched, as Unix epoch milliseconds. A value of
                         0 means the snapshot is unavailable/degraded, not that there are confirmed
                         zero matching markets.. Warning: Values > 2^53 may lose precision in JavaScript
                dataAvailable:
                    type: boolean
                    description: |-
                        True when markets were evaluated against a seed snapshot. False means an
                         empty payload is graceful degradation because the snapshot is unavailable.
            description: ListPredictionMarketsResponse contains prediction markets matching the request.
        worldmonitor_prediction_v1_PredictionMarket:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Unique market identifier or slug.
                title:
                    type: string
                    description: Market question or title.
                yesPrice:
                    type: number
                    maximum: 1
                    minimum: 0
                    format: double
                    description: Current "Yes" price (0.0 to 1.0, representing probability).
                volume:
                    type: number
                    minimum: 0
                    format: double
                    description: Trading volume in USD.
                url:
                    type: string
                    description: URL to the market page.
                closesAt:
                    type: integer
                    format: int64
                    description: 'Market close time, as Unix epoch milliseconds. Zero if no expiry.. Warning: Values > 2^53 may lose precision in JavaScript'
                category:
                    type: string
                    description: Market category (e.g., "Politics", "Crypto", "Sports").
                source:
                    type: string
                    enum:
                        - MARKET_SOURCE_UNSPECIFIED
                        - MARKET_SOURCE_POLYMARKET
                        - MARKET_SOURCE_KALSHI
                    description: Source platform for prediction market data.
            required:
                - id
            description: PredictionMarket represents a prediction market contract.
        worldmonitor_radiation_v1_ListRadiationObservationsRequest:
            type: object
            properties:
                maxItems:
                    type: integer
                    format: int32
                    description: Maximum items to return (1-25). Zero uses the service default.
            description: ListRadiationObservationsRequest specifies optional result limits.
        worldmonitor_radiation_v1_ListRadiationObservationsResponse:
            type: object
            properties:
                observations:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_radiation_v1_RadiationObservation'
                fetchedAt:
                    type: integer
                    format: int64
                    description: |-
                        Time the service synthesized the response, as Unix epoch milliseconds. A
                         value of 0 means the snapshot is unavailable/degraded, not that radiation
                         observations are confirmed absent.. Warning: Values > 2^53 may lose precision in JavaScript
                dataAvailable:
                    type: boolean
                    description: |-
                        True when observations came from a seed snapshot. False means an empty
                         payload is graceful degradation because the snapshot is unavailable.
                epaCount:
                    type: integer
                    format: int32
                    description: Number of EPA RadNet observations included.
                safecastCount:
                    type: integer
                    format: int32
                    description: Number of Safecast observations included.
                anomalyCount:
                    type: integer
                    format: int32
                    description: Total observations classified above normal.
                elevatedCount:
                    type: integer
                    format: int32
                    description: Observations classified as elevated.
                spikeCount:
                    type: integer
                    format: int32
                    description: Observations classified as spike-level anomalies.
                corroboratedCount:
                    type: integer
                    format: int32
                    description: Observations corroborated by more than one source.
                lowConfidenceCount:
                    type: integer
                    format: int32
                    description: Observations that remain low-confidence after synthesis.
                conflictingCount:
                    type: integer
                    format: int32
                    description: Observations where contributing sources materially disagree.
                convertedFromCpmCount:
                    type: integer
                    format: int32
                    description: Observations whose normalized value was derived from CPM.
            description: ListRadiationObservationsResponse contains normalized readings plus coverage metadata.
        worldmonitor_radiation_v1_RadiationObservation:
            type: object
            properties:
                id:
                    type: string
                    maxLength: 160
                    minLength: 1
                    description: Unique source-specific observation identifier.
                source:
                    type: string
                    enum:
                        - RADIATION_SOURCE_UNSPECIFIED
                        - RADIATION_SOURCE_EPA_RADNET
                        - RADIATION_SOURCE_SAFECAST
                    description: RadiationSource identifies the upstream measurement network.
                locationName:
                    type: string
                    description: Human-readable location label.
                country:
                    type: string
                    description: Country or territory label.
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                value:
                    type: number
                    format: double
                    description: Dose equivalent rate normalized to nSv/h.
                unit:
                    type: string
                    description: Display unit, currently always nSv/h after normalization.
                observedAt:
                    type: integer
                    format: int64
                    description: 'Time the observation was recorded, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                freshness:
                    type: string
                    enum:
                        - RADIATION_FRESHNESS_UNSPECIFIED
                        - RADIATION_FRESHNESS_LIVE
                        - RADIATION_FRESHNESS_RECENT
                        - RADIATION_FRESHNESS_HISTORICAL
                    description: RadiationFreshness groups observations by recency.
                baselineValue:
                    type: number
                    format: double
                    description: Rolling baseline for this station in nSv/h.
                delta:
                    type: number
                    format: double
                    description: Current reading minus rolling baseline in nSv/h.
                zScore:
                    type: number
                    format: double
                    description: Standard deviation distance from the rolling baseline.
                severity:
                    type: string
                    enum:
                        - RADIATION_SEVERITY_UNSPECIFIED
                        - RADIATION_SEVERITY_NORMAL
                        - RADIATION_SEVERITY_ELEVATED
                        - RADIATION_SEVERITY_SPIKE
                    description: RadiationSeverity classifies whether a reading is behaving normally.
                contributingSources:
                    type: array
                    items:
                        type: string
                        enum:
                            - RADIATION_SOURCE_UNSPECIFIED
                            - RADIATION_SOURCE_EPA_RADNET
                            - RADIATION_SOURCE_SAFECAST
                        description: RadiationSource identifies the upstream measurement network.
                confidence:
                    type: string
                    enum:
                        - RADIATION_CONFIDENCE_UNSPECIFIED
                        - RADIATION_CONFIDENCE_LOW
                        - RADIATION_CONFIDENCE_MEDIUM
                        - RADIATION_CONFIDENCE_HIGH
                    description: RadiationConfidence represents how strongly the reading is supported.
                corroborated:
                    type: boolean
                    description: Whether a second source corroborated the observed pattern.
                conflictingSources:
                    type: boolean
                    description: Whether contributing sources materially disagree.
                convertedFromCpm:
                    type: boolean
                    description: True when the value was converted from CPM using a generic fallback.
                sourceCount:
                    type: integer
                    format: int32
                    description: Number of distinct contributing sources.
            required:
                - id
            description: RadiationObservation represents a normalized ambient dose-rate reading.
        worldmonitor_research_v1_ListArxivPapersRequest:
            type: object
            properties:
                pageSize:
                    type: integer
                    format: int32
                    description: Maximum items per page (1-100).
                cursor:
                    type: string
                    description: |-
                        Cursor for next page.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                category:
                    type: string
                    description: arXiv category filter (e.g., "cs.AI"). Empty returns all tracked categories.
                query:
                    type: string
                    description: |-
                        Search query for paper titles and abstracts.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
            description: ListArxivPapersRequest specifies filters for retrieving arXiv papers.
        worldmonitor_research_v1_ListArxivPapersResponse:
            type: object
            properties:
                papers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_research_v1_ArxivPaper'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListArxivPapersResponse contains arXiv papers matching the request.
        worldmonitor_research_v1_ArxivPaper:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: arXiv paper ID (e.g., "2401.12345").
                title:
                    type: string
                    minLength: 1
                    description: Paper title.
                summary:
                    type: string
                    description: Paper abstract (may be truncated).
                authors:
                    type: array
                    items:
                        type: string
                        description: Author names.
                categories:
                    type: array
                    items:
                        type: string
                        description: arXiv categories (e.g., "cs.AI", "cs.LG").
                publishedAt:
                    type: integer
                    format: int64
                    description: 'Publication time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                url:
                    type: string
                    description: URL to the paper.
            required:
                - id
                - title
            description: ArxivPaper represents a research paper from arXiv.
        worldmonitor_research_v1_ListTrendingReposRequest:
            type: object
            properties:
                pageSize:
                    type: integer
                    format: int32
                    description: Maximum items per page (1-100).
                cursor:
                    type: string
                    description: Cursor for next page.
                language:
                    type: string
                    description: Programming language filter (e.g., "python", "typescript").
                period:
                    type: string
                    description: Trending period (e.g., "daily", "weekly"). Defaults to "daily".
            description: ListTrendingReposRequest specifies filters for retrieving trending GitHub repos.
        worldmonitor_research_v1_ListTrendingReposResponse:
            type: object
            properties:
                repos:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_research_v1_GithubRepo'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListTrendingReposResponse contains trending GitHub repositories.
        worldmonitor_research_v1_GithubRepo:
            type: object
            properties:
                fullName:
                    type: string
                    minLength: 1
                    description: Repository full name (e.g., "owner/repo").
                description:
                    type: string
                    description: Repository description.
                language:
                    type: string
                    description: Primary programming language.
                stars:
                    type: integer
                    minimum: 0
                    format: int32
                    description: Total star count.
                starsToday:
                    type: integer
                    format: int32
                    description: Stars gained in the trending period.
                forks:
                    type: integer
                    format: int32
                    description: Number of open forks.
                url:
                    type: string
                    description: Repository URL.
            required:
                - fullName
            description: GithubRepo represents a trending repository from GitHub.
        worldmonitor_research_v1_ListHackernewsItemsRequest:
            type: object
            properties:
                pageSize:
                    type: integer
                    format: int32
                    description: Maximum items per page (1-100).
                cursor:
                    type: string
                    description: Cursor for next page.
                feedType:
                    type: string
                    description: 'Feed type: "top", "new", "best", "ask", "show", "job". Defaults to "top".'
            description: ListHackernewsItemsRequest specifies filters for retrieving Hacker News items.
        worldmonitor_research_v1_ListHackernewsItemsResponse:
            type: object
            properties:
                items:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_research_v1_HackernewsItem'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListHackernewsItemsResponse contains Hacker News items.
        worldmonitor_research_v1_HackernewsItem:
            type: object
            properties:
                id:
                    type: integer
                    format: int32
                    description: HN item ID.
                title:
                    type: string
                    minLength: 1
                    description: Item title.
                url:
                    type: string
                    description: URL (empty for Ask HN / Show HN text posts).
                score:
                    type: integer
                    minimum: 0
                    format: int32
                    description: Upvote score.
                commentCount:
                    type: integer
                    format: int32
                    description: Number of comments.
                by:
                    type: string
                    description: Author username.
                submittedAt:
                    type: integer
                    format: int64
                    description: 'Submission time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
            required:
                - title
            description: HackernewsItem represents an item from Hacker News.
        worldmonitor_research_v1_ListTechEventsRequest:
            type: object
            properties:
                type:
                    type: string
                    description: 'Event type filter: "all", "conference", "earnings", "ipo", "other". Empty = all.'
                mappable:
                    type: boolean
                    description: Only events with non-virtual coordinates.
                limit:
                    type: integer
                    maximum: 500
                    minimum: 0
                    format: int32
                    description: |-
                        Max events to return. The handler clamps this to the range 1-200 and defaults to 50
                         when omitted; 0 is not unlimited (it clamps up to 1).
                days:
                    type: integer
                    minimum: 0
                    format: int32
                    description: |-
                        Events within N days from now. The handler clamps this to the range 1-365 and defaults
                         to 90 when omitted; 0 is not unlimited (it clamps up to 1).
            description: ListTechEventsRequest specifies filters for retrieving tech events.
        worldmonitor_research_v1_ListTechEventsResponse:
            type: object
            properties:
                success:
                    type: boolean
                    description: Whether the request succeeded.
                count:
                    type: integer
                    format: int32
                    description: Total event count in response.
                conferenceCount:
                    type: integer
                    format: int32
                    description: Number of conference-type events.
                mappableCount:
                    type: integer
                    format: int32
                    description: Number of mappable (non-virtual with coords) events.
                lastUpdated:
                    type: string
                    description: ISO 8601 timestamp of last update.
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_research_v1_TechEvent'
                error:
                    type: string
                    description: Error message if success is false.
            description: ListTechEventsResponse contains tech events matching the request.
        worldmonitor_research_v1_TechEvent:
            type: object
            properties:
                id:
                    type: string
                    description: Unique event identifier.
                title:
                    type: string
                    description: Event title.
                type:
                    type: string
                    description: 'Event type: "conference", "earnings", "ipo", "other".'
                location:
                    type: string
                    description: Location description.
                coords:
                    $ref: '#/components/schemas/worldmonitor_research_v1_TechEventCoords'
                startDate:
                    type: string
                    description: Start date (YYYY-MM-DD).
                endDate:
                    type: string
                    description: End date (YYYY-MM-DD).
                url:
                    type: string
                    description: Event URL.
                source:
                    type: string
                    description: 'Source: "techmeme", "dev.events", "curated".'
                description:
                    type: string
                    description: Event description.
            description: TechEvent represents a single tech event (conference, earnings, IPO, etc.).
        worldmonitor_research_v1_TechEventCoords:
            type: object
            properties:
                lat:
                    type: number
                    format: double
                    description: Latitude.
                lng:
                    type: number
                    format: double
                    description: Longitude.
                country:
                    type: string
                    description: Country name or code.
                original:
                    type: string
                    description: Original location string before normalization.
                virtual:
                    type: boolean
                    description: Whether this is a virtual/online event.
            description: TechEventCoords contains geocoded location data for a tech event.
        worldmonitor_resilience_v1_GetResilienceScoreRequest:
            type: object
            properties:
                countryCode:
                    type: string
                    description: ISO 3166-1 alpha-2 country code to score.
            required:
                - countryCode
        worldmonitor_resilience_v1_GetResilienceScoreResponse:
            type: object
            properties:
                countryCode:
                    type: string
                overallScore:
                    type: number
                    format: double
                level:
                    type: string
                domains:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_resilience_v1_ResilienceDomain'
                trend:
                    type: string
                change30d:
                    type: number
                    format: double
                lowConfidence:
                    type: boolean
                imputationShare:
                    type: number
                    format: double
                baselineScore:
                    type: number
                    format: double
                stressScore:
                    type: number
                    format: double
                stressFactor:
                    type: number
                    format: double
                dataVersion:
                    type: string
                scoreInterval:
                    $ref: '#/components/schemas/worldmonitor_resilience_v1_ScoreInterval'
                pillars:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_resilience_v1_ResiliencePillar'
                schemaVersion:
                    type: string
                    description: |-
                        Phase 2 T2.1/T2.3: "2.0" is the current default (adds pillars; keeps
                         overall_score / baseline_score / etc. populated for backward compat).
                         "1.0" is the legacy opt-out shape (pillars empty) retained for one
                         release cycle. Controlled at response build time by the
                         RESILIENCE_SCHEMA_V2_ENABLED env flag (defaults to "true" → v2).
                headlineEligible:
                    type: boolean
                    description: |-
                        Current headline-ranking eligibility. True only when the country passes
                         the headline gate: coverage >= 0.65 AND (population >= 200k OR
                         coverage >= 0.85) AND !lowConfidence. GetResilienceRanking includes
                         only eligible countries in items[]; scored but ineligible countries
                         remain in greyedOut[]. Raw score endpoints still return the country
                         score when available. Widget and country detail copy should show
                         "Outside headline ranking" when false unless low-confidence is the more
                         specific reason.
        worldmonitor_resilience_v1_ResilienceDomain:
            type: object
            properties:
                id:
                    type: string
                score:
                    type: number
                    format: double
                weight:
                    type: number
                    format: double
                dimensions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_resilience_v1_ResilienceDimension'
        worldmonitor_resilience_v1_ResilienceDimension:
            type: object
            properties:
                id:
                    type: string
                score:
                    type: number
                    format: double
                coverage:
                    type: number
                    format: double
                observedWeight:
                    type: number
                    format: double
                imputedWeight:
                    type: number
                    format: double
                imputationClass:
                    type: string
                    description: |-
                        Four-class imputation taxonomy (Phase 1 T1.7). One of:
                         "stable-absence", "unmonitored", "source-failure", "not-applicable".
                         Empty string when the dimension has any observed data AND is not
                         structurally not-applicable. The "not-applicable" value (plan
                         2026-04-26-001 §U3) is emitted when the dim's construct does not
                         apply to this country (e.g. sovereignFiscalBuffer for non-SWF
                         economies); it is paired with coverage:0 and observed_weight:0 so
                         the dim contributes nothing to the domain mean and is filtered
                         out of user-facing confidence/coverage signals on both server and
                         client. See docs/methodology/country-resilience-index.mdx.
                freshness:
                    $ref: '#/components/schemas/worldmonitor_resilience_v1_DimensionFreshness'
        worldmonitor_resilience_v1_DimensionFreshness:
            type: object
            properties:
                lastObservedAtMs:
                    type: string
                    format: int64
                    description: |-
                        Unix milliseconds when the oldest constituent signal in this
                         dimension was last observed (min fetchedAt across INDICATOR_REGISTRY
                         entries for this dimension). 0 when no signal has ever been
                         observed.
                staleness:
                    type: string
                    description: |-
                        Worst staleness level across the dimension's constituent signals,
                         classified by classifyStaleness against each signal's cadence.
                         One of: "fresh", "aging", "stale". Empty string when no signals.
        worldmonitor_resilience_v1_ScoreInterval:
            type: object
            properties:
                p05:
                    type: number
                    format: double
                p95:
                    type: number
                    format: double
        worldmonitor_resilience_v1_ResiliencePillar:
            type: object
            properties:
                id:
                    type: string
                    description: '"structural-readiness" | "live-shock-exposure" | "recovery-capacity".'
                score:
                    type: number
                    format: double
                    description: |-
                        Pillar score in [0, 100], mean of member domains weighted by
                         domain.weight * average_dimension_coverage.
                weight:
                    type: number
                    format: double
                    description: 'Pillar weight in the pillar-combined score. Per the plan: 0.40 / 0.35 / 0.25.'
                coverage:
                    type: number
                    format: double
                    description: Coverage in [0, 1], mean of member-domain average dimension coverage.
                domains:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_resilience_v1_ResilienceDomain'
            description: |-
                Phase 2 T2.1/T2.3 of the country-resilience reference-grade upgrade plan.
                 Three-pillar response shape that regroups the 6 ResilienceDomains
                 (economic, infrastructure, energy, social-governance, health-food,
                 recovery) into long-run capacity (structural-readiness), current shock
                 pressure (live-shock-exposure), and recovery capability (recovery-capacity).
                 Pillar scores are real domain-weighted, coverage-scaled aggregates computed
                 from the constituent domains; pillar coverage remains the mean of
                 member-domain average dimension coverage. See _pillar-membership.ts for the mapping.
                 When RESILIENCE_SCHEMA_V2_ENABLED and RESILIENCE_PILLAR_COMBINE_ENABLED
                 are both true, the top-level overall_score on GetResilienceScoreResponse
                 uses the pillar-combined score with the min-pillar penalty term in
                 _shared.ts#penalizedPillarScore. The legacy six-domain weighted aggregate
                 remains the flag-off rollback path.
        worldmonitor_resilience_v1_GetResilienceRankingRequest:
            type: object
        worldmonitor_resilience_v1_GetResilienceRankingResponse:
            type: object
            properties:
                items:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_resilience_v1_ResilienceRankingItem'
                greyedOut:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_resilience_v1_ResilienceRankingItem'
                fetchedAt:
                    type: string
                scored:
                    type: integer
                    format: int32
                total:
                    type: integer
                    format: int32
                coverage:
                    type: number
                    format: double
                partial:
                    type: boolean
        worldmonitor_resilience_v1_ResilienceRankingItem:
            type: object
            properties:
                countryCode:
                    type: string
                overallScore:
                    type: number
                    format: double
                level:
                    type: string
                lowConfidence:
                    type: boolean
                overallCoverage:
                    type: number
                    format: double
                rankStable:
                    type: boolean
                headlineEligible:
                    type: boolean
                    description: |-
                        Current headline-ranking eligibility. True only when the country passes
                         the headline gate: coverage >= 0.65 AND (population >= 200k OR
                         coverage >= 0.85) AND !lowConfidence. GetResilienceRanking includes
                         only eligible countries in items[]; scored but ineligible countries
                         remain in greyedOut[].
        worldmonitor_resilience_v1_GetResilienceRuntimeManifestRequest:
            type: object
        worldmonitor_resilience_v1_GetResilienceRuntimeManifestResponse:
            type: object
            properties:
                manifestVersion:
                    type: integer
                    format: int32
                generatedAt:
                    type: string
                deployedCommitSha:
                    type: string
                vercelEnv:
                    type: string
                formulaTag:
                    type: string
                dataVersion:
                    type: string
                flags:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_resilience_v1_ResilienceRuntimeFlag'
                cache:
                    $ref: '#/components/schemas/worldmonitor_resilience_v1_ResilienceRuntimeCacheState'
                rankingCache:
                    $ref: '#/components/schemas/worldmonitor_resilience_v1_ResilienceRankingCacheState'
                constructVersions:
                    $ref: '#/components/schemas/worldmonitor_resilience_v1_ResilienceRuntimeConstructVersions'
                intervals:
                    $ref: '#/components/schemas/worldmonitor_resilience_v1_ResilienceRuntimeIntervalState'
        worldmonitor_resilience_v1_ResilienceRuntimeFlag:
            type: object
            properties:
                name:
                    type: string
                enabled:
                    type: boolean
        worldmonitor_resilience_v1_ResilienceRuntimeCacheState:
            type: object
            properties:
                scorePrefix:
                    type: string
                rankingKey:
                    type: string
                historyPrefix:
                    type: string
                intervalPrefix:
                    type: string
                intervalMethodology:
                    type: string
        worldmonitor_resilience_v1_ResilienceRankingCacheState:
            type: object
            properties:
                fetchedAt:
                    type: string
                count:
                    type: integer
                    format: int32
                scored:
                    type: integer
                    format: int32
                total:
                    type: integer
                    format: int32
        worldmonitor_resilience_v1_ResilienceRuntimeConstructVersions:
            type: object
            properties:
                energy:
                    type: string
                    description: 'Safe derived energy construct version. Valid values: "legacy" or "v2".'
        worldmonitor_resilience_v1_ResilienceRuntimeIntervalState:
            type: object
            properties:
                available:
                    type: boolean
                    description: True only when the public sample interval can be read for the active formula.
                methodology:
                    type: string
                    description: Public methodology tag used to audit scoreInterval/rankStable semantics.
                sampleCountry:
                    type: string
                    description: ISO2 country used for the public availability probe.
                lastObservedAt:
                    type: string
                    description: Latest safe observed timestamp from interval seed-meta or sample payload.
        worldmonitor_sanctions_v1_ListSanctionsPressureRequest:
            type: object
            properties:
                maxItems:
                    type: integer
                    format: int32
                    description: Maximum number of recent sanctions entries to include.
            description: ListSanctionsPressureRequest retrieves recent OFAC sanctions pressure state.
        worldmonitor_sanctions_v1_ListSanctionsPressureResponse:
            type: object
            properties:
                entries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_sanctions_v1_SanctionsEntry'
                countries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_sanctions_v1_CountrySanctionsPressure'
                programs:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_sanctions_v1_ProgramSanctionsPressure'
                fetchedAt:
                    type: string
                    format: int64
                datasetDate:
                    type: string
                    format: int64
                totalCount:
                    type: integer
                    format: int32
                sdnCount:
                    type: integer
                    format: int32
                consolidatedCount:
                    type: integer
                    format: int32
                newEntryCount:
                    type: integer
                    format: int32
                vesselCount:
                    type: integer
                    format: int32
                aircraftCount:
                    type: integer
                    format: int32
            description: ListSanctionsPressureResponse contains normalized OFAC pressure summaries and recent entries.
        worldmonitor_sanctions_v1_SanctionsEntry:
            type: object
            properties:
                id:
                    type: string
                name:
                    type: string
                entityType:
                    type: string
                    enum:
                        - SANCTIONS_ENTITY_TYPE_UNSPECIFIED
                        - SANCTIONS_ENTITY_TYPE_ENTITY
                        - SANCTIONS_ENTITY_TYPE_INDIVIDUAL
                        - SANCTIONS_ENTITY_TYPE_VESSEL
                        - SANCTIONS_ENTITY_TYPE_AIRCRAFT
                    description: SanctionsEntityType classifies the designated party.
                countryCodes:
                    type: array
                    items:
                        type: string
                countryNames:
                    type: array
                    items:
                        type: string
                programs:
                    type: array
                    items:
                        type: string
                sourceLists:
                    type: array
                    items:
                        type: string
                effectiveAt:
                    type: string
                    format: int64
                isNew:
                    type: boolean
                note:
                    type: string
            description: SanctionsEntry is a normalized OFAC sanctions designation.
        worldmonitor_sanctions_v1_CountrySanctionsPressure:
            type: object
            properties:
                countryCode:
                    type: string
                countryName:
                    type: string
                entryCount:
                    type: integer
                    format: int32
                newEntryCount:
                    type: integer
                    format: int32
                vesselCount:
                    type: integer
                    format: int32
                aircraftCount:
                    type: integer
                    format: int32
            description: CountrySanctionsPressure summarizes designation volume and recent additions by country.
        worldmonitor_sanctions_v1_ProgramSanctionsPressure:
            type: object
            properties:
                program:
                    type: string
                entryCount:
                    type: integer
                    format: int32
                newEntryCount:
                    type: integer
                    format: int32
            description: ProgramSanctionsPressure summarizes designation volume and recent additions by OFAC program.
        worldmonitor_sanctions_v1_LookupSanctionEntityRequest:
            type: object
            properties:
                q:
                    type: string
                    description: Search text for a sanctioned person, organization, vessel, or aircraft.
                maxResults:
                    type: integer
                    format: int32
                    description: Maximum number of matching sanctioned entities to return.
            description: LookupSanctionEntityRequest searches the OFAC entity index by name, vessel, or aircraft.
        worldmonitor_sanctions_v1_LookupSanctionEntityResponse:
            type: object
            properties:
                results:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_sanctions_v1_SanctionEntityMatch'
                total:
                    type: integer
                    format: int32
                source:
                    type: string
            description: LookupSanctionEntityResponse contains matched entities from OFAC + OpenSanctions.
        worldmonitor_sanctions_v1_SanctionEntityMatch:
            type: object
            properties:
                id:
                    type: string
                name:
                    type: string
                entityType:
                    type: string
                countryCodes:
                    type: array
                    items:
                        type: string
                programs:
                    type: array
                    items:
                        type: string
            description: SanctionEntityMatch is a compact entity match from the lookup index.
        worldmonitor_scenario_v1_RunScenarioRequest:
            type: object
            properties:
                scenarioId:
                    type: string
                    maxLength: 128
                    minLength: 1
                    description: Scenario template id — must match an entry in SCENARIO_TEMPLATES.
                iso2:
                    type: string
                    pattern: ^([A-Z]{2})?$
                    description: |-
                        Optional 2-letter ISO country code to scope the impact computation.
                         When absent, v1 computes only the seeded reporter set:
                         US, CN, RU, IR, IN, TW.
            required:
                - scenarioId
            description: |-
                RunScenarioRequest enqueues a scenario job on the scenario-queue:pending
                 Upstash list for the async scenario-worker to pick up.
        worldmonitor_scenario_v1_RunScenarioResponse:
            type: object
            properties:
                jobId:
                    type: string
                    description: Generated job id of the form `scenario:{epoch_ms}:{8-char-suffix}`.
                status:
                    type: string
                    description: Always "pending" at enqueue time.
                statusUrl:
                    type: string
                    description: |-
                        Convenience URL the caller can use to poll this job's status.
                         Server-computed as `/api/scenario/v1/get-scenario-status?jobId=<job_id>`.
                         Restored after the v1 → v1 sebuf migration because external callers
                         may key off this field.
            description: |-
                RunScenarioResponse carries the enqueued job id. Clients poll
                 GetScenarioStatus with this id until status != "pending".

                 NOTE: a successful enqueue returns HTTP 202 Accepted with a Location
                 header pointing at GetScenarioStatus — the legacy (pre-sebuf) contract,
                 restored. The sebuf-generated server still emits 200 for every success
                 (no per-RPC status-code annotation exists), so the gateway upgrades the
                 status via the setSuccessStatusOverride side-channel
                 (server/_shared/response-headers.ts). Treat any 2xx as success; the
                 interim guidance to branch on response body shape instead of the status
                 code remains valid.
        worldmonitor_scenario_v1_GetScenarioStatusRequest:
            type: object
            properties:
                jobId:
                    type: string
                    pattern: ^scenario:[0-9]{13}:[a-z0-9]{8}$
                    description: |-
                        Job id of the form `scenario:{epoch_ms}:{8-char-suffix}`. Path-traversal
                         guarded by JOB_ID_RE in the handler.
            required:
                - jobId
            description: GetScenarioStatusRequest polls the worker result for an enqueued job id.
        worldmonitor_scenario_v1_GetScenarioStatusResponse:
            type: object
            properties:
                status:
                    type: string
                result:
                    $ref: '#/components/schemas/worldmonitor_scenario_v1_ScenarioResult'
                error:
                    type: string
                    description: Populated only when status == "failed".
            description: |-
                GetScenarioStatusResponse reflects the worker's lifecycle state.
                 "pending" — no key yet (job still queued or very-recent enqueue).
                 "processing" — worker has claimed the job but hasn't completed compute.
                 "done" — compute succeeded; `result` is populated.
                 "failed" — compute errored; `error` is populated.
        worldmonitor_scenario_v1_ScenarioResult:
            type: object
            properties:
                affectedChokepointIds:
                    type: array
                    items:
                        type: string
                        description: Chokepoint ids disrupted by this scenario.
                topImpactCountries:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_scenario_v1_ScenarioImpactCountry'
                template:
                    $ref: '#/components/schemas/worldmonitor_scenario_v1_ScenarioResultTemplate'
            description: |-
                ScenarioResult is the computed payload the scenario-worker writes back
                 under the `scenario-result:{job_id}` Redis key. Populated only when
                 GetScenarioStatusResponse.status == "done".
        worldmonitor_scenario_v1_ScenarioImpactCountry:
            type: object
            properties:
                iso2:
                    type: string
                    description: 2-letter ISO country code.
                totalImpact:
                    type: number
                    format: double
                    description: |-
                        Raw weighted impact value aggregated across the country's exposed HS2
                         chapters. Physical scenarios use exposureScore * (disruption_pct / 100)
                         * cost_shock_multiplier; tariff-shock scenarios use vulnerabilityIndex
                         * cost_shock_multiplier. Relative-only - not a currency amount.
                impactPct:
                    type: integer
                    format: int32
                    description: |-
                        Impact as a 0-100 share of max(maxReturnedTotalImpact, 1), capped at 100.
                         Because of the denominator floor, the top country can be below 100 when
                         all returned totalImpact values are below 1.
            description: ScenarioImpactCountry carries a single country's relative scenario impact score.
        worldmonitor_scenario_v1_ScenarioResultTemplate:
            type: object
            properties:
                name:
                    type: string
                    description: |-
                        Worker-derived template key, not a display name. Physical scenarios join
                         affected_chokepoint_ids with `+`; tariff-type scenarios may use
                         `tariff_shock` when no physical chokepoint is affected.
                disruptionPct:
                    type: integer
                    format: int32
                    description: 0-100 percent of chokepoint capacity blocked.
                durationDays:
                    type: integer
                    format: int32
                    description: Estimated duration of disruption in days.
                costShockMultiplier:
                    type: number
                    format: double
                    description: Freight cost multiplier applied on top of bypass corridor costs.
            description: |-
                ScenarioResultTemplate carries template parameters echoed into the worker's
                 computed result so clients can render them without re-looking up the
                 template registry.
        worldmonitor_scenario_v1_ListScenarioTemplatesRequest:
            type: object
        worldmonitor_scenario_v1_ListScenarioTemplatesResponse:
            type: object
            properties:
                templates:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_scenario_v1_ScenarioTemplate'
        worldmonitor_scenario_v1_ScenarioTemplate:
            type: object
            properties:
                id:
                    type: string
                name:
                    type: string
                affectedChokepointIds:
                    type: array
                    items:
                        type: string
                        description: |-
                            Chokepoint ids this scenario disrupts. Empty for tariff-shock scenarios
                             that have no physical chokepoint closure.
                disruptionPct:
                    type: integer
                    format: int32
                    description: 0-100 percent of chokepoint capacity blocked.
                durationDays:
                    type: integer
                    format: int32
                    description: Estimated duration of disruption in days.
                affectedHs2:
                    type: array
                    items:
                        type: string
                        description: HS2 chapter codes affected. Empty means ALL sectors are affected.
                costShockMultiplier:
                    type: number
                    format: double
                    description: Freight cost multiplier applied on top of bypass corridor costs.
            description: |-
                ScenarioTemplate mirrors the catalog shape served by
                 GET /api/scenario/v1/list-scenario-templates. The authoritative template
                 registry lives in server/worldmonitor/supply-chain/v1/scenario-templates.ts.
        worldmonitor_seismology_v1_ListEarthquakesRequest:
            type: object
            properties:
                start:
                    type: integer
                    format: int64
                    description: |-
                        Start of time range (inclusive), Unix epoch milliseconds.
                         Accepted but currently ignored; no-op until this handler supports the parameter.. Warning: Values > 2^53 may lose precision in JavaScript
                end:
                    type: integer
                    format: int64
                    description: |-
                        End of time range (inclusive), Unix epoch milliseconds.
                         Accepted but currently ignored; no-op until this handler supports the parameter.. Warning: Values > 2^53 may lose precision in JavaScript
                pageSize:
                    type: integer
                    format: int32
                    description: |-
                        Maximum items per page. Defaults to 500 when omitted or 0; the handler applies no
                         clamp, so the requested value directly limits the returned list (no enforced maximum).
                cursor:
                    type: string
                    description: |-
                        Cursor for next page.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                minMagnitude:
                    type: number
                    format: double
                    description: |-
                        Minimum magnitude filter (e.g., 4.0 for significant quakes).
                         Accepted but currently ignored; no-op until this handler supports the parameter.
            description: ListEarthquakesRequest specifies filters for retrieving earthquake data from USGS.
        worldmonitor_seismology_v1_ListEarthquakesResponse:
            type: object
            properties:
                earthquakes:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_seismology_v1_Earthquake'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListEarthquakesResponse contains the list of earthquakes matching the request filters.
        worldmonitor_seismology_v1_Earthquake:
            type: object
            properties:
                id:
                    type: string
                    maxLength: 100
                    minLength: 1
                    description: Unique USGS event identifier (e.g., "us7000abcd").
                place:
                    type: string
                    description: Human-readable place description (e.g., "10 km SW of Anchorage, Alaska").
                magnitude:
                    type: number
                    format: double
                    description: Earthquake magnitude on the Richter scale.
                depthKm:
                    type: number
                    format: double
                    description: Depth in kilometers below the surface.
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                occurredAt:
                    type: integer
                    format: int64
                    description: 'Time the earthquake occurred, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                sourceUrl:
                    type: string
                    description: URL to the USGS event detail page.
                nearTestSite:
                    type: boolean
                    description: True when epicenter is within 100 km of a known nuclear test site.
                testSiteName:
                    type: string
                    description: Name of the nearest test site (e.g. "Punggye-ri"), when near_test_site is true.
                concernScore:
                    type: number
                    format: double
                    description: Composite concern score 0–100 based on magnitude, depth, and proximity.
                concernLevel:
                    type: string
                    description: 'Human-readable concern level: "low" | "moderate" | "elevated" | "critical".'
            required:
                - id
            description: Earthquake represents a seismic event from USGS GeoJSON feed.
        worldmonitor_shipping_v2_RouteIntelligenceRequest:
            type: object
            properties:
                fromIso2:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: Origin country, ISO-3166-1 alpha-2 uppercase.
                toIso2:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: Destination country, ISO-3166-1 alpha-2 uppercase.
                cargoType:
                    type: string
                    description: |-
                        Cargo type — one of: container (default), tanker, bulk, roro.
                         Empty string defers to the server default. Unknown values are coerced to
                         "container" to preserve legacy behavior.
                hs2:
                    type: string
                    description: |-
                        2-digit HS commodity code (default "27" — mineral fuels). Non-digit
                         characters are stripped server-side to match legacy behavior.
            required:
                - fromIso2
                - toIso2
            description: |-
                RouteIntelligenceRequest scopes a route-intelligence query by origin and
                 destination country. Query-parameter names are preserved verbatim from the
                 legacy partner contract (fromIso2/toIso2/cargoType/hs2 — camelCase).
        worldmonitor_shipping_v2_RouteIntelligenceResponse:
            type: object
            properties:
                fromIso2:
                    type: string
                toIso2:
                    type: string
                cargoType:
                    type: string
                hs2:
                    type: string
                primaryRouteId:
                    type: string
                chokepointExposures:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_shipping_v2_ChokepointExposure'
                bypassOptions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_shipping_v2_BypassOption'
                warRiskTier:
                    type: string
                    description: War-risk tier enum string, e.g., "WAR_RISK_TIER_NORMAL" or "WAR_RISK_TIER_ELEVATED".
                disruptionScore:
                    type: integer
                    format: int32
                    description: Disruption score of the primary chokepoint, 0-100.
                fetchedAt:
                    type: string
                    description: |-
                        ISO-8601 timestamp of when the response was assembled. Empty string means
                         the route snapshot is unavailable/degraded, not confirmed zero exposure.
            description: |-
                RouteIntelligenceResponse wire shape preserved byte-for-byte from the
                 pre-migration JSON at docs/api-shipping-v2.mdx. `fetched_at` is intentionally
                 a string (ISO-8601) rather than int64 epoch ms because partners depend on
                 the ISO-8601 shape.
        worldmonitor_shipping_v2_ChokepointExposure:
            type: object
            properties:
                chokepointId:
                    type: string
                chokepointName:
                    type: string
                exposurePct:
                    type: integer
                    format: int32
            description: Single chokepoint exposure for a route.
        worldmonitor_shipping_v2_BypassOption:
            type: object
            properties:
                id:
                    type: string
                name:
                    type: string
                type:
                    type: string
                    description: Type of bypass (e.g., "maritime_detour", "land_corridor").
                addedTransitDays:
                    type: integer
                    format: int32
                addedCostMultiplier:
                    type: number
                    format: double
                activationThreshold:
                    type: string
                    description: Enum-like string, e.g., "DISRUPTION_SCORE_60".
            description: Single bypass-corridor option around a disrupted chokepoint.
        worldmonitor_shipping_v2_RegisterWebhookRequest:
            type: object
            properties:
                callbackUrl:
                    type: string
                    maxLength: 2048
                    minLength: 8
                    description: |-
                        HTTPS callback URL. Must not resolve to a private/loopback address at
                         registration time (SSRF guard). The delivery worker re-validates the
                         resolved IP before each send to mitigate DNS rebinding.
                chokepointIds:
                    type: array
                    items:
                        type: string
                        description: |-
                            Zero or more chokepoint IDs to subscribe to. Empty list subscribes to
                             the entire CHOKEPOINT_REGISTRY. Unknown IDs fail with 400.
                alertThreshold:
                    type: integer
                    maximum: 100
                    minimum: 0
                    format: int32
                    description: |-
                        Disruption-score threshold for delivery, 0-100. Default 50.
                         proto3 `optional` so the handler can distinguish "partner explicitly sent
                         0 (deliver every alert)" from "partner omitted the field (apply default
                         50)". Without `optional`, both serialise to the proto3 scalar default of
                         0 and the handler can't tell them apart — flagged in #3242 review.
            required:
                - callbackUrl
            description: |-
                RegisterWebhookRequest creates a new chokepoint-disruption webhook
                 subscription. Wire shape is byte-compatible with the pre-migration
                 legacy POST body.
        worldmonitor_shipping_v2_RegisterWebhookResponse:
            type: object
            properties:
                subscriberId:
                    type: string
                    description: '`wh_` prefix + 24 lowercase hex chars (12 random bytes).'
                secret:
                    type: string
                    description: Raw 64-char lowercase hex secret (32 random bytes). No `whsec_` prefix.
            description: |-
                RegisterWebhookResponse wire shape preserved exactly — partners persist the
                 `secret` because the server never returns it again except via rotate-secret.
        worldmonitor_shipping_v2_ListWebhooksRequest:
            type: object
            description: |-
                ListWebhooksRequest has no fields — the owner is derived from the caller's
                 API-key fingerprint (SHA-256 of X-WorldMonitor-Key).
        worldmonitor_shipping_v2_ListWebhooksResponse:
            type: object
            properties:
                webhooks:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_shipping_v2_WebhookSummary'
            description: |-
                ListWebhooksResponse wire shape preserved exactly: the `webhooks` field
                 name and the omission of `secret` are part of the partner contract.
        worldmonitor_shipping_v2_WebhookSummary:
            type: object
            properties:
                subscriberId:
                    type: string
                callbackUrl:
                    type: string
                chokepointIds:
                    type: array
                    items:
                        type: string
                alertThreshold:
                    type: integer
                    format: int32
                createdAt:
                    type: string
                    description: ISO-8601 timestamp of registration.
                active:
                    type: boolean
            description: |-
                Single webhook record in the list response. `secret` is intentionally
                 omitted; use rotate-secret to obtain a new one.
        worldmonitor_supply_chain_v1_GetShippingRatesRequest:
            type: object
        worldmonitor_supply_chain_v1_GetShippingRatesResponse:
            type: object
            properties:
                indices:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_ShippingIndex'
                fetchedAt:
                    type: string
                upstreamUnavailable:
                    type: boolean
        worldmonitor_supply_chain_v1_ShippingIndex:
            type: object
            properties:
                indexId:
                    type: string
                name:
                    type: string
                currentValue:
                    type: number
                    format: double
                previousValue:
                    type: number
                    format: double
                changePct:
                    type: number
                    format: double
                unit:
                    type: string
                history:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_ShippingRatePoint'
                spikeAlert:
                    type: boolean
        worldmonitor_supply_chain_v1_ShippingRatePoint:
            type: object
            properties:
                date:
                    type: string
                value:
                    type: number
                    format: double
        worldmonitor_supply_chain_v1_GetChokepointStatusRequest:
            type: object
        worldmonitor_supply_chain_v1_GetChokepointStatusResponse:
            type: object
            properties:
                chokepoints:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_ChokepointInfo'
                fetchedAt:
                    type: string
                    description: |-
                        ISO-8601 time the status snapshot was fetched. Empty string with
                         upstream_unavailable=true means the snapshot is unavailable/degraded.
                upstreamUnavailable:
                    type: boolean
                    description: |-
                        True when upstream seed/relay data is unavailable or partial. When true, an
                         empty chokepoints array is graceful degradation, not confirmed zero data.
        worldmonitor_supply_chain_v1_ChokepointInfo:
            type: object
            properties:
                id:
                    type: string
                name:
                    type: string
                lat:
                    type: number
                    format: double
                lon:
                    type: number
                    format: double
                disruptionScore:
                    type: integer
                    format: int32
                status:
                    type: string
                    description: |-
                        Traffic-light score badge: green (<20), yellow (20-49), or red (>=50).
                         Not an operational closure taxonomy.
                activeWarnings:
                    type: integer
                    format: int32
                congestionLevel:
                    type: string
                affectedRoutes:
                    type: array
                    items:
                        type: string
                description:
                    type: string
                aisDisruptions:
                    type: integer
                    format: int32
                directions:
                    type: array
                    items:
                        type: string
                directionalDwt:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_DirectionalDwt'
                transitSummary:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_TransitSummary'
                flowEstimate:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_FlowEstimate'
                warRiskTier:
                    type: string
                    enum:
                        - WAR_RISK_TIER_UNSPECIFIED
                        - WAR_RISK_TIER_NORMAL
                        - WAR_RISK_TIER_ELEVATED
                        - WAR_RISK_TIER_HIGH
                        - WAR_RISK_TIER_CRITICAL
                        - WAR_RISK_TIER_WAR_ZONE
                    description: |-
                        *
                         War risk tier derived from Lloyd's JWC Listed Areas + OSINT threat classification.
                         This is a FREE field (no PRO gate) — it exposes the existing server-internal
                         threatLevel from ChokepointConfig, making it available to clients for badges
                         and bypass corridor scoring.
        worldmonitor_supply_chain_v1_DirectionalDwt:
            type: object
            properties:
                direction:
                    type: string
                dwtThousandTonnes:
                    type: number
                    format: double
                wowChangePct:
                    type: number
                    format: double
        worldmonitor_supply_chain_v1_TransitSummary:
            type: object
            properties:
                todayTotal:
                    type: integer
                    format: int32
                todayTanker:
                    type: integer
                    format: int32
                todayCargo:
                    type: integer
                    format: int32
                todayOther:
                    type: integer
                    format: int32
                wowChangePct:
                    type: number
                    format: double
                history:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_TransitDayCount'
                riskLevel:
                    type: string
                incidentCount7d:
                    type: integer
                    format: int32
                disruptionPct:
                    type: number
                    format: double
                riskSummary:
                    type: string
                riskReportAction:
                    type: string
                dataAvailable:
                    type: boolean
                    description: |-
                        False when the upstream portwatch/relay source did not return data for
                         this chokepoint in the current cycle — the summary fields are zero-state
                         fill, not a genuine "zero traffic" reading. Client should render a
                         "transit data unavailable" indicator and skip stat/chart rendering.
        worldmonitor_supply_chain_v1_TransitDayCount:
            type: object
            properties:
                date:
                    type: string
                tanker:
                    type: integer
                    format: int32
                cargo:
                    type: integer
                    format: int32
                other:
                    type: integer
                    format: int32
                total:
                    type: integer
                    format: int32
                container:
                    type: integer
                    format: int32
                dryBulk:
                    type: integer
                    format: int32
                generalCargo:
                    type: integer
                    format: int32
                roro:
                    type: integer
                    format: int32
                capContainer:
                    type: number
                    format: double
                capDryBulk:
                    type: number
                    format: double
                capGeneralCargo:
                    type: number
                    format: double
                capRoro:
                    type: number
                    format: double
                capTanker:
                    type: number
                    format: double
        worldmonitor_supply_chain_v1_FlowEstimate:
            type: object
            properties:
                currentMbd:
                    type: number
                    format: double
                    description: |-
                        Current estimated flow in million barrels/day. Computed as
                         baseline_mbd * flow_ratio.
                baselineMbd:
                    type: number
                    format: double
                    description: |-
                        EIA 2023 annual reference level in million barrels/day for the mapped
                         seven-item live-flow subset.
                flowRatio:
                    type: number
                    format: double
                    description: |-
                        Latest 7-day PortWatch average divided by the preceding rolling baseline
                         window of up to 90 days, clamped to 0.0-1.5.
                disrupted:
                    type: boolean
                    description: |-
                        True when each of the latest 3 daily ratios is below 85% of the same
                         rolling baseline window. Separate from the green/yellow/red status badge.
                source:
                    type: string
                    description: |-
                        Flow source: "portwatch-dwt" when DWT-majority coverage is used,
                         otherwise "portwatch-counts" for vessel-count coverage.
                hazardAlertLevel:
                    type: string
                    description: |-
                        Nearest active GDACS hazard alert level within the configured radius:
                         "RED", "ORANGE", or empty string when no nearby alert applies.
                hazardAlertName:
                    type: string
                    description: |-
                        Name of the nearest active GDACS hazard event within the configured
                         radius, or empty string when no nearby alert applies.
        worldmonitor_supply_chain_v1_GetChokepointHistoryRequest:
            type: object
            properties:
                chokepointId:
                    type: string
                    description: Chokepoint identifier whose transit history should be returned.
            required:
                - chokepointId
            description: |-
                GetChokepointHistory returns the transit-count history for a single
                 chokepoint. Loaded lazily on card expand so the main chokepoint-status
                 response can stay compact (no 180-day history per chokepoint).
        worldmonitor_supply_chain_v1_GetChokepointHistoryResponse:
            type: object
            properties:
                chokepointId:
                    type: string
                history:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_TransitDayCount'
                fetchedAt:
                    type: string
                    format: int64
        worldmonitor_supply_chain_v1_GetCriticalMineralsRequest:
            type: object
        worldmonitor_supply_chain_v1_GetCriticalMineralsResponse:
            type: object
            properties:
                minerals:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_CriticalMineral'
                fetchedAt:
                    type: string
                upstreamUnavailable:
                    type: boolean
        worldmonitor_supply_chain_v1_CriticalMineral:
            type: object
            properties:
                mineral:
                    type: string
                topProducers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_MineralProducer'
                hhi:
                    type: number
                    format: double
                riskRating:
                    type: string
                globalProduction:
                    type: number
                    format: double
                unit:
                    type: string
        worldmonitor_supply_chain_v1_MineralProducer:
            type: object
            properties:
                country:
                    type: string
                countryCode:
                    type: string
                productionTonnes:
                    type: number
                    format: double
                sharePct:
                    type: number
                    format: double
        worldmonitor_supply_chain_v1_GetShippingStressRequest:
            type: object
        worldmonitor_supply_chain_v1_GetShippingStressResponse:
            type: object
            properties:
                carriers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_ShippingStressCarrier'
                stressScore:
                    type: number
                    format: double
                    description: Composite stress score 0–100 (higher = more disruption).
                stressLevel:
                    type: string
                    description: '"low" | "moderate" | "elevated" | "critical".'
                fetchedAt:
                    type: integer
                    format: int64
                    description: 'Warning: Values > 2^53 may lose precision in JavaScript'
                upstreamUnavailable:
                    type: boolean
                    description: Set to true when upstream data source is unavailable and cached data is stale.
        worldmonitor_supply_chain_v1_ShippingStressCarrier:
            type: object
            properties:
                symbol:
                    type: string
                    description: Ticker or identifier (e.g., "BDRY", "ZIM").
                name:
                    type: string
                    description: Human-readable name.
                price:
                    type: number
                    format: double
                    description: Current price.
                changePct:
                    type: number
                    format: double
                    description: Percentage change from previous close.
                carrierType:
                    type: string
                    description: 'Carrier type: "etf" | "carrier" | "index".'
                sparkline:
                    type: array
                    items:
                        type: number
                        format: double
                        description: 30-day price sparkline.
            description: ShippingStressCarrier represents market stress data for a carrier or shipping index.
        worldmonitor_supply_chain_v1_GetCountryChokepointIndexRequest:
            type: object
            properties:
                iso2:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 country code (uppercase).
                hs2:
                    type: string
                    description: HS2 chapter (2-digit string). Defaults to "27" (energy/mineral fuels) when absent.
            required:
                - iso2
            description: GetCountryChokepointIndexRequest specifies the country and optional HS2 chapter.
        worldmonitor_supply_chain_v1_GetCountryChokepointIndexResponse:
            type: object
            properties:
                iso2:
                    type: string
                    description: ISO 3166-1 alpha-2 country code echoed from the request.
                hs2:
                    type: string
                    description: HS2 chapter used for the computation.
                exposures:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_ChokepointExposureEntry'
                primaryChokepointId:
                    type: string
                    description: Canonical ID of the chokepoint with the highest exposure score.
                vulnerabilityIndex:
                    type: number
                    format: double
                    description: 'Composite vulnerability index 0-100: top1 * 0.5 + top2 * 0.3 + top3 * 0.2.'
                fetchedAt:
                    type: string
                    description: ISO timestamp of when this data was last seeded.
            description: GetCountryChokepointIndexResponse returns exposure scores for all relevant chokepoints.
        worldmonitor_supply_chain_v1_ChokepointExposureEntry:
            type: object
            properties:
                chokepointId:
                    type: string
                    description: Canonical chokepoint ID from the chokepoint registry.
                chokepointName:
                    type: string
                    description: Human-readable chokepoint name.
                exposureScore:
                    type: number
                    format: double
                    description: |-
                        Exposure score 0-100; higher = more dependent on this chokepoint. With
                         bilateral product data, sums routeCoverage * exporterShare * productWeight
                         * 100 across matching products; fallback uses route overlap only. HS2 27
                         supported energy chokepoints receive a 1.5x boost capped at 100.
                coastSide:
                    type: string
                    description: Which ocean/basin side the country's ports face (atlantic, pacific, indian, med, multi, landlocked).
                shockSupported:
                    type: boolean
                    description: Whether the shock model is supported for this chokepoint + hs2 combination.
            description: ChokepointExposureEntry holds per-chokepoint exposure data for a country.
        worldmonitor_supply_chain_v1_GetBypassOptionsRequest:
            type: object
            properties:
                chokepointId:
                    type: string
                    description: Chokepoint identifier to evaluate for bypass options.
                cargoType:
                    type: string
                    description: 'container | tanker | bulk | roro  (default: "container")'
                closurePct:
                    type: integer
                    format: int32
                    description: '0-100, percent of capacity blocked (default: 100)'
            required:
                - chokepointId
        worldmonitor_supply_chain_v1_GetBypassOptionsResponse:
            type: object
            properties:
                chokepointId:
                    type: string
                cargoType:
                    type: string
                closurePct:
                    type: integer
                    format: int32
                options:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_BypassOption'
                fetchedAt:
                    type: string
                primaryChokepointWarRiskTier:
                    type: string
                    enum:
                        - WAR_RISK_TIER_UNSPECIFIED
                        - WAR_RISK_TIER_NORMAL
                        - WAR_RISK_TIER_ELEVATED
                        - WAR_RISK_TIER_HIGH
                        - WAR_RISK_TIER_CRITICAL
                        - WAR_RISK_TIER_WAR_ZONE
                    description: |-
                        *
                         War risk tier derived from Lloyd's JWC Listed Areas + OSINT threat classification.
                         This is a FREE field (no PRO gate) — it exposes the existing server-internal
                         threatLevel from ChokepointConfig, making it available to clients for badges
                         and bypass corridor scoring.
        worldmonitor_supply_chain_v1_BypassOption:
            type: object
            properties:
                id:
                    type: string
                name:
                    type: string
                type:
                    type: string
                addedTransitDays:
                    type: integer
                    format: int32
                addedCostMultiplier:
                    type: number
                    format: double
                capacityConstraintTonnage:
                    type: string
                    format: int64
                suitableCargoTypes:
                    type: array
                    items:
                        type: string
                activationThreshold:
                    type: string
                waypointChokepointIds:
                    type: array
                    items:
                        type: string
                liveScore:
                    type: number
                    format: double
                bypassWarRiskTier:
                    type: string
                    enum:
                        - WAR_RISK_TIER_UNSPECIFIED
                        - WAR_RISK_TIER_NORMAL
                        - WAR_RISK_TIER_ELEVATED
                        - WAR_RISK_TIER_HIGH
                        - WAR_RISK_TIER_CRITICAL
                        - WAR_RISK_TIER_WAR_ZONE
                    description: |-
                        *
                         War risk tier derived from Lloyd's JWC Listed Areas + OSINT threat classification.
                         This is a FREE field (no PRO gate) — it exposes the existing server-internal
                         threatLevel from ChokepointConfig, making it available to clients for badges
                         and bypass corridor scoring.
                notes:
                    type: string
        worldmonitor_supply_chain_v1_GetCountryCostShockRequest:
            type: object
            properties:
                iso2:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 country code for the importing country.
                chokepointId:
                    type: string
                    description: Chokepoint identifier to model as disrupted.
                hs2:
                    type: string
                    description: 'HS2 chapter (default: "27")'
            required:
                - iso2
                - chokepointId
        worldmonitor_supply_chain_v1_GetCountryCostShockResponse:
            type: object
            properties:
                iso2:
                    type: string
                chokepointId:
                    type: string
                hs2:
                    type: string
                supplyDeficitPct:
                    type: number
                    format: double
                    description: Average refined-product supply deficit % under full closure (Gasoline/Diesel/Jet fuel/LPG average; HS 27 only)
                coverageDays:
                    type: integer
                    format: int32
                    description: Energy stockpile coverage in days (IEA data, HS 27 only; 0 for non-energy sectors or net exporters)
                warRiskPremiumBps:
                    type: integer
                    format: int32
                    description: War risk insurance premium in basis points for this chokepoint
                warRiskTier:
                    type: string
                    enum:
                        - WAR_RISK_TIER_UNSPECIFIED
                        - WAR_RISK_TIER_NORMAL
                        - WAR_RISK_TIER_ELEVATED
                        - WAR_RISK_TIER_HIGH
                        - WAR_RISK_TIER_CRITICAL
                        - WAR_RISK_TIER_WAR_ZONE
                    description: |-
                        *
                         War risk tier derived from Lloyd's JWC Listed Areas + OSINT threat classification.
                         This is a FREE field (no PRO gate) — it exposes the existing server-internal
                         threatLevel from ChokepointConfig, making it available to clients for badges
                         and bypass corridor scoring.
                hasEnergyModel:
                    type: boolean
                    description: Whether supply_deficit_pct and coverage_days are modelled (true) or unavailable (false)
                unavailableReason:
                    type: string
                    description: Null/unavailable explanation for non-energy sectors
                fetchedAt:
                    type: string
        worldmonitor_supply_chain_v1_GetCountryProductsRequest:
            type: object
            properties:
                iso2:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 country code whose strategic products should be returned.
            required:
                - iso2
        worldmonitor_supply_chain_v1_GetCountryProductsResponse:
            type: object
            properties:
                iso2:
                    type: string
                products:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_CountryProduct'
                fetchedAt:
                    type: string
                    description: ISO timestamp from the seeded payload (empty when no data is cached).
        worldmonitor_supply_chain_v1_CountryProduct:
            type: object
            properties:
                hs4:
                    type: string
                description:
                    type: string
                totalValue:
                    type: number
                    format: double
                topExporters:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_ProductExporter'
                year:
                    type: integer
                    format: int32
        worldmonitor_supply_chain_v1_ProductExporter:
            type: object
            properties:
                partnerCode:
                    type: integer
                    format: int32
                partnerIso2:
                    type: string
                value:
                    type: number
                    format: double
                share:
                    type: number
                    format: double
        worldmonitor_supply_chain_v1_GetMultiSectorCostShockRequest:
            type: object
            properties:
                iso2:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 country code for the importing country.
                chokepointId:
                    type: string
                    description: Chokepoint identifier to model as disrupted.
                closureDays:
                    type: integer
                    format: int32
                    description: Closure-window duration in days. Server clamps to [1, 365]. Defaults to 30.
            required:
                - iso2
                - chokepointId
        worldmonitor_supply_chain_v1_GetMultiSectorCostShockResponse:
            type: object
            properties:
                iso2:
                    type: string
                chokepointId:
                    type: string
                closureDays:
                    type: integer
                    format: int32
                    description: Server-clamped closure-window duration in days (1-365).
                warRiskTier:
                    type: string
                    enum:
                        - WAR_RISK_TIER_UNSPECIFIED
                        - WAR_RISK_TIER_NORMAL
                        - WAR_RISK_TIER_ELEVATED
                        - WAR_RISK_TIER_HIGH
                        - WAR_RISK_TIER_CRITICAL
                        - WAR_RISK_TIER_WAR_ZONE
                    description: |-
                        *
                         War risk tier derived from Lloyd's JWC Listed Areas + OSINT threat classification.
                         This is a FREE field (no PRO gate) — it exposes the existing server-internal
                         threatLevel from ChokepointConfig, making it available to clients for badges
                         and bypass corridor scoring.
                sectors:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_MultiSectorCostShock'
                totalAddedCost:
                    type: number
                    format: double
                    description: Sum of total_cost_shock across all sectors.
                fetchedAt:
                    type: string
                unavailableReason:
                    type: string
                    description: Populated when no seeded import data is available for the country.
        worldmonitor_supply_chain_v1_MultiSectorCostShock:
            type: object
            properties:
                hs2:
                    type: string
                    description: HS2 chapter code (e.g. "27" mineral fuels, "85" electronics).
                hs2Label:
                    type: string
                    description: Friendly chapter label (e.g. "Energy", "Electronics").
                importValueAnnual:
                    type: number
                    format: double
                    description: Total annual import value (USD) for this sector.
                freightAddedPctPerTon:
                    type: number
                    format: double
                    description: Bypass-corridor freight uplift fraction (0.10 == +10% per ton).
                warRiskPremiumBps:
                    type: integer
                    format: int32
                    description: War-risk insurance premium (basis points) sourced from the chokepoint tier.
                addedTransitDays:
                    type: integer
                    format: int32
                    description: Bypass-corridor transit penalty (informational).
                totalCostShockPerDay:
                    type: number
                    format: double
                totalCostShock30Days:
                    type: number
                    format: double
                totalCostShock90Days:
                    type: number
                    format: double
                totalCostShock:
                    type: number
                    format: double
                    description: Cost for the requested closure_days window.
                closureDays:
                    type: integer
                    format: int32
                    description: Echoes the clamped closure duration used for total_cost_shock (1-365).
        worldmonitor_supply_chain_v1_GetSectorDependencyRequest:
            type: object
            properties:
                iso2:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 country code whose sector dependency should be analyzed.
                hs2:
                    type: string
                    description: HS2 chapter code, e.g. "27" (mineral fuels), "85" (electronics)
            required:
                - iso2
                - hs2
        worldmonitor_supply_chain_v1_GetSectorDependencyResponse:
            type: object
            properties:
                iso2:
                    type: string
                hs2:
                    type: string
                hs2Label:
                    type: string
                    description: Human-readable HS2 chapter name.
                flags:
                    type: array
                    items:
                        type: string
                        enum:
                            - DEPENDENCY_FLAG_UNSPECIFIED
                            - DEPENDENCY_FLAG_SINGLE_SOURCE_CRITICAL
                            - DEPENDENCY_FLAG_SINGLE_CORRIDOR_CRITICAL
                            - DEPENDENCY_FLAG_COMPOUND_RISK
                            - DEPENDENCY_FLAG_DIVERSIFIABLE
                        description: DependencyFlag classifies how a country+sector dependency can fail.
                primaryExporterIso2:
                    type: string
                    description: ISO2 of the country supplying the largest share of this sector's imports.
                primaryExporterShare:
                    type: number
                    format: double
                    description: Share of imports from the primary exporter (0–1). 0 = no Comtrade data available.
                primaryChokepointId:
                    type: string
                    description: Chokepoint ID with the highest exposure score for this country+sector.
                primaryChokepointExposure:
                    type: number
                    format: double
                    description: Exposure score for the primary chokepoint (0–100).
                hasViableBypass:
                    type: boolean
                    description: Whether at least one viable bypass corridor exists for the primary chokepoint.
                fetchedAt:
                    type: string
        worldmonitor_supply_chain_v1_GetRouteExplorerLaneRequest:
            type: object
            properties:
                fromIso2:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 origin country code for the trade lane.
                toIso2:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 destination country code for the trade lane.
                hs2:
                    type: string
                    description: HS2 chapter code, e.g. "27", "85"
                cargoType:
                    type: string
                    description: 'One of: container, tanker, bulk, roro'
            required:
                - fromIso2
                - toIso2
                - hs2
                - cargoType
        worldmonitor_supply_chain_v1_GetRouteExplorerLaneResponse:
            type: object
            properties:
                fromIso2:
                    type: string
                toIso2:
                    type: string
                hs2:
                    type: string
                cargoType:
                    type: string
                primaryRouteId:
                    type: string
                    description: Primary trade route ID from TRADE_ROUTES config. Empty when no modeled lane.
                primaryRouteGeometry:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GeoPoint'
                chokepointExposures:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_ChokepointExposureSummary'
                bypassOptions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_BypassCorridorOption'
                warRiskTier:
                    type: string
                disruptionScore:
                    type: number
                    format: double
                estTransitDaysRange:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_NumberRange'
                estFreightUsdPerTeuRange:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_NumberRange'
                noModeledLane:
                    type: boolean
                    description: |-
                        True when the wrapper fell back to the origin's first route (no shared route
                         between origin and destination clusters). Signals "no modeled lane" to the UI.
                fetchedAt:
                    type: string
        worldmonitor_supply_chain_v1_GeoPoint:
            type: object
            properties:
                lon:
                    type: number
                    format: double
                lat:
                    type: number
                    format: double
            description: GeoPoint is a [longitude, latitude] pair.
        worldmonitor_supply_chain_v1_ChokepointExposureSummary:
            type: object
            properties:
                chokepointId:
                    type: string
                chokepointName:
                    type: string
                exposurePct:
                    type: integer
                    format: int32
        worldmonitor_supply_chain_v1_BypassCorridorOption:
            type: object
            properties:
                id:
                    type: string
                name:
                    type: string
                type:
                    type: string
                addedTransitDays:
                    type: integer
                    format: int32
                addedCostMultiplier:
                    type: number
                    format: double
                warRiskTier:
                    type: string
                status:
                    type: string
                    enum:
                        - CORRIDOR_STATUS_UNSPECIFIED
                        - CORRIDOR_STATUS_ACTIVE
                        - CORRIDOR_STATUS_PROPOSED
                        - CORRIDOR_STATUS_UNAVAILABLE
                    description: |-
                        Status of a bypass corridor for UI labeling. "active" means usable today;
                         "proposed" means documented but not yet built/operational; "unavailable"
                         means blockaded or otherwise blocked from use.
                fromPort:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GeoPoint'
                toPort:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_GeoPoint'
            description: |-
                BypassCorridorOption is a single enriched bypass corridor for the Route Explorer UI.
                 Includes coordinate endpoints so the client can call MapContainer.setBypassRoutes
                 directly without any client-side geometry lookup.
        worldmonitor_supply_chain_v1_NumberRange:
            type: object
            properties:
                min:
                    type: integer
                    format: int32
                max:
                    type: integer
                    format: int32
            description: Inclusive integer range for transit days / freight USD estimates.
        worldmonitor_supply_chain_v1_GetRouteImpactRequest:
            type: object
            properties:
                fromIso2:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 origin country code for the route.
                toIso2:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 destination country code for the route.
                hs2:
                    type: string
                    description: HS2 chapter code for the product sector on the route.
            required:
                - fromIso2
                - toIso2
                - hs2
        worldmonitor_supply_chain_v1_GetRouteImpactResponse:
            type: object
            properties:
                laneValueUsd:
                    type: number
                    format: double
                primaryExporterIso2:
                    type: string
                primaryExporterShare:
                    type: number
                    format: double
                topStrategicProducts:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_StrategicProduct'
                resilienceScore:
                    type: number
                    format: double
                dependencyFlags:
                    type: array
                    items:
                        type: string
                        enum:
                            - DEPENDENCY_FLAG_UNSPECIFIED
                            - DEPENDENCY_FLAG_SINGLE_SOURCE_CRITICAL
                            - DEPENDENCY_FLAG_SINGLE_CORRIDOR_CRITICAL
                            - DEPENDENCY_FLAG_COMPOUND_RISK
                            - DEPENDENCY_FLAG_DIVERSIFIABLE
                        description: DependencyFlag classifies how a country+sector dependency can fail.
                hs2InSeededUniverse:
                    type: boolean
                comtradeSource:
                    type: string
                fetchedAt:
                    type: string
        worldmonitor_supply_chain_v1_StrategicProduct:
            type: object
            properties:
                hs4:
                    type: string
                label:
                    type: string
                totalValueUsd:
                    type: number
                    format: double
                topExporterIso2:
                    type: string
                topExporterShare:
                    type: number
                    format: double
                primaryChokepointId:
                    type: string
        worldmonitor_supply_chain_v1_ListPipelinesRequest:
            type: object
            properties:
                commodityType:
                    type: string
                    description: Filter to one commodity. Omit (or pass empty) to receive both.
            description: |-
                ListPipelines returns the full oil and/or gas pipeline registry with
                 evidence-based status per asset. Registry is curated (see
                 docs/methodology/pipelines.mdx) and refreshed weekly by
                 scripts/seed-pipelines-{gas,oil}.mjs. Typical consumer: PipelineStatusPanel
                 rendering the DeckGL PathLayer.

                 The public badge is DERIVED from the evidence bundle server-side at
                 read time — callers MUST use `public_badge` for display, not invent
                 their own derivation from `evidence` fields. This keeps the atlas and
                 MCP clients consistent and versioned together.
        worldmonitor_supply_chain_v1_ListPipelinesResponse:
            type: object
            properties:
                pipelines:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_PipelineEntry'
                fetchedAt:
                    type: string
                classifierVersion:
                    type: string
                upstreamUnavailable:
                    type: boolean
        worldmonitor_supply_chain_v1_PipelineEntry:
            type: object
            properties:
                id:
                    type: string
                name:
                    type: string
                operator:
                    type: string
                commodityType:
                    type: string
                    description: Either "gas" or "oil".
                fromCountry:
                    type: string
                toCountry:
                    type: string
                transitCountries:
                    type: array
                    items:
                        type: string
                capacityBcmYr:
                    type: number
                    format: double
                capacityMbd:
                    type: number
                    format: double
                lengthKm:
                    type: integer
                    format: int32
                inService:
                    type: integer
                    format: int32
                startPoint:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_LatLon'
                endPoint:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_LatLon'
                waypoints:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_LatLon'
                evidence:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_PipelineEvidence'
                publicBadge:
                    type: string
                    description: |-
                        Server-derived public badge. One of:
                           "flowing" | "reduced" | "offline" | "disputed"
        worldmonitor_supply_chain_v1_LatLon:
            type: object
            properties:
                lat:
                    type: number
                    format: double
                lon:
                    type: number
                    format: double
        worldmonitor_supply_chain_v1_PipelineEvidence:
            type: object
            properties:
                physicalState:
                    type: string
                    description: 'One of: "flowing" | "reduced" | "offline" | "unknown"'
                physicalStateSource:
                    type: string
                    description: 'One of: "operator" | "regulator" | "press" | "satellite" | "ais-relay"'
                operatorStatement:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_OperatorStatement'
                commercialState:
                    type: string
                    description: 'One of: "under_contract" | "expired" | "suspended" | "unknown"'
                sanctionRefs:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_SanctionRef'
                lastEvidenceUpdate:
                    type: string
                classifierVersion:
                    type: string
                classifierConfidence:
                    type: number
                    format: double
        worldmonitor_supply_chain_v1_OperatorStatement:
            type: object
            properties:
                text:
                    type: string
                url:
                    type: string
                date:
                    type: string
        worldmonitor_supply_chain_v1_SanctionRef:
            type: object
            properties:
                authority:
                    type: string
                listId:
                    type: string
                date:
                    type: string
                url:
                    type: string
        worldmonitor_supply_chain_v1_GetPipelineDetailRequest:
            type: object
            properties:
                pipelineId:
                    type: string
                    description: Pipeline identifier to load with full evidence details.
            required:
                - pipelineId
            description: |-
                GetPipelineDetail returns a single pipeline with its full evidence bundle.
                 Evidence surface here is richer than ListPipelinesResponse — the list view
                 is designed for the map layer's compact shape; detail is designed for the
                 click-through drawer.
        worldmonitor_supply_chain_v1_GetPipelineDetailResponse:
            type: object
            properties:
                pipeline:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_PipelineEntry'
                revisions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_PipelineRevisionEntry'
                fetchedAt:
                    type: string
                unavailable:
                    type: boolean
        worldmonitor_supply_chain_v1_PipelineRevisionEntry:
            type: object
            properties:
                date:
                    type: string
                fieldChanged:
                    type: string
                previousValue:
                    type: string
                newValue:
                    type: string
                trigger:
                    type: string
                    description: 'One of: "classifier" | "source" | "decay" | "override"'
                sourcesUsed:
                    type: array
                    items:
                        type: string
                classifierVersion:
                    type: string
        worldmonitor_supply_chain_v1_ListStorageFacilitiesRequest:
            type: object
            properties:
                facilityType:
                    type: string
                    description: |-
                        Filter to one facility type. Accepts:
                           "ugs" | "spr" | "lng_export" | "lng_import" | "crude_tank_farm"
                         Omit (or pass empty) to receive all types.
            description: |-
                ListStorageFacilities returns the curated strategic storage registry
                 (underground gas storage, strategic petroleum reserves, LNG terminals,
                 crude tank farms) with evidence-based status per asset. Registry is
                 curated (see docs/methodology/storage.mdx) and refreshed weekly by
                 scripts/seed-storage-facilities.mjs. Typical consumer:
                 StorageFacilityMapPanel rendering the DeckGL ScatterplotLayer.

                 Like pipelines, the public badge is DERIVED from the evidence bundle
                 server-side at read time. Callers MUST use `public_badge` for display
                 rather than inventing their own derivation from `evidence` fields, so
                 the atlas and MCP clients stay consistent and versioned together.
        worldmonitor_supply_chain_v1_ListStorageFacilitiesResponse:
            type: object
            properties:
                facilities:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_StorageFacilityEntry'
                fetchedAt:
                    type: string
                classifierVersion:
                    type: string
                upstreamUnavailable:
                    type: boolean
        worldmonitor_supply_chain_v1_StorageFacilityEntry:
            type: object
            properties:
                id:
                    type: string
                name:
                    type: string
                operator:
                    type: string
                facilityType:
                    type: string
                    description: 'One of: "ugs" | "spr" | "lng_export" | "lng_import" | "crude_tank_farm"'
                country:
                    type: string
                location:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_StorageLatLon'
                capacityTwh:
                    type: number
                    format: double
                    description: |-
                        Working capacity in the facility's native unit (see working_capacity_unit).
                         Exactly ONE of these is populated per facility, chosen by facility_type:
                           ugs                              → capacity_twh
                           spr, crude_tank_farm             → capacity_mb
                           lng_export, lng_import           → capacity_mtpa
                capacityMb:
                    type: number
                    format: double
                capacityMtpa:
                    type: number
                    format: double
                workingCapacityUnit:
                    type: string
                    description: 'One of: "TWh" | "Mb" | "Mtpa"'
                inService:
                    type: integer
                    format: int32
                evidence:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_StorageEvidence'
                publicBadge:
                    type: string
                    description: |-
                        Server-derived public badge. One of:
                           "operational" | "reduced" | "offline" | "disputed"
        worldmonitor_supply_chain_v1_StorageLatLon:
            type: object
            properties:
                lat:
                    type: number
                    format: double
                lon:
                    type: number
                    format: double
        worldmonitor_supply_chain_v1_StorageEvidence:
            type: object
            properties:
                physicalState:
                    type: string
                    description: 'One of: "operational" | "reduced" | "offline" | "under_construction" | "unknown"'
                physicalStateSource:
                    type: string
                    description: 'One of: "operator" | "regulator" | "press" | "satellite" | "ais-relay"'
                operatorStatement:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_StorageOperatorStatement'
                commercialState:
                    type: string
                    description: 'One of: "under_contract" | "expired" | "suspended" | "unknown"'
                sanctionRefs:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_StorageSanctionRef'
                fillDisclosed:
                    type: boolean
                    description: |-
                        Whether working-gas / stock-level fill is publicly disclosed for this
                         asset. LNG export terminals, for instance, tend NOT to disclose; UGS
                         sites in Europe are required to disclose via GIE AGSI+.
                fillSource:
                    type: string
                    description: |-
                        Source of the disclosed fill series ("GIE AGSI+", "EIA SPR weekly
                         stock report", etc.). Empty when fill_disclosed=false.
                lastEvidenceUpdate:
                    type: string
                classifierVersion:
                    type: string
                classifierConfidence:
                    type: number
                    format: double
        worldmonitor_supply_chain_v1_StorageOperatorStatement:
            type: object
            properties:
                text:
                    type: string
                url:
                    type: string
                date:
                    type: string
        worldmonitor_supply_chain_v1_StorageSanctionRef:
            type: object
            properties:
                authority:
                    type: string
                listId:
                    type: string
                date:
                    type: string
                url:
                    type: string
        worldmonitor_supply_chain_v1_GetStorageFacilityDetailRequest:
            type: object
            properties:
                facilityId:
                    type: string
                    description: Storage facility identifier to load with full evidence details.
            required:
                - facilityId
            description: |-
                GetStorageFacilityDetail returns a single facility with its full evidence
                 bundle + revision log. Revisions land in Week 3 alongside the disruption
                 event log (Week 3 milestone — empty array in v1).
        worldmonitor_supply_chain_v1_GetStorageFacilityDetailResponse:
            type: object
            properties:
                facility:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_StorageFacilityEntry'
                revisions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_StorageFacilityRevisionEntry'
                fetchedAt:
                    type: string
                unavailable:
                    type: boolean
        worldmonitor_supply_chain_v1_StorageFacilityRevisionEntry:
            type: object
            properties:
                date:
                    type: string
                fieldChanged:
                    type: string
                previousValue:
                    type: string
                newValue:
                    type: string
                trigger:
                    type: string
                    description: 'One of: "classifier" | "source" | "decay" | "override"'
                sourcesUsed:
                    type: array
                    items:
                        type: string
                classifierVersion:
                    type: string
        worldmonitor_supply_chain_v1_ListFuelShortagesRequest:
            type: object
            properties:
                country:
                    type: string
                    description: Filter to one ISO 3166-1 alpha-2 country. Omit for global.
                product:
                    type: string
                    description: |-
                        Filter to one product. Accepts: "petrol" | "diesel" | "jet" | "heating_oil".
                         Omit for all products.
                severity:
                    type: string
                    description: 'Filter to one severity. Accepts: "confirmed" | "watch". Omit for both.'
            description: |-
                ListFuelShortages returns the global fuel-shortage alert registry.
                 Seeded from a curated JSON file (scripts/data/fuel-shortages.json).
                 An LLM classifier extension was scoped but not shipped — the registry
                 is curated-only today. Severity ("confirmed" or "watch") is a row
                 field authored at curation time; the evidence is shipped alongside
                 so agents and humans can audit the grounds for a severity label.

                 See docs/methodology/shortages.mdx for the evidence-threshold spec.
        worldmonitor_supply_chain_v1_ListFuelShortagesResponse:
            type: object
            properties:
                shortages:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_FuelShortageEntry'
                fetchedAt:
                    type: string
                classifierVersion:
                    type: string
                upstreamUnavailable:
                    type: boolean
        worldmonitor_supply_chain_v1_FuelShortageEntry:
            type: object
            properties:
                id:
                    type: string
                country:
                    type: string
                product:
                    type: string
                    description: 'One of: "petrol" | "diesel" | "jet" | "heating_oil"'
                severity:
                    type: string
                    description: 'One of: "confirmed" | "watch"  (classifier output — not a client-side derivation)'
                firstSeen:
                    type: string
                lastConfirmed:
                    type: string
                resolvedAt:
                    type: string
                    description: Empty string when not yet resolved.
                impactTypes:
                    type: array
                    items:
                        type: string
                        description: |-
                            Observable consumer-facing impacts. Subset of:
                               "stations_closed" | "rationing" | "flights_cancelled" | "import_cut" | "price_spike"
                causeChain:
                    type: array
                    items:
                        type: string
                        description: |-
                            Contributing root causes, ordered primary-first. Subset of:
                               "upstream_refinery" | "logistics" | "policy" | "chokepoint" |
                               "sanction" | "war" | "import_cut"
                shortDescription:
                    type: string
                evidence:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_FuelShortageEvidence'
        worldmonitor_supply_chain_v1_FuelShortageEvidence:
            type: object
            properties:
                evidenceSources:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_FuelShortageEvidenceSource'
                firstRegulatorConfirmation:
                    type: string
                    description: |-
                        ISO date of the first regulator confirmation, if any. Empty when
                         severity is "watch" on press-only signal.
                classifierVersion:
                    type: string
                classifierConfidence:
                    type: number
                    format: double
                lastEvidenceUpdate:
                    type: string
        worldmonitor_supply_chain_v1_FuelShortageEvidenceSource:
            type: object
            properties:
                authority:
                    type: string
                title:
                    type: string
                url:
                    type: string
                date:
                    type: string
                sourceType:
                    type: string
                    description: 'One of: "regulator" | "operator" | "press" | "ais-relay" | "satellite"'
        worldmonitor_supply_chain_v1_GetFuelShortageDetailRequest:
            type: object
            properties:
                shortageId:
                    type: string
                    description: Fuel-shortage identifier to load with full evidence details.
            required:
                - shortageId
            description: |-
                GetFuelShortageDetail returns a single shortage with full evidence
                 bundle + citation timeline. Loaded lazily on drawer open.
        worldmonitor_supply_chain_v1_GetFuelShortageDetailResponse:
            type: object
            properties:
                shortage:
                    $ref: '#/components/schemas/worldmonitor_supply_chain_v1_FuelShortageEntry'
                fetchedAt:
                    type: string
                unavailable:
                    type: boolean
        worldmonitor_supply_chain_v1_ListEnergyDisruptionsRequest:
            type: object
            properties:
                assetId:
                    type: string
                    description: |-
                        Filter to one asset. Omit for all. When set, also narrows to the
                         matching asset_type if provided.
                assetType:
                    type: string
                    description: 'Filter to one asset type. Accepts: "pipeline" | "storage".'
                ongoingOnly:
                    type: boolean
                    description: If true, only return events with endAt empty (still ongoing).
            description: |-
                ListEnergyDisruptions returns the energy disruption event log — state
                 transitions for pipelines and storage facilities (sabotage, sanction,
                 maintenance, mechanical, weather, commercial, war). Each event ties
                 back to an assetId seeded by the pipeline or storage registry, so the
                 panel drawer can render an asset-scoped timeline without a second RPC.

                 Seeded from a curated JSON file (scripts/data/energy-disruptions.json).
                 An automated state-transition classifier was scoped but not shipped —
                 the log is curated-only today.

                 See docs/methodology/disruptions.mdx.
        worldmonitor_supply_chain_v1_ListEnergyDisruptionsResponse:
            type: object
            properties:
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_EnergyDisruptionEntry'
                fetchedAt:
                    type: string
                classifierVersion:
                    type: string
                upstreamUnavailable:
                    type: boolean
        worldmonitor_supply_chain_v1_EnergyDisruptionEntry:
            type: object
            properties:
                id:
                    type: string
                assetId:
                    type: string
                    description: Maps to a pipeline or storage-facility id seeded elsewhere.
                assetType:
                    type: string
                    description: 'One of: "pipeline" | "storage"'
                eventType:
                    type: string
                    description: |-
                        One of: "sabotage" | "sanction" | "maintenance" | "mechanical" |
                                 "weather" | "commercial" | "war" | "other"
                startAt:
                    type: string
                endAt:
                    type: string
                    description: Empty string when event is still ongoing.
                capacityOfflineBcmYr:
                    type: number
                    format: double
                    description: Headline-offline capacity (contextual — 0 when not applicable).
                capacityOfflineMbd:
                    type: number
                    format: double
                causeChain:
                    type: array
                    items:
                        type: string
                        description: Contributing causes, primary-first.
                shortDescription:
                    type: string
                sources:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_supply_chain_v1_EnergyDisruptionSource'
                classifierVersion:
                    type: string
                classifierConfidence:
                    type: number
                    format: double
                lastEvidenceUpdate:
                    type: string
                countries:
                    type: array
                    items:
                        type: string
                        description: |-
                            Countries touched by the referenced asset (pipeline: fromCountry +
                             toCountry + transitCountries; storage: country). Denormalised at seed
                             time so CountryDeepDivePanel can filter events without a second RPC.
                             Always non-empty in well-formed payloads; empty only if the upstream
                             asset was removed without an event update. Per plan §R/#5 decision B.
        worldmonitor_supply_chain_v1_EnergyDisruptionSource:
            type: object
            properties:
                authority:
                    type: string
                title:
                    type: string
                url:
                    type: string
                date:
                    type: string
                sourceType:
                    type: string
        worldmonitor_thermal_v1_ListThermalEscalationsRequest:
            type: object
            properties:
                maxItems:
                    type: integer
                    format: int32
                    description: Maximum number of thermal escalation clusters to return.
        worldmonitor_thermal_v1_ListThermalEscalationsResponse:
            type: object
            properties:
                fetchedAt:
                    type: string
                    description: |-
                        ISO-8601 time the seed snapshot was fetched. Empty string means the
                         snapshot is unavailable/degraded, not that thermal escalation is confirmed
                         absent.
                observationWindowHours:
                    type: integer
                    format: int32
                sourceVersion:
                    type: string
                clusters:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_thermal_v1_ThermalEscalationCluster'
                summary:
                    $ref: '#/components/schemas/worldmonitor_thermal_v1_ThermalEscalationSummary'
                dataAvailable:
                    type: boolean
                    description: |-
                        True when clusters came from a seed snapshot. False means an empty payload
                         is graceful degradation because the snapshot is unavailable.
        worldmonitor_thermal_v1_ThermalEscalationCluster:
            type: object
            properties:
                id:
                    type: string
                centroid:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                countryCode:
                    type: string
                countryName:
                    type: string
                regionLabel:
                    type: string
                firstDetectedAt:
                    type: string
                lastDetectedAt:
                    type: string
                observationCount:
                    type: integer
                    format: int32
                uniqueSourceCount:
                    type: integer
                    format: int32
                maxBrightness:
                    type: number
                    format: double
                avgBrightness:
                    type: number
                    format: double
                maxFrp:
                    type: number
                    format: double
                totalFrp:
                    type: number
                    format: double
                nightDetectionShare:
                    type: number
                    format: double
                baselineExpectedCount:
                    type: number
                    format: double
                baselineExpectedFrp:
                    type: number
                    format: double
                countDelta:
                    type: number
                    format: double
                frpDelta:
                    type: number
                    format: double
                zScore:
                    type: number
                    format: double
                persistenceHours:
                    type: number
                    format: double
                status:
                    type: string
                    enum:
                        - THERMAL_STATUS_UNSPECIFIED
                        - THERMAL_STATUS_NORMAL
                        - THERMAL_STATUS_ELEVATED
                        - THERMAL_STATUS_SPIKE
                        - THERMAL_STATUS_PERSISTENT
                context:
                    type: string
                    enum:
                        - THERMAL_CONTEXT_UNSPECIFIED
                        - THERMAL_CONTEXT_WILDLAND
                        - THERMAL_CONTEXT_URBAN_EDGE
                        - THERMAL_CONTEXT_INDUSTRIAL
                        - THERMAL_CONTEXT_ENERGY_ADJACENT
                        - THERMAL_CONTEXT_CONFLICT_ADJACENT
                        - THERMAL_CONTEXT_LOGISTICS_ADJACENT
                        - THERMAL_CONTEXT_MIXED
                confidence:
                    type: string
                    enum:
                        - THERMAL_CONFIDENCE_UNSPECIFIED
                        - THERMAL_CONFIDENCE_LOW
                        - THERMAL_CONFIDENCE_MEDIUM
                        - THERMAL_CONFIDENCE_HIGH
                strategicRelevance:
                    type: string
                    enum:
                        - THERMAL_RELEVANCE_UNSPECIFIED
                        - THERMAL_RELEVANCE_LOW
                        - THERMAL_RELEVANCE_MEDIUM
                        - THERMAL_RELEVANCE_HIGH
                nearbyAssets:
                    type: array
                    items:
                        type: string
                narrativeFlags:
                    type: array
                    items:
                        type: string
        worldmonitor_thermal_v1_ThermalEscalationSummary:
            type: object
            properties:
                clusterCount:
                    type: integer
                    format: int32
                elevatedCount:
                    type: integer
                    format: int32
                spikeCount:
                    type: integer
                    format: int32
                persistentCount:
                    type: integer
                    format: int32
                conflictAdjacentCount:
                    type: integer
                    format: int32
                highRelevanceCount:
                    type: integer
                    format: int32
        worldmonitor_trade_v1_GetTradeRestrictionsRequest:
            type: object
            properties:
                countries:
                    type: array
                    items:
                        type: string
                        description: |-
                            WTO member codes to filter by. Empty = all.
                             Accepted but currently ignored; no-op until this handler supports the parameter.
                limit:
                    type: integer
                    format: int32
                    description: Max results to return (server caps at 100).
            description: Request for quantitative restriction data.
        worldmonitor_trade_v1_GetTradeRestrictionsResponse:
            type: object
            properties:
                restrictions:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_trade_v1_TradeRestriction'
                fetchedAt:
                    type: string
                    description: ISO 8601 timestamp when data was fetched from WTO.
                upstreamUnavailable:
                    type: boolean
                    description: True if upstream fetch failed and results may be stale/empty.
            description: Response containing trade restrictions and fetch metadata.
        worldmonitor_trade_v1_TradeRestriction:
            type: object
            properties:
                id:
                    type: string
                    description: Unique restriction identifier from WTO.
                reportingCountry:
                    type: string
                    description: ISO 3166-1 alpha-3 or WTO member code of reporting country.
                affectedCountry:
                    type: string
                    description: Country affected by the restriction.
                productSector:
                    type: string
                    description: Product sector or HS chapter description.
                measureType:
                    type: string
                    description: 'Measure classification: "QR", "EXPORT_BAN", "IMPORT_BAN", "LICENSING".'
                description:
                    type: string
                    description: Human-readable description of the measure.
                status:
                    type: string
                    description: 'Current status: "IN_FORCE", "TERMINATED", "NOTIFIED".'
                notifiedAt:
                    type: string
                    description: ISO 8601 date when measure was notified.
                sourceUrl:
                    type: string
                    description: WTO source document URL (must be http/https protocol).
            description: Quantitative restriction or export control measure notified to WTO.
        worldmonitor_trade_v1_GetTariffTrendsRequest:
            type: object
            properties:
                reportingCountry:
                    type: string
                    description: WTO member code of reporting country (e.g. "840" = US).
                partnerCountry:
                    type: string
                    description: WTO member code of partner country (e.g. "156" = China).
                productSector:
                    type: string
                    description: Product sector filter (HS chapter). Empty = aggregate.
                years:
                    type: integer
                    format: int32
                    description: Number of years to look back (default 10, max 30).
            description: Request for tariff timeseries data.
        worldmonitor_trade_v1_GetTariffTrendsResponse:
            type: object
            properties:
                datapoints:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_trade_v1_TariffDataPoint'
                fetchedAt:
                    type: string
                    description: ISO 8601 timestamp when data was fetched from WTO.
                upstreamUnavailable:
                    type: boolean
                    description: True if upstream fetch failed and results may be stale/empty.
                effectiveTariffRate:
                    $ref: '#/components/schemas/worldmonitor_trade_v1_EffectiveTariffRate'
            description: Response containing tariff trend datapoints.
        worldmonitor_trade_v1_TariffDataPoint:
            type: object
            properties:
                reportingCountry:
                    type: string
                    description: WTO member code of reporting country.
                partnerCountry:
                    type: string
                    description: WTO member code of partner country.
                productSector:
                    type: string
                    description: Product sector or HS chapter.
                year:
                    type: integer
                    format: int32
                    description: Year of observation.
                tariffRate:
                    type: number
                    format: double
                    description: Applied MFN tariff rate (percentage).
                boundRate:
                    type: number
                    format: double
                    description: WTO bound tariff rate (percentage).
                indicatorCode:
                    type: string
                    description: WTO indicator code used for this datapoint.
            description: Single tariff data point for a reporter-partner-product combination.
        worldmonitor_trade_v1_EffectiveTariffRate:
            type: object
            properties:
                sourceName:
                    type: string
                    description: Source name for the effective-rate estimate.
                sourceUrl:
                    type: string
                    description: Canonical source URL for the estimate/methodology.
                observationPeriod:
                    type: string
                    description: Human-readable observation period (for example "December 2025").
                updatedAt:
                    type: string
                    description: ISO 8601 date when the source page was last updated, if known.
                tariffRate:
                    type: number
                    format: double
                    description: Effective tariff rate (percentage).
            description: Current effective tariff estimate for countries with coverage beyond WTO MFN baselines.
        worldmonitor_trade_v1_GetTradeFlowsRequest:
            type: object
            properties:
                reportingCountry:
                    type: string
                    description: WTO member code of reporting country.
                partnerCountry:
                    type: string
                    description: WTO member code of partner country.
                years:
                    type: integer
                    format: int32
                    description: Number of years to look back (default 10, max 30).
            description: Request for bilateral trade flow data.
        worldmonitor_trade_v1_GetTradeFlowsResponse:
            type: object
            properties:
                flows:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_trade_v1_TradeFlowRecord'
                fetchedAt:
                    type: string
                    description: ISO 8601 timestamp when data was fetched from WTO.
                upstreamUnavailable:
                    type: boolean
                    description: True if upstream fetch failed and results may be stale/empty.
            description: Response containing trade flow records.
        worldmonitor_trade_v1_TradeFlowRecord:
            type: object
            properties:
                reportingCountry:
                    type: string
                    description: WTO member code of reporting country.
                partnerCountry:
                    type: string
                    description: WTO member code of partner country.
                year:
                    type: integer
                    format: int32
                    description: Year of observation.
                exportValueUsd:
                    type: number
                    format: double
                    description: Merchandise export value in millions USD.
                importValueUsd:
                    type: number
                    format: double
                    description: Merchandise import value in millions USD.
                yoyExportChange:
                    type: number
                    format: double
                    description: Year-over-year export change (percentage).
                yoyImportChange:
                    type: number
                    format: double
                    description: Year-over-year import change (percentage).
                productSector:
                    type: string
                    description: Product sector or HS chapter.
            description: Bilateral trade flow record for a reporting-partner pair.
        worldmonitor_trade_v1_GetTradeBarriersRequest:
            type: object
            properties:
                countries:
                    type: array
                    items:
                        type: string
                        description: |-
                            WTO member codes to filter by. Empty = all.
                             Accepted but currently ignored; no-op until this handler supports the parameter.
                measureType:
                    type: string
                    description: |-
                        Filter by measure type: "SPS", "TBT", or empty for both.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                limit:
                    type: integer
                    format: int32
                    description: Max results to return (server caps at 100).
            description: Request for SPS/TBT trade barrier notifications.
        worldmonitor_trade_v1_GetTradeBarriersResponse:
            type: object
            properties:
                barriers:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_trade_v1_TradeBarrier'
                fetchedAt:
                    type: string
                    description: ISO 8601 timestamp when data was fetched from WTO.
                upstreamUnavailable:
                    type: boolean
                    description: True if upstream fetch failed and results may be stale/empty.
            description: Response containing trade barrier notifications.
        worldmonitor_trade_v1_TradeBarrier:
            type: object
            properties:
                id:
                    type: string
                    description: Unique barrier notification identifier.
                notifyingCountry:
                    type: string
                    description: Country that notified the measure.
                title:
                    type: string
                    description: Title of the notification.
                measureType:
                    type: string
                    description: 'Measure classification: "SPS" or "TBT".'
                productDescription:
                    type: string
                    description: Product description or affected goods.
                objective:
                    type: string
                    description: Stated objective of the measure.
                status:
                    type: string
                    description: Status of the notification.
                dateDistributed:
                    type: string
                    description: ISO 8601 date when notification was distributed.
                sourceUrl:
                    type: string
                    description: WTO source document URL (must be http/https protocol).
            description: SPS or TBT trade barrier notification.
        worldmonitor_trade_v1_GetCustomsRevenueRequest:
            type: object
        worldmonitor_trade_v1_GetCustomsRevenueResponse:
            type: object
            properties:
                months:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_trade_v1_CustomsRevenueMonth'
                fetchedAt:
                    type: string
                upstreamUnavailable:
                    type: boolean
        worldmonitor_trade_v1_CustomsRevenueMonth:
            type: object
            properties:
                recordDate:
                    type: string
                fiscalYear:
                    type: integer
                    format: int32
                calendarYear:
                    type: integer
                    format: int32
                calendarMonth:
                    type: integer
                    format: int32
                monthlyAmountBillions:
                    type: number
                    format: double
                fytdAmountBillions:
                    type: number
                    format: double
            description: Monthly US customs duties revenue from Treasury MTS data.
        worldmonitor_trade_v1_ListComtradeFlowsRequest:
            type: object
            properties:
                reporterCode:
                    type: string
                    description: UN Comtrade reporter code (e.g. "842" = US, "156" = China). Empty returns all reporters.
                cmdCode:
                    type: string
                    description: HS commodity code (e.g. "2709" = crude oil). Empty returns all commodities.
                anomaliesOnly:
                    type: boolean
                    description: If true, only return flows with a year-over-year change exceeding 30%.
            description: ListComtradeFlowsRequest filters strategic commodity trade flows.
        worldmonitor_trade_v1_ListComtradeFlowsResponse:
            type: object
            properties:
                flows:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_trade_v1_ComtradeFlowRecord'
                fetchedAt:
                    type: string
                    description: ISO 8601 timestamp when data was seeded.
                upstreamUnavailable:
                    type: boolean
                    description: True if seeded data is missing or stale.
            description: ListComtradeFlowsResponse contains strategic commodity trade flows.
        worldmonitor_trade_v1_ComtradeFlowRecord:
            type: object
            properties:
                reporterCode:
                    type: string
                    description: UN Comtrade reporter code.
                reporterName:
                    type: string
                    description: Reporter country name.
                partnerCode:
                    type: string
                    description: Partner country code ("000" = world total).
                partnerName:
                    type: string
                    description: Partner country name.
                cmdCode:
                    type: string
                    description: HS commodity code.
                cmdDesc:
                    type: string
                    description: Commodity description.
                year:
                    type: integer
                    format: int32
                    description: Reporting year.
                tradeValueUsd:
                    type: number
                    format: double
                    description: Trade value in USD.
                netWeightKg:
                    type: number
                    format: double
                    description: Net weight in kg.
                yoyChange:
                    type: number
                    format: double
                    description: Year-over-year change (ratio, e.g. 0.35 = +35%).
                isAnomaly:
                    type: boolean
                    description: True if the YoY change exceeds the anomaly threshold (30%).
            description: ComtradeFlowRecord is a single bilateral commodity flow record.
        worldmonitor_unrest_v1_ListUnrestEventsRequest:
            type: object
            properties:
                start:
                    type: integer
                    format: int64
                    description: 'Start of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                end:
                    type: integer
                    format: int64
                    description: 'End of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                pageSize:
                    type: integer
                    format: int32
                    description: |-
                        Maximum items per page (1-100).
                         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.
                country:
                    type: string
                    description: Optional country filter (ISO 3166-1 alpha-2).
                minSeverity:
                    type: string
                    enum:
                        - SEVERITY_LEVEL_UNSPECIFIED
                        - SEVERITY_LEVEL_LOW
                        - SEVERITY_LEVEL_MEDIUM
                        - SEVERITY_LEVEL_HIGH
                    description: |-
                        SeverityLevel represents a three-tier severity classification used across domains.
                         Maps to existing TS unions: 'low' | 'medium' | 'high'.
                neLat:
                    type: number
                    format: double
                    description: |-
                        North-east corner latitude of bounding box.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                neLon:
                    type: number
                    format: double
                    description: |-
                        North-east corner longitude of bounding box.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                swLat:
                    type: number
                    format: double
                    description: |-
                        South-west corner latitude of bounding box.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                swLon:
                    type: number
                    format: double
                    description: |-
                        South-west corner longitude of bounding box.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
            description: ListUnrestEventsRequest specifies filters for retrieving social unrest events.
        worldmonitor_unrest_v1_ListUnrestEventsResponse:
            type: object
            properties:
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_unrest_v1_UnrestEvent'
                clusters:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_unrest_v1_UnrestCluster'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
            description: ListUnrestEventsResponse contains unrest events and clusters matching the request.
        worldmonitor_unrest_v1_UnrestEvent:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Unique event identifier.
                title:
                    type: string
                    description: Event title or headline.
                summary:
                    type: string
                    description: Brief summary of the event.
                eventType:
                    type: string
                    enum:
                        - UNREST_EVENT_TYPE_UNSPECIFIED
                        - UNREST_EVENT_TYPE_PROTEST
                        - UNREST_EVENT_TYPE_RIOT
                        - UNREST_EVENT_TYPE_STRIKE
                        - UNREST_EVENT_TYPE_DEMONSTRATION
                        - UNREST_EVENT_TYPE_CIVIL_UNREST
                    description: |-
                        UnrestEventType represents the classification of a social unrest event.
                         Maps to existing TS union: 'protest' | 'riot' | 'strike' | 'demonstration' | 'civil_unrest'.
                city:
                    type: string
                    description: City where the event occurred.
                country:
                    type: string
                    description: Country where the event occurred.
                region:
                    type: string
                    description: Administrative region within the country.
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                occurredAt:
                    type: integer
                    format: int64
                    description: 'Time the event occurred, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                severity:
                    type: string
                    enum:
                        - SEVERITY_LEVEL_UNSPECIFIED
                        - SEVERITY_LEVEL_LOW
                        - SEVERITY_LEVEL_MEDIUM
                        - SEVERITY_LEVEL_HIGH
                    description: |-
                        SeverityLevel represents a three-tier severity classification used across domains.
                         Maps to existing TS unions: 'low' | 'medium' | 'high'.
                fatalities:
                    type: integer
                    format: int32
                    description: Reported fatalities, if any.
                sources:
                    type: array
                    items:
                        type: string
                        description: Source identifiers.
                sourceType:
                    type: string
                    enum:
                        - UNREST_SOURCE_TYPE_UNSPECIFIED
                        - UNREST_SOURCE_TYPE_ACLED
                        - UNREST_SOURCE_TYPE_GDELT
                        - UNREST_SOURCE_TYPE_RSS
                    description: |-
                        UnrestSourceType represents the data source for an unrest event.
                         Maps to existing TS union: 'acled' | 'gdelt' | 'rss'.
                tags:
                    type: array
                    items:
                        type: string
                        description: Descriptive tags.
                actors:
                    type: array
                    items:
                        type: string
                        description: Named actors involved.
                confidence:
                    type: string
                    enum:
                        - CONFIDENCE_LEVEL_UNSPECIFIED
                        - CONFIDENCE_LEVEL_LOW
                        - CONFIDENCE_LEVEL_MEDIUM
                        - CONFIDENCE_LEVEL_HIGH
                    description: |-
                        ConfidenceLevel represents the confidence in event data accuracy.
                         Used across multiple domains.
                sourceUrls:
                    type: array
                    items:
                        type: string
                        description: Source article URLs, when provided by the upstream feed.
            required:
                - id
            description: |-
                UnrestEvent represents a social unrest incident (protest, riot, strike, etc.).
                 Aggregated from ACLED and GDELT sources.
        worldmonitor_unrest_v1_UnrestCluster:
            type: object
            properties:
                id:
                    type: string
                    description: Unique cluster identifier.
                country:
                    type: string
                    description: Country of the cluster.
                region:
                    type: string
                    description: Region within the country.
                eventCount:
                    type: integer
                    format: int32
                    description: Number of events in this cluster.
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_unrest_v1_UnrestEvent'
                severity:
                    type: string
                    enum:
                        - SEVERITY_LEVEL_UNSPECIFIED
                        - SEVERITY_LEVEL_LOW
                        - SEVERITY_LEVEL_MEDIUM
                        - SEVERITY_LEVEL_HIGH
                    description: |-
                        SeverityLevel represents a three-tier severity classification used across domains.
                         Maps to existing TS unions: 'low' | 'medium' | 'high'.
                startAt:
                    type: integer
                    format: int64
                    description: 'Start of the cluster time window, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                endAt:
                    type: integer
                    format: int64
                    description: 'End of the cluster time window, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                primaryCause:
                    type: string
                    description: Primary cause or theme of the unrest.
            description: UnrestCluster represents a geographic cluster of related unrest events.
        worldmonitor_webcam_v1_ListWebcamsRequest:
            type: object
            properties:
                zoom:
                    type: integer
                    format: int32
                    description: Map zoom level used to decide whether to return webcams or clusters.
                boundW:
                    type: number
                    format: double
                    description: Western longitude bound of the map viewport.
                boundS:
                    type: number
                    format: double
                    description: Southern latitude bound of the map viewport.
                boundE:
                    type: number
                    format: double
                    description: Eastern longitude bound of the map viewport.
                boundN:
                    type: number
                    format: double
                    description: Northern latitude bound of the map viewport.
        worldmonitor_webcam_v1_ListWebcamsResponse:
            type: object
            properties:
                webcams:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_webcam_v1_WebcamEntry'
                clusters:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_webcam_v1_WebcamCluster'
                totalInView:
                    type: integer
                    format: int32
        worldmonitor_webcam_v1_WebcamEntry:
            type: object
            properties:
                webcamId:
                    type: string
                title:
                    type: string
                lat:
                    type: number
                    format: double
                lng:
                    type: number
                    format: double
                category:
                    type: string
                country:
                    type: string
        worldmonitor_webcam_v1_WebcamCluster:
            type: object
            properties:
                lat:
                    type: number
                    format: double
                lng:
                    type: number
                    format: double
                count:
                    type: integer
                    format: int32
                categories:
                    type: array
                    items:
                        type: string
        worldmonitor_webcam_v1_GetWebcamImageRequest:
            type: object
            properties:
                webcamId:
                    type: string
                    description: Webcam identifier to resolve into image and player URLs.
        worldmonitor_webcam_v1_GetWebcamImageResponse:
            type: object
            properties:
                thumbnailUrl:
                    type: string
                playerUrl:
                    type: string
                title:
                    type: string
                windyUrl:
                    type: string
                lastUpdated:
                    type: string
                    description: |-
                        ISO-8601 datetime string of the webcam's most recent update
                         (e.g. "2026-07-03T12:00:00.000Z"); empty string when unknown or unavailable.
                         String (not int64): the handler emits new Date(...).toISOString(), so the
                         field carries a datetime string, never epoch milliseconds.
                error:
                    type: string
        worldmonitor_wildfire_v1_ListFireDetectionsRequest:
            type: object
            properties:
                start:
                    type: integer
                    format: int64
                    description: |-
                        Start of time range (inclusive), Unix epoch milliseconds.
                         Accepted but currently ignored; no-op until this handler supports the parameter.. Warning: Values > 2^53 may lose precision in JavaScript
                end:
                    type: integer
                    format: int64
                    description: |-
                        End of time range (inclusive), Unix epoch milliseconds.
                         Accepted but currently ignored; no-op until this handler supports the parameter.. Warning: Values > 2^53 may lose precision in JavaScript
                pageSize:
                    type: integer
                    format: int32
                    description: |-
                        Maximum items per page (1-100).
                         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.
                neLat:
                    type: number
                    format: double
                    description: |-
                        North-east latitude of bounding box.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                neLon:
                    type: number
                    format: double
                    description: |-
                        North-east longitude of bounding box.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                swLat:
                    type: number
                    format: double
                    description: |-
                        South-west latitude of bounding box.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
                swLon:
                    type: number
                    format: double
                    description: |-
                        South-west longitude of bounding box.
                         Accepted but currently ignored; no-op until this handler supports the parameter.
            description: ListFireDetectionsRequest specifies filters for retrieving fire detections from NASA FIRMS.
        worldmonitor_wildfire_v1_ListFireDetectionsResponse:
            type: object
            properties:
                fireDetections:
                    type: array
                    items:
                        $ref: '#/components/schemas/worldmonitor_wildfire_v1_FireDetection'
                pagination:
                    $ref: '#/components/schemas/worldmonitor_core_v1_PaginationResponse'
                fetchedAt:
                    type: integer
                    format: int64
                    description: |-
                        Time the seed snapshot was fetched, as Unix epoch milliseconds. A value of
                         0 means the snapshot is unavailable/degraded, not that there are confirmed
                         zero active fires.. Warning: Values > 2^53 may lose precision in JavaScript
                dataAvailable:
                    type: boolean
                    description: |-
                        True when fire_detections came from a seed snapshot. False means an empty
                         payload is graceful degradation because the snapshot is unavailable.
            description: ListFireDetectionsResponse contains the list of fire detections matching the request filters.
        worldmonitor_wildfire_v1_FireDetection:
            type: object
            properties:
                id:
                    type: string
                    maxLength: 100
                    minLength: 1
                    description: Unique detection identifier.
                location:
                    $ref: '#/components/schemas/worldmonitor_core_v1_GeoCoordinates'
                brightness:
                    type: number
                    format: double
                    description: Brightness temperature in Kelvin.
                frp:
                    type: number
                    format: double
                    description: Fire radiative power in MW.
                confidence:
                    type: string
                    enum:
                        - FIRE_CONFIDENCE_UNSPECIFIED
                        - FIRE_CONFIDENCE_LOW
                        - FIRE_CONFIDENCE_NOMINAL
                        - FIRE_CONFIDENCE_HIGH
                    description: FireConfidence represents the confidence level of a fire detection.
                satellite:
                    type: string
                    description: Satellite that detected the fire (e.g., "MODIS", "VIIRS", "LANDSAT").
                detectedAt:
                    type: integer
                    format: int64
                    description: 'Time the fire was detected, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                region:
                    type: string
                    description: Monitored region name (e.g., "Ukraine", "Russia", "Iran").
                dayNight:
                    type: string
                    description: Day or night detection ("D" or "N").
                possibleExplosion:
                    type: boolean
                    description: |-
                        Whether the thermal signature suggests a possible explosion rather than a fire
                         (FRP > 80 MW and brightness > 380 K).
            required:
                - id
            description: FireDetection represents a satellite-detected active fire from NASA FIRMS.
