openapi: 3.1.0 info: title: IntelligenceService API version: 1.0.0 security: - WorldMonitorKey: [] - ApiKeyHeader: [] servers: - url: https://api.worldmonitor.app paths: /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/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/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/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/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. PRO-gated. Requires entitlement tier >= 1. operationId: GetCountryIntelBrief security: - WorldMonitorKey: [] - ApiKeyHeader: [] - BearerAuth: [] 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/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: 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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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-china-decision-signals: get: security: [] tags: - IntelligenceService summary: GetChinaDecisionSignals description: |- GetChinaDecisionSignals composes the six launched China decision-parity domains into one bounded provenance-preserving public snapshot. operationId: GetChinaDecisionSignals 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: "generatedAt": "2026-07-26T12:00:00.000Z" "payloadJson": "{\"schemaVersion\":1,\"generatedAt\":\"2026-07-26T12:00:00.000Z\",\"groups\":[{\"id\":\"macro\",\"state\":\"unavailable\",\"reason\":\"No launched, provenance-valid signal is currently available.\",\"items\":[],\"metadata\":{\"totalValidItems\":0,\"omittedItemCount\":0}},{\"id\":\"policy-enforcement\",\"state\":\"unavailable\",\"reason\":\"No launched, provenance-valid signal is currently available.\",\"items\":[],\"metadata\":{\"totalValidItems\":0,\"omittedItemCount\":0}},{\"id\":\"cross-strait-activity\",\"state\":\"unavailable\",\"reason\":\"No launched, provenance-valid signal is currently available.\",\"items\":[],\"metadata\":{\"totalValidItems\":0,\"omittedItemCount\":0}},{\"id\":\"corporate-disclosures\",\"state\":\"unavailable\",\"reason\":\"No launched, provenance-valid signal is currently available.\",\"items\":[],\"metadata\":{\"totalValidItems\":0,\"omittedItemCount\":0}},{\"id\":\"corridor-conditions\",\"state\":\"unavailable\",\"reason\":\"No launched, provenance-valid signal is currently available.\",\"items\":[],\"metadata\":{\"totalValidItems\":0,\"omittedItemCount\":0}},{\"id\":\"activity-nowcast\",\"state\":\"unavailable\",\"reason\":\"No launched, provenance-valid signal is currently available.\",\"items\":[],\"metadata\":{\"totalValidItems\":0,\"omittedItemCount\":0}}],\"access\":{\"anonymous\":\"bounded_public_summary\",\"pro\":\"same_provenance_via_mcp\",\"operator\":\"source_health_only\"}}" "upstreamUnavailable": true schema: $ref: '#/components/schemas/GetChinaDecisionSignalsResponse' "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/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/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/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/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' 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 .' schemas: ChinaDecisionSignalSnapshot: type: "object" additionalProperties: false required: - "schemaVersion" - "generatedAt" - "groups" - "access" properties: schemaVersion: type: "integer" const: 1 generatedAt: type: "string" format: "date-time" groups: type: "array" minItems: 6 maxItems: 6 prefixItems: - allOf: - "$ref": "#/components/schemas/ChinaDecisionSignalGroup" - type: "object" properties: id: const: "macro" - allOf: - "$ref": "#/components/schemas/ChinaDecisionSignalGroup" - type: "object" properties: id: const: "policy-enforcement" - allOf: - "$ref": "#/components/schemas/ChinaDecisionSignalGroup" - type: "object" properties: id: const: "cross-strait-activity" - allOf: - "$ref": "#/components/schemas/ChinaDecisionSignalGroup" - type: "object" properties: id: const: "corporate-disclosures" - allOf: - "$ref": "#/components/schemas/ChinaDecisionSignalGroup" - type: "object" properties: id: const: "corridor-conditions" - allOf: - "$ref": "#/components/schemas/ChinaDecisionSignalGroup" - type: "object" properties: id: const: "activity-nowcast" items: false access: "$ref": "#/components/schemas/ChinaDecisionSignalAccess" ChinaDecisionSignalAccess: type: "object" additionalProperties: false required: - "anonymous" - "pro" - "operator" properties: anonymous: type: "string" const: "bounded_public_summary" pro: type: "string" const: "same_provenance_via_mcp" operator: type: "string" const: "source_health_only" ChinaDecisionSignalGroup: type: "object" additionalProperties: false required: - "id" - "state" - "reason" - "items" - "metadata" properties: id: type: "string" enum: - "macro" - "policy-enforcement" - "cross-strait-activity" - "corporate-disclosures" - "corridor-conditions" - "activity-nowcast" state: type: "string" enum: - "available" - "partial" - "stale" - "unavailable" reason: oneOf: - type: "string" minLength: 1 pattern: "\\S" - type: "null" items: type: "array" maxItems: 4 items: "$ref": "#/components/schemas/ChinaDecisionSignalItem" metadata: type: "object" additionalProperties: true oneOf: - properties: state: const: "unavailable" items: type: "array" maxItems: 0 - properties: state: enum: - "available" - "partial" - "stale" items: type: "array" minItems: 1 maxItems: 4 ChinaDecisionSignalItem: type: "object" additionalProperties: false required: - "id" - "lineageId" - "label" - "summary" - "sourceName" - "sourceUrl" - "publisherType" - "observedAt" - "publishedAt" - "effectiveAt" - "retrievedAt" - "stale" - "metadata" - "provenance" properties: id: type: "string" minLength: 1 pattern: "\\S" lineageId: type: "string" minLength: 1 pattern: "\\S" label: type: "string" minLength: 1 pattern: "\\S" summary: type: "string" minLength: 1 pattern: "\\S" sourceName: type: "string" minLength: 1 pattern: "\\S" sourceUrl: oneOf: - type: "string" format: "uri" pattern: "^https://(?![^/?#]*@)[^/?#\\s]+(?:[/?#]\\S*)?$" - type: "null" publisherType: type: "string" enum: - "official_government" - "state_controlled_media" - "official_exchange" - "independent_observation" - "independent_media" - "wire_service" - "market_publisher" - "derived_output" - "unknown" observedAt: oneOf: - oneOf: - type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - type: "string" pattern: "^\\d{4}$" - type: "null" publishedAt: oneOf: - oneOf: - type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - type: "string" pattern: "^\\d{4}$" - type: "null" effectiveAt: oneOf: - oneOf: - type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - type: "string" pattern: "^\\d{4}$" - type: "null" retrievedAt: oneOf: - oneOf: - type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - type: "string" pattern: "^\\d{4}$" - type: "null" stale: type: "boolean" metadata: type: "object" additionalProperties: true provenance: "$ref": "#/components/schemas/ChinaDecisionSignalProvenance" ChinaDecisionSignalProvenance: type: "object" additionalProperties: false required: - "contractVersion" - "signalId" - "familyId" - "claims" properties: contractVersion: type: "string" const: "decision-signal-provenance/v1" signalId: type: "string" minLength: 1 pattern: "\\S" familyId: type: "string" enum: - "china_macro_official_numeric_observation" - "typed_document_event" - "operational_activity_record" - "exchange_disclosure" - "composed_corridor_condition" - "derived_comparison" claims: "$ref": "#/components/schemas/ChinaDecisionSignalProvenanceClaims" oneOf: - properties: familyId: const: "china_macro_official_numeric_observation" claims: type: "object" properties: publisher: type: "object" properties: status: enum: - "known" source_url: type: "object" properties: status: enum: - "known" original_reference: type: "object" properties: status: enum: - "known" original_language: type: "object" properties: status: enum: - "known" - "unknown" translation: type: "object" properties: status: enum: - "not_applicable" observation_time: type: "object" properties: status: enum: - "known" effective_time: type: "object" properties: status: enum: - "known" - "unknown" publication_time: type: "object" properties: status: enum: - "known" retrieval_time: type: "object" properties: status: enum: - "known" revision: type: "object" properties: status: enum: - "known" supersession: type: "object" properties: status: enum: - "known" extraction_confidence: type: "object" properties: status: enum: - "known" classification_confidence: type: "object" properties: status: enum: - "not_applicable" corroboration: type: "object" properties: status: enum: - "known" - "unknown" transport_freshness: type: "object" properties: status: enum: - "known" content_freshness: type: "object" properties: status: enum: - "known" derivation: type: "object" properties: status: enum: - "not_applicable" - properties: familyId: const: "typed_document_event" claims: type: "object" properties: publisher: type: "object" properties: status: enum: - "known" source_url: type: "object" properties: status: enum: - "known" original_reference: type: "object" properties: status: enum: - "known" original_language: type: "object" properties: status: enum: - "known" translation: type: "object" properties: status: enum: - "known" observation_time: type: "object" properties: status: enum: - "not_applicable" effective_time: type: "object" properties: status: enum: - "known" - "unknown" publication_time: type: "object" properties: status: enum: - "known" retrieval_time: type: "object" properties: status: enum: - "known" revision: type: "object" properties: status: enum: - "known" - "unknown" supersession: type: "object" properties: status: enum: - "known" extraction_confidence: type: "object" properties: status: enum: - "known" classification_confidence: type: "object" properties: status: enum: - "known" corroboration: type: "object" properties: status: enum: - "known" - "unknown" transport_freshness: type: "object" properties: status: enum: - "known" content_freshness: type: "object" properties: status: enum: - "known" derivation: type: "object" properties: status: enum: - "not_applicable" - properties: familyId: const: "operational_activity_record" claims: type: "object" properties: publisher: type: "object" properties: status: enum: - "known" source_url: type: "object" properties: status: enum: - "known" original_reference: type: "object" properties: status: enum: - "known" original_language: type: "object" properties: status: enum: - "known" - "unknown" translation: type: "object" properties: status: enum: - "known" - "unknown" observation_time: type: "object" properties: status: enum: - "known" effective_time: type: "object" properties: status: enum: - "known" - "unknown" publication_time: type: "object" properties: status: enum: - "known" - "unknown" retrieval_time: type: "object" properties: status: enum: - "known" revision: type: "object" properties: status: enum: - "known" - "unknown" supersession: type: "object" properties: status: enum: - "known" extraction_confidence: type: "object" properties: status: enum: - "known" classification_confidence: type: "object" properties: status: enum: - "known" corroboration: type: "object" properties: status: enum: - "known" - "unknown" transport_freshness: type: "object" properties: status: enum: - "known" content_freshness: type: "object" properties: status: enum: - "known" derivation: type: "object" properties: status: enum: - "not_applicable" - properties: familyId: const: "exchange_disclosure" claims: type: "object" properties: publisher: type: "object" properties: status: enum: - "known" source_url: type: "object" properties: status: enum: - "known" original_reference: type: "object" properties: status: enum: - "known" original_language: type: "object" properties: status: enum: - "known" translation: type: "object" properties: status: enum: - "known" observation_time: type: "object" properties: status: enum: - "not_applicable" effective_time: type: "object" properties: status: enum: - "known" - "unknown" publication_time: type: "object" properties: status: enum: - "known" retrieval_time: type: "object" properties: status: enum: - "known" revision: type: "object" properties: status: enum: - "known" supersession: type: "object" properties: status: enum: - "known" extraction_confidence: type: "object" properties: status: enum: - "known" classification_confidence: type: "object" properties: status: enum: - "known" corroboration: type: "object" properties: status: enum: - "known" - "unknown" transport_freshness: type: "object" properties: status: enum: - "known" content_freshness: type: "object" properties: status: enum: - "known" derivation: type: "object" properties: status: enum: - "not_applicable" - properties: familyId: const: "composed_corridor_condition" claims: type: "object" properties: publisher: type: "object" properties: status: enum: - "known" source_url: type: "object" properties: status: enum: - "not_applicable" original_reference: type: "object" properties: status: enum: - "not_applicable" original_language: type: "object" properties: status: enum: - "not_applicable" translation: type: "object" properties: status: enum: - "not_applicable" observation_time: type: "object" properties: status: enum: - "known" effective_time: type: "object" properties: status: enum: - "known" publication_time: type: "object" properties: status: enum: - "not_applicable" retrieval_time: type: "object" properties: status: enum: - "known" revision: type: "object" properties: status: enum: - "known" supersession: type: "object" properties: status: enum: - "known" extraction_confidence: type: "object" properties: status: enum: - "not_applicable" classification_confidence: type: "object" properties: status: enum: - "known" corroboration: type: "object" properties: status: enum: - "known" transport_freshness: type: "object" properties: status: enum: - "known" content_freshness: type: "object" properties: status: enum: - "known" derivation: type: "object" properties: status: enum: - "known" - properties: familyId: const: "derived_comparison" claims: type: "object" properties: publisher: type: "object" properties: status: enum: - "known" source_url: type: "object" properties: status: enum: - "not_applicable" original_reference: type: "object" properties: status: enum: - "not_applicable" original_language: type: "object" properties: status: enum: - "not_applicable" translation: type: "object" properties: status: enum: - "not_applicable" observation_time: type: "object" properties: status: enum: - "known" effective_time: type: "object" properties: status: enum: - "known" publication_time: type: "object" properties: status: enum: - "not_applicable" retrieval_time: type: "object" properties: status: enum: - "known" revision: type: "object" properties: status: enum: - "known" supersession: type: "object" properties: status: enum: - "known" extraction_confidence: type: "object" properties: status: enum: - "not_applicable" classification_confidence: type: "object" properties: status: enum: - "known" corroboration: type: "object" properties: status: enum: - "known" transport_freshness: type: "object" properties: status: enum: - "known" content_freshness: type: "object" properties: status: enum: - "known" derivation: type: "object" properties: status: enum: - "known" ChinaDecisionSignalProvenanceClaims: type: "object" additionalProperties: false required: - "publisher" - "source_url" - "original_reference" - "original_language" - "translation" - "observation_time" - "effective_time" - "publication_time" - "retrieval_time" - "revision" - "supersession" - "extraction_confidence" - "classification_confidence" - "corroboration" - "transport_freshness" - "content_freshness" - "derivation" properties: publisher: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "id" - "name" - "type" - "registryReference" properties: id: type: "string" minLength: 1 pattern: "\\S" name: type: "string" minLength: 1 pattern: "\\S" type: type: "string" enum: - "official_government" - "state_controlled_media" - "official_exchange" - "independent_observation" - "independent_media" - "wire_service" - "market_publisher" - "derived_output" - "unknown" registryReference: oneOf: - type: "object" additionalProperties: false required: - "sourceName" - "sourceType" - "propagandaRisk" properties: sourceName: type: "string" minLength: 1 pattern: "\\S" sourceType: type: "string" minLength: 1 pattern: "\\S" propagandaRisk: type: "string" minLength: 1 pattern: "\\S" - type: "null" oneOf: - properties: type: const: "derived_output" registryReference: type: "null" - properties: type: enum: - "official_government" - "state_controlled_media" - "official_exchange" - "independent_observation" - "independent_media" - "wire_service" - "market_publisher" - "unknown" registryReference: type: "object" additionalProperties: false required: - "sourceName" - "sourceType" - "propagandaRisk" properties: sourceName: type: "string" minLength: 1 pattern: "\\S" sourceType: type: "string" minLength: 1 pattern: "\\S" propagandaRisk: type: "string" minLength: 1 pattern: "\\S" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" source_url: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "string" format: "uri" pattern: "^https://(?![^/?#]*@)[^/?#\\s]+(?:[/?#]\\S*)?$" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" original_reference: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "kind" - "id" properties: kind: type: "string" enum: - "document" - "text" - "observation" - "event" - "dataset" id: type: "string" minLength: 1 pattern: "\\S" contentHash: type: "string" pattern: "^sha256:[a-f0-9]{64}$" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" original_language: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "string" minLength: 1 pattern: "\\S" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" translation: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "state" properties: state: type: "string" enum: - "unavailable" - "not_translated" - "machine_assisted" - "human_reviewed" targetLanguage: type: "string" minLength: 1 pattern: "\\S" oneOf: - properties: state: enum: - "machine_assisted" - "human_reviewed" required: - "targetLanguage" - properties: state: enum: - "unavailable" - "not_translated" not: required: - "targetLanguage" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" observation_time: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "role" - "value" - "precision" properties: role: type: "string" const: "observation" value: oneOf: - type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - type: "string" pattern: "^\\d{4}$" precision: type: "string" enum: - "instant" - "day" - "month" - "year" oneOf: - properties: precision: const: "instant" value: type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - properties: precision: const: "day" value: type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - properties: precision: const: "month" value: type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - properties: precision: const: "year" value: type: "string" pattern: "^\\d{4}$" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" effective_time: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "role" - "value" - "precision" properties: role: type: "string" const: "effective" value: oneOf: - type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - type: "string" pattern: "^\\d{4}$" precision: type: "string" enum: - "instant" - "day" - "month" - "year" oneOf: - properties: precision: const: "instant" value: type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - properties: precision: const: "day" value: type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - properties: precision: const: "month" value: type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - properties: precision: const: "year" value: type: "string" pattern: "^\\d{4}$" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" publication_time: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "role" - "value" - "precision" properties: role: type: "string" const: "publication" value: oneOf: - type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - type: "string" pattern: "^\\d{4}$" precision: type: "string" enum: - "instant" - "day" - "month" - "year" oneOf: - properties: precision: const: "instant" value: type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - properties: precision: const: "day" value: type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - properties: precision: const: "month" value: type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - properties: precision: const: "year" value: type: "string" pattern: "^\\d{4}$" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" retrieval_time: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "role" - "value" - "precision" properties: role: type: "string" const: "retrieval" value: oneOf: - type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - type: "string" pattern: "^\\d{4}$" precision: type: "string" enum: - "instant" - "day" - "month" - "year" oneOf: - properties: precision: const: "instant" value: type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - properties: precision: const: "day" value: type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - properties: precision: const: "month" value: type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - properties: precision: const: "year" value: type: "string" pattern: "^\\d{4}$" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" revision: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "vintageId" - "sequence" - "state" properties: vintageId: type: "string" minLength: 1 pattern: "\\S" sequence: type: "integer" minimum: 1 state: type: "string" enum: - "preliminary" - "original" - "revised" - "corrected" oneOf: - properties: state: enum: - "preliminary" - "original" sequence: const: 1 - properties: state: enum: - "revised" - "corrected" sequence: type: "integer" minimum: 2 - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" supersession: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "state" properties: state: type: "string" enum: - "current" - "corrected" - "cancelled" - "superseded" relatedSignalId: type: "string" minLength: 1 pattern: "\\S" reason: type: "string" minLength: 1 pattern: "\\S" oneOf: - properties: state: const: "current" not: anyOf: - required: - "relatedSignalId" - required: - "reason" - properties: state: enum: - "corrected" - "superseded" required: - "relatedSignalId" - properties: state: const: "cancelled" required: - "reason" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" extraction_confidence: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "score" - "method" properties: score: type: "number" minimum: 0 maximum: 1 method: type: "string" minLength: 1 pattern: "\\S" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" classification_confidence: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "score" - "method" properties: score: type: "number" minimum: 0 maximum: 1 method: type: "string" minLength: 1 pattern: "\\S" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" corroboration: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "state" - "sourceSignalIds" properties: state: type: "string" enum: - "single_source" - "multi_source" - "independently_corroborated" - "contradicted" sourceSignalIds: type: "array" uniqueItems: true items: type: "string" minLength: 1 pattern: "\\S" oneOf: - properties: state: const: "single_source" sourceSignalIds: type: "array" uniqueItems: true items: type: "string" minLength: 1 pattern: "\\S" minItems: 1 maxItems: 1 - properties: state: enum: - "multi_source" - "independently_corroborated" - "contradicted" sourceSignalIds: type: "array" minItems: 2 uniqueItems: true items: type: "string" minLength: 1 pattern: "\\S" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" transport_freshness: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "state" - "assessedAt" properties: state: type: "string" enum: - "fresh" - "stale" - "missing" - "error" assessedAt: type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" lastSuccessAt: type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" content_freshness: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "state" - "assessedAt" properties: state: type: "string" enum: - "current" - "stale" - "unavailable" - "partial" - "timestamp_unknown" assessedAt: type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" contentAsOf: oneOf: - type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" - type: "string" format: "date" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$" - type: "string" pattern: "^\\d{4}-(?:0[1-9]|1[0-2])$" - type: "string" pattern: "^\\d{4}$" oneOf: - properties: state: enum: - "current" - "stale" required: - "contentAsOf" - properties: state: const: "timestamp_unknown" not: required: - "contentAsOf" - properties: state: enum: - "unavailable" - "partial" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" derivation: oneOf: - type: "object" additionalProperties: false required: - "status" - "value" properties: status: type: "string" const: "known" value: type: "object" additionalProperties: false required: - "methodId" - "methodVersion" - "computedAt" - "inputSignalIds" properties: methodId: type: "string" minLength: 1 pattern: "\\S" methodVersion: type: "string" minLength: 1 pattern: "\\S" computedAt: type: "string" format: "date-time" pattern: "^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$" inputSignalIds: type: "array" minItems: 1 uniqueItems: true items: type: "string" minLength: 1 pattern: "\\S" - "$ref": "#/components/schemas/ChinaDecisionSignalUnavailableClaim" ChinaDecisionSignalUnavailableClaim: type: "object" additionalProperties: false required: - "status" - "reason" properties: status: type: "string" enum: - "unknown" - "not_applicable" reason: type: "string" minLength: 1 pattern: "\\S" 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. GetRiskScoresRequest: type: object properties: region: type: string description: Optional region filter. Empty returns all tracked regions. description: GetRiskScoresRequest specifies parameters for retrieving risk scores. GetRiskScoresResponse: type: object properties: ciiScores: type: array items: $ref: '#/components/schemas/CiiScore' strategicRisks: type: array items: $ref: '#/components/schemas/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. 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/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. 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. 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. 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. GetPizzintStatusResponse: type: object properties: pizzint: $ref: '#/components/schemas/PizzintStatus' tensionPairs: type: array items: $ref: '#/components/schemas/GdeltTensionPair' description: GetPizzintStatusResponse contains Pentagon Pizza Index and GDELT tension data. 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/PizzintLocation' description: PizzintStatus represents the Pentagon Pizza Index status (proxy for late-night DC activity). 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. 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. 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. ClassifyEventResponse: type: object properties: classification: $ref: '#/components/schemas/EventClassification' description: ClassifyEventResponse contains the AI-generated event classification. 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. 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. 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/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. 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. 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/BriefSource' description: GetCountryIntelBriefResponse contains an AI-generated intelligence brief for a country. 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. 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. SearchGdeltDocumentsResponse: type: object properties: articles: type: array items: $ref: '#/components/schemas/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. 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. DeductSituationRequest: type: object properties: query: type: string geoContext: type: string framework: type: string description: Optional analytical framework instructions. DeductSituationResponse: type: object properties: analysis: type: string model: type: string provider: type: string ListSatellitesRequest: type: object properties: country: type: string description: Filter by country code. Empty returns all. description: ListSatellitesRequest specifies filters for orbital data. ListSatellitesResponse: type: object properties: satellites: type: array items: $ref: '#/components/schemas/Satellite' description: ListSatellitesResponse contains the current orbital snapshot. 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. ListGpsInterferenceRequest: type: object properties: region: type: string description: Optional region filter. description: ListGpsInterferenceRequest specifies filters for GPS interference data. ListGpsInterferenceResponse: type: object properties: hexes: type: array items: $ref: '#/components/schemas/GpsJamHex' stats: $ref: '#/components/schemas/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. 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. 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. ListOrefAlertsRequest: type: object properties: mode: type: string enum: - MODE_UNSPECIFIED - MODE_HISTORY description: Request to fetch Israeli Red Alerts (OREF). ListOrefAlertsResponse: type: object properties: configured: type: boolean description: Whether the OREF bridge is configured. alerts: type: array items: $ref: '#/components/schemas/OrefAlert' history: type: array items: $ref: '#/components/schemas/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. 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. OrefWave: type: object properties: alerts: type: array items: $ref: '#/components/schemas/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. 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. ListTelegramFeedResponse: type: object properties: enabled: type: boolean description: Whether the bridge is currently active. messages: type: array items: $ref: '#/components/schemas/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. 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. 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. GetCompanyEnrichmentResponse: type: object properties: company: $ref: '#/components/schemas/EnrichedCompany' github: $ref: '#/components/schemas/EnrichedGithub' techStack: type: array items: $ref: '#/components/schemas/TechStackItem' secFilings: $ref: '#/components/schemas/SecFilings' hackerNewsMentions: type: array items: $ref: '#/components/schemas/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. EnrichedCompany: type: object properties: name: type: string domain: type: string description: type: string location: type: string website: type: string founded: type: integer format: int32 EnrichedGithub: type: object properties: publicRepos: type: integer format: int32 followers: type: integer format: int32 avatarUrl: type: string TechStackItem: type: object properties: name: type: string category: type: string confidence: type: number format: float SecFilings: type: object properties: totalFilings: type: integer format: int32 recentFilings: type: array items: $ref: '#/components/schemas/SecFiling' SecFiling: type: object properties: form: type: string fileDate: type: string description: type: string 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' 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. ListCompanySignalsResponse: type: object properties: company: type: string domain: type: string signals: type: array items: $ref: '#/components/schemas/CompanySignal' summary: $ref: '#/components/schemas/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. 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/SignalEngagement' 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 SignalSummary: type: object properties: totalSignals: type: integer format: int32 byType: type: object additionalProperties: type: integer format: int32 strongestSignal: $ref: '#/components/schemas/CompanySignal' signalDiversity: type: integer format: int32 ByTypeEntry: type: object properties: key: type: string value: type: integer format: int32 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 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 ListSecurityAdvisoriesRequest: type: object ListSecurityAdvisoriesResponse: type: object properties: advisories: type: array items: $ref: '#/components/schemas/SecurityAdvisoryItem' byCountry: type: object additionalProperties: type: string ByCountryEntry: type: object properties: key: type: string value: type: string 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 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. GetGdeltTopicTimelineResponse: type: object properties: topic: type: string description: Topic ID. tone: type: array items: $ref: '#/components/schemas/GdeltTimelinePoint' vol: type: array items: $ref: '#/components/schemas/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. 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. ListCrossSourceSignalsRequest: type: object description: ListCrossSourceSignalsRequest has no required parameters (returns all signals). ListCrossSourceSignalsResponse: type: object properties: signals: type: array items: $ref: '#/components/schemas/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. 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. ListMarketImplicationsRequest: type: object properties: frameworkId: type: string description: Framework identifier whose market implication cards should be listed. ListMarketImplicationsResponse: type: object properties: cards: type: array items: $ref: '#/components/schemas/MarketImplicationCard' degraded: type: boolean emptyReason: type: string generatedAt: type: string 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/TransmissionNode' TransmissionNode: type: object properties: node: type: string impactType: type: string logic: type: string GetSocialVelocityRequest: type: object GetSocialVelocityResponse: type: object properties: posts: type: array items: $ref: '#/components/schemas/SocialVelocityPost' fetchedAt: type: integer format: int64 description: 'Warning: Values > 2^53 may lose precision in JavaScript' 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. GetCountryEnergyProfileRequest: type: object properties: countryCode: type: string description: ISO 3166-1 alpha-2 country code for the energy profile. 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 jodiOilObservedMeasurements: type: array items: type: string description: |- Per-field presence for partial JODI payloads. Existing numeric fields keep their proto3 zero defaults for compatibility; a path appears here only when that source measurement was actually observed, including valid zeroes. Values use the stable source paths from jodi-measurement-fields.json. jodiGasObservedMeasurements: type: array items: type: string description: Same presence contract for JODI gas source paths. 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".' 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/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/GasImpact' ProductImpact: type: object properties: product: type: string outputLossKbd: type: number format: double demandKbd: type: number format: double deficitPct: type: number format: double 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/GasStorageBuffer' dataSource: type: string 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 GetCountryPortActivityRequest: type: object properties: countryCode: type: string description: ISO 3166-1 alpha-2 country code for port activity. CountryPortActivityResponse: type: object properties: ports: type: array items: $ref: '#/components/schemas/PortActivityEntry' fetchedAt: type: string available: type: boolean 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 GetChinaDecisionSignalsRequest: type: object GetChinaDecisionSignalsResponse: type: object properties: payloadJson: contentMediaType: "application/json" contentSchema: $ref: "#/components/schemas/ChinaDecisionSignalSnapshot" type: string description: |- Canonical bounded JSON shared byte-for-byte by public API, country summary, and MCP. Operator-only health stays on /api/health. generatedAt: type: string upstreamUnavailable: type: boolean description: |- True only when all six launched groups are unavailable. Partial source outages remain visible per group and do not suppress unrelated domains. 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. GetRegionalSnapshotResponse: type: object properties: snapshot: $ref: '#/components/schemas/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. 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/SnapshotMeta' regime: $ref: '#/components/schemas/RegimeState' balance: $ref: '#/components/schemas/BalanceVector' actors: type: array items: $ref: '#/components/schemas/ActorState' leverageEdges: type: array items: $ref: '#/components/schemas/LeverageEdge' scenarioSets: type: array items: $ref: '#/components/schemas/ScenarioSet' transmissionPaths: type: array items: $ref: '#/components/schemas/TransmissionPath' triggers: $ref: '#/components/schemas/TriggerLadder' mobility: $ref: '#/components/schemas/MobilityState' evidence: type: array items: $ref: '#/components/schemas/EvidenceItem' narrative: $ref: '#/components/schemas/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. 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). 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. 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/BalanceDriver' buffers: type: array items: $ref: '#/components/schemas/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. 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. 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. 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. ScenarioSet: type: object properties: horizon: type: string description: 'horizon: 24h | 7d | 30d' lanes: type: array items: $ref: '#/components/schemas/ScenarioLane' description: |- ScenarioSet bundles scenario lanes for one time horizon. Lane probabilities sum to 1.0 within a set. 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/TransmissionPath' description: ScenarioLane is one outcome branch within a horizon set. 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. TriggerLadder: type: object properties: active: type: array items: $ref: '#/components/schemas/Trigger' watching: type: array items: $ref: '#/components/schemas/Trigger' dormant: type: array items: $ref: '#/components/schemas/Trigger' description: TriggerLadder buckets triggers by activation state. Trigger: type: object properties: id: type: string description: type: string threshold: $ref: '#/components/schemas/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. 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. MobilityState: type: object properties: airspace: type: array items: $ref: '#/components/schemas/AirspaceStatus' flightCorridors: type: array items: $ref: '#/components/schemas/FlightCorridorStress' airports: type: array items: $ref: '#/components/schemas/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. 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. FlightCorridorStress: type: object properties: corridor: type: string stressLevel: type: number format: double reroutedFlights24h: type: integer format: int32 description: FlightCorridorStress captures per-corridor reroute intensity. 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. 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. RegionalNarrative: type: object properties: situation: $ref: '#/components/schemas/NarrativeSection' balanceAssessment: $ref: '#/components/schemas/NarrativeSection' outlook24h: $ref: '#/components/schemas/NarrativeSection' outlook7d: $ref: '#/components/schemas/NarrativeSection' outlook30d: $ref: '#/components/schemas/NarrativeSection' watchItems: type: array items: $ref: '#/components/schemas/NarrativeSection' description: |- RegionalNarrative is the LLM-synthesized narrative layer. Every section links back to evidence via evidence_ids. 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. 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. GetRegimeHistoryResponse: type: object properties: transitions: type: array items: $ref: '#/components/schemas/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). 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. 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 GetRegionalBriefResponse: type: object properties: brief: $ref: '#/components/schemas/RegionalBrief' 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.