docs/api/ResilienceService.openapi.yaml
Rama main · réplica de lectura del repositorio original.
openapi: 3.1.0
info:
title: ResilienceService API
version: 1.0.0
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
servers:
- url: https://api.worldmonitor.app
paths:
/api/resilience/v1/get-resilience-score:
get:
tags:
- ResilienceService
summary: GetResilienceScore
description: GetResilienceScore returns a country's resilience score with domain and pillar scores, trend and confidence. PRO-gated. Requires an active Pro subscription.
operationId: GetResilienceScore
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: countryCode
in: query
description: ISO 3166-1 alpha-2 country code to score.
required: true
example: "US"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"baselineScore": 42.5
"change30d": 1.5
"countryCode": "US"
"dataVersion": "example"
"domains":
- "dimensions":
- "coverage": 1.5
"freshness":
"lastObservedAtMs": "1717200000000"
"staleness": "example"
"id": "example-id"
"imputationClass": "example"
"imputedWeight": 1.5
"id": "example-id"
"score": 42.5
"weight": 1.5
schema:
$ref: '#/components/schemas/GetResilienceScoreResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: Pro subscription required.
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/resilience/v1/get-resilience-indicators:
get:
tags:
- ResilienceService
summary: GetResilienceIndicators
description: GetResilienceIndicators explains one country's score at indicator level. PRO-gated. Requires entitlement tier >= 1.
operationId: GetResilienceIndicators
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: countryCode
in: query
description: Required ISO 3166-1 alpha-2 country code.
required: true
example: "US"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"constructVersions":
"education": "example"
"energy": "example"
"financialSystemExposure": "example"
"countryCode": "US"
"dataVersion": "example"
"dimensions":
- "active": true
"coverage": 1.5
"effectiveContributionTotal": 1
"id": "example-id"
"literalContributionTotal": 1
"formula": "example"
schema:
$ref: '#/components/schemas/GetResilienceIndicatorsResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: PRO entitlement access denied.
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/resilience/v1/get-food-stocks:
get:
tags:
- ResilienceService
summary: GetFoodStocks
description: GetFoodStocks returns USDA PSD grain and oilseed stocks-to-use by country or WORLD; FAOSTAT fills supply gaps without stock ratios (see hasStocksToUse). PRO-gated. Requires entitlement tier >= 1.
operationId: GetFoodStocks
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: countryCode
in: query
description: ISO 3166-1 alpha-2, or WORLD. Empty returns the unfiltered snapshot.
required: false
example: "US"
schema:
type: string
- name: commodity
in: query
description: Commodity slug (wheat, corn, rice, soybeans, barley, palmOil). Empty = all.
required: false
example: "corn"
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:
"calorieWeightedStocksToUse": 1.5
"fetchedAt": "2026-01-15T12:00:00Z"
"records":
- "commodity": "corn"
"consumptionTmt": 1.5
"countryCode": "US"
"endingStocksTmt": 1.5
"exportsTmt": 1.5
"unavailable": false
schema:
$ref: '#/components/schemas/GetFoodStocksResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: PRO entitlement access denied.
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/resilience/v1/get-demographics-capability:
get:
tags:
- ResilienceService
summary: GetDemographicsCapability
description: GetDemographicsCapability returns age, education and industrial-workforce observations for one country. PRO-gated. Requires entitlement tier >= 1.
operationId: GetDemographicsCapability
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: countryCode
in: query
description: Required ISO 3166-1 alpha-2 country code.
required: true
example: "US"
schema:
type: string
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"ageStructure":
"available": true
"medianAgeYears":
"available": true
"source": "Example dataset"
"unit": "years"
"value": 1.5
"year": 2024
"oldAgeDependencyRatioPercent":
"available": true
"source": "Example dataset"
"unit": "percent"
"value": 1.5
"year": 2024
"totalDependencyRatioPercent":
"available": true
"source": "Example dataset"
"unit": "percent"
"value": 1.5
"year": 2024
"workingAgePopulationPeople":
"available": true
"source": "Example dataset"
"unit": "people"
"value": 1.5
"year": 2024
"available": true
"countryCode": "US"
"education":
"available": true
"researchersPerMillion":
"available": true
"source": "Example dataset"
"unit": "people per million"
"value": 1.5
"year": 2024
"stemGraduatesSharePercent":
"available": true
"source": "Example dataset"
"unit": "percent"
"value": 1.5
"year": 2024
"tertiaryEnrollmentGrossPercent":
"available": true
"source": "Example dataset"
"unit": "percent"
"value": 1.5
"year": 2024
"fetchedAt": "2026-01-15T12:00:00Z"
schema:
$ref: '#/components/schemas/GetDemographicsCapabilityResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: PRO entitlement access denied.
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/resilience/v1/get-resilience-ranking:
get:
tags:
- ResilienceService
summary: GetResilienceRanking
description: Retrieve country structural resilience rankings with coverage, confidence and snapshot metadata for comparison. PRO-gated. Requires an active Pro subscription.
operationId: GetResilienceRanking
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"coverage": 1.5
"fetchedAt": "2026-01-15T12:00:00Z"
"greyedOut":
- "countryCode": "US"
"headlineEligible": true
"level": "example"
"lowConfidence": true
"overallCoverage": 1.5
"items":
- "countryCode": "US"
"headlineEligible": true
"level": "example"
"lowConfidence": true
"overallCoverage": 1.5
"partial": true
schema:
$ref: '#/components/schemas/GetResilienceRankingResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"401":
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
"403":
description: Pro subscription required.
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/resilience/v1/get-runtime-manifest:
get:
tags:
- ResilienceService
summary: GetResilienceRuntimeManifest
description: 'GetResilienceRuntimeManifest returns the public resilience-scoring runtime manifest: manifest version, generation timestamp, active formula tag, cache state, construct versions, and interval availability.'
operationId: GetResilienceRuntimeManifest
security: []
parameters:
- name: jmespath
in: query
description: |-
Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.
required: false
example: "keys(@)"
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
example:
"cache":
"historyPrefix": "example"
"intervalMethodology": "example"
"intervalPrefix": "example"
"rankingKey": "example"
"scorePrefix": "example"
"constructVersions":
"education": "example"
"energy": "example"
"financialSystemExposure": "example"
"dataVersion": "example"
"deployedCommitSha": "example"
"flags":
- "enabled": true
"name": "WorldMonitor Analyst"
schema:
$ref: '#/components/schemas/GetResilienceRuntimeManifestResponse'
"400":
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/JmespathProjectionError'
"429":
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the active rate-limit window.
schema:
type: string
X-RateLimit-Remaining:
description: Requests remaining in the active rate-limit window.
schema:
type: string
X-RateLimit-Reset:
description: Unix epoch milliseconds when the active rate-limit window resets.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/RateLimitError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
components:
securitySchemes:
WorldMonitorKey:
type: apiKey
in: header
name: X-WorldMonitor-Key
description: User-issued WorldMonitor API key.
ApiKeyHeader:
type: apiKey
in: header
name: X-Api-Key
description: Alias header for the WorldMonitor API key (X-WorldMonitor-Key).
BearerAuth:
type: http
scheme: bearer
description: 'Bearer token: a Clerk-issued JWT for browser session flows, passed as Authorization: Bearer <token>.'
schemas:
JmespathProjectionError:
description: Returned when a REST jmespath projection is invalid or exceeds the expression/output byte limits.
properties:
_jmespath_error:
description: Projection error discriminator and details.
type: string
original_keys:
description: Top-level keys or shape of the unprojected response.
items:
type: string
type: array
required:
- _jmespath_error
- original_keys
type: object
UnauthorizedError:
type: object
properties:
error:
type: string
description: Human-readable error message.
required:
- error
description: Returned when the API key is missing, malformed, or lacks current API access.
Error:
type: object
properties:
message:
type: string
description: Error message (e.g., 'user not found', 'database connection failed')
description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.
BillingVerificationError:
type: object
description: "Returned with HTTP 503 when paid access cannot be confirmed right now: the billing provider is re-verifying a recently expired subscription, or the entitlement backend is unreachable. Retryable — honor Retry-After."
properties:
error:
type: string
description: Human-readable billing-verification failure reason.
code:
type: string
enum:
- renewal_verification_pending
- renewal_verification_failed
- entitlement_verification_unavailable
description: Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header.
requiredTier:
type: integer
format: int32
description: Minimum entitlement tier required for this endpoint, when the denial came from a tier gate.
required:
- error
- code
InvalidRequestBodyError:
type: object
description: Returned when a JSON POST request body is empty or malformed.
properties:
message:
type: string
description: Invalid request body
required:
- message
GatewayError:
type: object
description: Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks.
properties:
error:
oneOf:
- type: string
- type: object
additionalProperties: true
description: Gateway error reason or structured gateway failure details.
required:
- error
RateLimitError:
type: object
description: Returned when a gateway or handler rate limit rejects the request.
properties:
error:
type: string
description: Human-readable rate-limit failure reason.
required:
- error
ForbiddenError:
type: object
properties:
error:
type: string
description: Human-readable entitlement failure reason.
code:
type: string
enum:
- subscription_lapsed
description: Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header).
requiredTier:
type: integer
format: int32
description: Minimum entitlement tier required for this endpoint.
currentTier:
type: integer
format: int32
description: Caller entitlement tier when known.
planKey:
type: string
description: Caller plan key when known.
required:
- error
description: Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier.
FieldViolation:
type: object
properties:
field:
type: string
description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')
description:
type: string
description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')
required:
- field
- description
description: FieldViolation describes a single validation error for a specific field.
ValidationError:
type: object
properties:
violations:
type: array
items:
$ref: '#/components/schemas/FieldViolation'
description: List of validation violations
required:
- violations
description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.
GetResilienceScoreRequest:
type: object
properties:
countryCode:
type: string
description: ISO 3166-1 alpha-2 country code to score.
required:
- countryCode
GetResilienceScoreResponse:
type: object
properties:
countryCode:
type: string
overallScore:
type: number
format: double
level:
type: string
domains:
type: array
items:
$ref: '#/components/schemas/ResilienceDomain'
trend:
type: string
change30d:
type: number
format: double
lowConfidence:
type: boolean
imputationShare:
type: number
format: double
baselineScore:
type: number
format: double
stressScore:
type: number
format: double
stressFactor:
type: number
format: double
dataVersion:
type: string
scoreInterval:
$ref: '#/components/schemas/ScoreInterval'
pillars:
type: array
items:
$ref: '#/components/schemas/ResiliencePillar'
schemaVersion:
type: string
description: |-
Phase 2 T2.1/T2.3: "2.0" is the current default (adds pillars; keeps
overall_score / baseline_score / etc. populated for backward compat).
"1.0" is the legacy opt-out shape (pillars empty) retained for one
release cycle. Controlled at response build time by the
RESILIENCE_SCHEMA_V2_ENABLED env flag (defaults to "true" → v2).
headlineEligible:
type: boolean
description: |-
Current headline-ranking eligibility. True only when the country passes
the headline gate: coverage >= 0.65 AND (population >= 200k OR
coverage >= 0.85) AND !lowConfidence. GetResilienceRanking includes
only eligible countries in items[]; scored but ineligible countries
remain in greyedOut[]. Raw score endpoints still return the country
score when available. Widget and country detail copy should show
"Outside headline ranking" when false unless low-confidence is the more
specific reason.
ResilienceDomain:
type: object
properties:
id:
type: string
score:
type: number
format: double
weight:
type: number
format: double
dimensions:
type: array
items:
$ref: '#/components/schemas/ResilienceDimension'
ResilienceDimension:
type: object
properties:
id:
type: string
score:
type: number
format: double
coverage:
type: number
format: double
observedWeight:
type: number
format: double
imputedWeight:
type: number
format: double
imputationClass:
type: string
description: |-
Four-class imputation taxonomy (Phase 1 T1.7). One of:
"stable-absence", "unmonitored", "source-failure", "not-applicable".
Empty string when the dimension has any observed data AND is not
structurally not-applicable. The "not-applicable" value (plan
2026-04-26-001 §U3) is emitted when the dim's construct does not
apply to this country (e.g. sovereignFiscalBuffer for non-SWF
economies); it is paired with coverage:0 and observed_weight:0 so
the dim contributes nothing to the domain mean and is filtered
out of user-facing confidence/coverage signals on both server and
client. See docs/methodology/country-resilience-index.mdx.
freshness:
$ref: '#/components/schemas/DimensionFreshness'
DimensionFreshness:
type: object
properties:
lastObservedAtMs:
type: string
format: int64
description: |-
Unix milliseconds when the oldest constituent signal in this
dimension was last observed (min fetchedAt across INDICATOR_REGISTRY
entries for this dimension). 0 when no signal has ever been
observed.
staleness:
type: string
description: |-
Worst staleness level across the dimension's constituent signals,
classified by classifyStaleness against each signal's cadence.
One of: "fresh", "aging", "stale". Empty string when no signals.
ScoreInterval:
type: object
properties:
p05:
type: number
format: double
p95:
type: number
format: double
ResiliencePillar:
type: object
properties:
id:
type: string
description: '"structural-readiness" | "live-shock-exposure" | "recovery-capacity".'
score:
type: number
format: double
description: |-
Pillar score in [0, 100], mean of member domains weighted by
domain.weight * average_dimension_coverage.
weight:
type: number
format: double
description: 'Pillar weight in the pillar-combined score. Per the plan: 0.40 / 0.35 / 0.25.'
coverage:
type: number
format: double
description: Coverage in [0, 1], mean of member-domain average dimension coverage.
domains:
type: array
items:
$ref: '#/components/schemas/ResilienceDomain'
description: |-
Phase 2 T2.1/T2.3 of the country-resilience reference-grade upgrade plan.
Three-pillar response shape that regroups the 6 ResilienceDomains
(economic, infrastructure, energy, social-governance, health-food,
recovery) into long-run capacity (structural-readiness), current shock
pressure (live-shock-exposure), and recovery capability (recovery-capacity).
Pillar scores are real domain-weighted, coverage-scaled aggregates computed
from the constituent domains; pillar coverage remains the mean of
member-domain average dimension coverage. See _pillar-membership.ts for the mapping.
When RESILIENCE_SCHEMA_V2_ENABLED and RESILIENCE_PILLAR_COMBINE_ENABLED
are both true, the top-level overall_score on GetResilienceScoreResponse
uses the pillar-combined score with the min-pillar penalty term in
_shared.ts#penalizedPillarScore. The legacy six-domain weighted aggregate
remains the flag-off rollback path.
GetResilienceIndicatorsRequest:
type: object
properties:
countryCode:
type: string
description: Required ISO 3166-1 alpha-2 country code.
required:
- countryCode
GetResilienceIndicatorsResponse:
type: object
properties:
countryCode:
type: string
description: Normalized ISO 3166-1 alpha-2 country code used by the scorer.
methodology:
type: string
description: Stable decomposition method used to reconcile rows to dimension scores.
formula:
type: string
description: Active score formula tag, for example d6 or pc.
dataVersion:
type: string
description: Source snapshot version used for the score, normally an ISO date.
schemaVersion:
type: string
description: Public resilience score schema version.
constructVersions:
$ref: '#/components/schemas/ResilienceRuntimeConstructVersions'
dimensions:
type: array
items:
$ref: '#/components/schemas/ResilienceIndicatorDimension'
indicators:
type: array
items:
$ref: '#/components/schemas/ResilienceIndicator'
ResilienceRuntimeConstructVersions:
type: object
properties:
energy:
type: string
description: 'Safe derived energy construct version. Valid values: "legacy" or "v2".'
education:
type: string
description: 'Safe derived education construct version. Valid values: "active" or "rollback".'
financialSystemExposure:
type: string
description: 'Safe derived financial-system construct version. Valid values: "active" or "rollback".'
ResilienceIndicatorDimension:
type: object
properties:
id:
type: string
description: Stable dimension identifier from the resilience construct.
score:
type: number
format: double
description: Final dimension score on the 0-100 scale.
coverage:
type: number
format: double
description: Fraction of active dimension weight backed by observations, from 0 to 1.
prePolicyScore:
type: number
format: double
description: Dimension score before a policy cap or other post-blend adjustment.
policyCapName:
type: string
description: Name of the applied post-blend policy cap, or empty when none applies.
policyCapFactor:
type: number
format: double
description: Multiplicative factor applied by the post-blend policy cap.
literalContributionTotal:
type: number
format: double
description: Sum of literal indicator contributions before dimension-level policy.
effectiveContributionTotal:
type: number
format: double
description: Sum of exposed effective contributions. This reconciles to score.
active:
type: boolean
description: False for retired or runtime-disabled placeholder dimensions.
reconciliationAvailable:
type: boolean
description: True when effective_contribution_total is required to equal score.
reason:
type: string
description: Explanation when this dimension is inactive or cannot reconcile contributions.
description: Reconciled metadata for one resilience dimension.
ResilienceIndicator:
type: object
properties:
id:
type: string
description: Stable indicator identifier from the 72-row registry.
dimension:
type: string
description: Stable identifier of the dimension that owns this indicator.
tier:
type: string
description: 'Scoring tier: core, enrichment, or experimental.'
active:
type: boolean
description: Active means the current construct version can use this indicator.
includedInDimensionScore:
type: boolean
description: True when this country observation participated in the dimension score.
state:
type: string
description: |-
observed, imputed, missing, fallback, source-failure, inactive, retired,
or not-applicable.
reason:
type: string
description: Explains exclusion, inactive selection, retirement, or fallback state.
normalizedScoreAvailable:
type: boolean
description: True when normalized_score contains the score used by the scorer.
normalizedScore:
type: number
format: double
description: Indicator score normalized to the 0-100 resilience scale.
nominalWeight:
type: number
format: double
description: Configured indicator weight before runtime selection or reweighting.
runtimeWeightAvailable:
type: boolean
description: True when runtime_weight applies to this execution path.
runtimeWeight:
type: number
format: double
description: Weight selected by the executed scorer branch before normalization.
scoringWeightShareAvailable:
type: boolean
description: True when scoring_weight_share applies to this execution path.
scoringWeightShare:
type: number
format: double
description: Indicator share of the active blend after runtime reweighting.
literalContribution:
type: number
format: double
description: Indicator contribution before dimension-level caps or adjustments.
effectiveContribution:
type: number
format: double
description: Reconciled contribution after dimension-level caps or adjustments.
imputationClass:
type: string
description: Empty for observed or unavailable rows; otherwise the scorer taxonomy.
sourceYearAvailable:
type: boolean
description: True when source_year contains the provider observation year.
sourceYear:
type: integer
minimum: 0
format: int32
description: Provider observation year, not the WorldMonitor retrieval year.
observationAgeAvailable:
type: boolean
description: Age of the source observation, not the time since WorldMonitor fetched it.
observationAgeValue:
type: integer
minimum: 0
format: int32
description: Integer observation age expressed in observation_age_unit.
observationAgeUnit:
type: string
description: '"days" for an observation timestamp or "years" for an annual source row.'
observationAgeBasis:
type: string
description: '"observation-timestamp" or "source-year". Never derived from retrieval time.'
retrievedAtAvailable:
type: boolean
description: True when retrieved_at contains an explicit retrieval timestamp.
retrievedAt:
type: string
description: Explicit ISO-8601 retrieval timestamp; never inferred from source year.
observedAtAvailable:
type: boolean
description: True when observed_at contains a provider observation timestamp.
observedAt:
type: string
description: Provider observation timestamp in ISO-8601 form.
sources:
type: array
items:
$ref: '#/components/schemas/ResilienceIndicatorSource'
rawValue:
$ref: '#/components/schemas/ResilienceIndicatorRawValue'
description: One registry indicator and its effective contribution to a dimension.
ResilienceIndicatorSource:
type: object
properties:
key:
type: string
description: Stable source or cache key used by the resilience scorer.
name:
type: string
description: Human-readable provider or dataset name.
attribution:
type: string
description: Attribution text that callers must preserve when displaying the value.
license:
type: string
description: Audited source license or redistribution classification.
url:
type: string
description: Canonical provider or methodology URL when one is available.
observationProvenance:
type: boolean
description: |-
True only when this source was recorded for the selected country observation.
False means the entry is registry attribution, not observation provenance.
licenseUrl:
type: string
description: Canonical URL for the audited source license or redistribution terms.
attributionUrl:
type: string
description: Canonical attribution URL when it differs from the source dataset URL.
description: |-
Source-level attribution and provenance for one indicator. Composite
indicators repeat this message once for every upstream source they use.
ResilienceIndicatorRawValue:
type: object
properties:
available:
type: boolean
description: True only when at least one raw value representation may be redistributed.
numericValue:
type: number
format: double
description: Numeric raw observation. Read numeric_value_available before this value.
numericValueAvailable:
type: boolean
description: True when numeric_value contains an audited redistributable observation.
textValue:
type: string
description: Categorical raw observation. Read text_value_available before this value.
textValueAvailable:
type: boolean
description: True when text_value contains an audited redistributable observation.
unit:
type: string
description: Unit attached to the raw observation, for example percent or days.
status:
type: string
description: |-
available, absent, restricted, audit-incomplete, conditional,
ineligible-observation, or unknown-indicator.
reason:
type: string
description: Human-readable explanation for an unavailable or withheld value.
description: |-
Selectively exposed raw observation. Availability fields keep a withheld or
absent value distinct from a genuine numeric zero or empty categorical value.
GetFoodStocksRequest:
type: object
properties:
countryCode:
type: string
description: ISO 3166-1 alpha-2, or WORLD. Empty returns the unfiltered snapshot.
commodity:
type: string
description: Commodity slug (wheat, corn, rice, soybeans, barley, palmOil). Empty = all.
description: GetFoodStocksRequest filters the seeded USDA-style food-stocks snapshot.
GetFoodStocksResponse:
type: object
properties:
records:
type: array
items:
$ref: '#/components/schemas/FoodStockRecord'
fetchedAt:
type: string
description: ISO-8601 time the seeder wrote resilience:food-stocks:v1. Empty when unavailable.
unavailable:
type: boolean
description: True when the seed is missing or unreadable (not a confirmed zero).
calorieWeightedStocksToUse:
type: number
format: double
description: Calorie-weighted stocks-to-use for the requested country, or 0 when unknown / unfiltered.
description: GetFoodStocksResponse is the filtered seed snapshot.
FoodStockRecord:
type: object
properties:
countryCode:
type: string
description: ISO 3166-1 alpha-2, or "WORLD" for the global balance sheet.
commodity:
type: string
description: 'Commodity slug: wheat, corn, rice, soybeans, barley, palmOil.'
marketingYear:
type: string
description: Marketing year label stored verbatim, e.g. "2025/26". Never a calendar year.
stocksToUse:
type: number
format: double
description: |-
Ending stocks divided by total use (0.18 = 18%). Read hasStocksToUse
BEFORE this value: proto3 has no presence for a bare double, so an unknown
ratio and a genuine 0% are the same wire value. USDA/PSD estimates ending
stocks only for selected countries, so a minor producer routinely reports
real production and consumption with no stocks series at all — and 0.0% on
a food-security surface reads as famine, not as "not measured".
hasStocksToUse:
type: boolean
description: False when stocks_to_use is a placeholder rather than a measurement.
endingStocksTmt:
type: number
format: double
description: |-
Ending stocks in thousand metric tons. Read has_ending_stocks first, for
the same reason as stocks_to_use above.
hasEndingStocks:
type: boolean
description: False when ending_stocks_tmt is a placeholder rather than a measurement.
totalUseTmt:
type: number
format: double
description: |-
1000 MT. PSD country: consumption + exports. WORLD: consumption.
FAOSTAT: domestic-supply quantity.
productionTmt:
type: number
format: double
description: Production in thousand metric tons. Zero when unknown.
consumptionTmt:
type: number
format: double
description: |-
1000 MT. PSD: domestic consumption. FAOSTAT: domestic-supply quantity.
Zero when unknown.
importsTmt:
type: number
format: double
description: Imports in thousand metric tons. Zero when unknown.
exportsTmt:
type: number
format: double
description: Exports in thousand metric tons. Zero when unknown.
unit:
type: string
description: Unit the raw quantities are stored in, typically "1000 MT".
source:
type: string
description: |-
"psd" or "faostat". FAOSTAT Food Balances supplies production and
domestic-supply, but no stocks.
description: One country (or WORLD) × commodity production/stocks balance from the seeded snapshot.
GetDemographicsCapabilityRequest:
type: object
properties:
countryCode:
type: string
description: Required ISO 3166-1 alpha-2 country code.
required:
- countryCode
GetDemographicsCapabilityResponse:
type: object
properties:
countryCode:
type: string
available:
type: boolean
description: True when at least one validated observation exists for the country.
fetchedAt:
type: string
description: ISO-8601 time the canonical snapshot was generated.
stages:
type: array
items:
$ref: '#/components/schemas/DemographicsCapabilityStage'
ageStructure:
$ref: '#/components/schemas/DemographicsAgeStructure'
education:
$ref: '#/components/schemas/DemographicsEducation'
industrialWorkforce:
$ref: '#/components/schemas/DemographicsIndustrialWorkforce'
DemographicsCapabilityStage:
type: object
properties:
name:
type: string
description: 'Stable stage name: wpp, education, or ilostat.'
status:
type: string
description: Seeder state, normally fresh, retained, or unavailable.
fetchedAt:
type: string
description: ISO-8601 time of the data retained for this stage.
recordCount:
type: integer
minimum: 0
format: int32
description: Number of country records retained for the stage.
newestObservationYear:
type: integer
minimum: 0
format: int32
description: Most recent source observation year retained for the stage.
description: Independent fetch-stage state. One failed stage must not hide healthy groups.
DemographicsAgeStructure:
type: object
properties:
available:
type: boolean
medianAgeYears:
$ref: '#/components/schemas/CapabilityObservation'
oldAgeDependencyRatioPercent:
$ref: '#/components/schemas/CapabilityObservation'
totalDependencyRatioPercent:
$ref: '#/components/schemas/CapabilityObservation'
workingAgePopulationPeople:
$ref: '#/components/schemas/CapabilityObservation'
workingAgePopulationProjected10yPeople:
$ref: '#/components/schemas/CapabilityObservation'
CapabilityObservation:
type: object
properties:
available:
type: boolean
description: True when value, year, source and unit pass validation.
value:
type: number
format: double
description: 'Numeric observation. Read available first: zero is also the proto3 placeholder.'
year:
type: integer
minimum: 0
format: int32
description: Source year; not the seed year.
source:
type: string
description: Provider or dataset attribution.
unit:
type: string
description: 'Unit: percent, people, or years.'
sourceStatus:
type: string
description: Provider or input status; absent is unknown.
description: CapabilityObservation keeps a measured zero distinct from a missing value.
DemographicsEducation:
type: object
properties:
available:
type: boolean
tertiaryEnrollmentGrossPercent:
$ref: '#/components/schemas/CapabilityObservation'
stemGraduatesSharePercent:
$ref: '#/components/schemas/CapabilityObservation'
researchersPerMillion:
$ref: '#/components/schemas/CapabilityObservation'
DemographicsIndustrialWorkforce:
type: object
properties:
available:
type: boolean
craftTradesEmploymentPeople:
$ref: '#/components/schemas/CapabilityObservation'
plantMachineOperatorsEmploymentPeople:
$ref: '#/components/schemas/CapabilityObservation'
trainedIndustrialWorkforcePeople:
$ref: '#/components/schemas/CapabilityObservation'
manufacturingEmploymentSharePercent:
$ref: '#/components/schemas/CapabilityObservation'
GetResilienceRankingRequest:
type: object
GetResilienceRankingResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ResilienceRankingItem'
greyedOut:
type: array
items:
$ref: '#/components/schemas/ResilienceRankingItem'
fetchedAt:
type: string
scored:
type: integer
format: int32
total:
type: integer
format: int32
coverage:
type: number
format: double
partial:
type: boolean
ResilienceRankingItem:
type: object
properties:
countryCode:
type: string
overallScore:
type: number
format: double
level:
type: string
lowConfidence:
type: boolean
overallCoverage:
type: number
format: double
rankStable:
type: boolean
headlineEligible:
type: boolean
description: |-
Current headline-ranking eligibility. True only when the country passes
the headline gate: coverage >= 0.65 AND (population >= 200k OR
coverage >= 0.85) AND !lowConfidence. GetResilienceRanking includes
only eligible countries in items[]; scored but ineligible countries
remain in greyedOut[].
GetResilienceRuntimeManifestRequest:
type: object
GetResilienceRuntimeManifestResponse:
type: object
properties:
manifestVersion:
type: integer
format: int32
generatedAt:
type: string
deployedCommitSha:
type: string
vercelEnv:
type: string
formulaTag:
type: string
dataVersion:
type: string
flags:
type: array
items:
$ref: '#/components/schemas/ResilienceRuntimeFlag'
cache:
$ref: '#/components/schemas/ResilienceRuntimeCacheState'
rankingCache:
$ref: '#/components/schemas/ResilienceRankingCacheState'
constructVersions:
$ref: '#/components/schemas/ResilienceRuntimeConstructVersions'
intervals:
$ref: '#/components/schemas/ResilienceRuntimeIntervalState'
ResilienceRuntimeFlag:
type: object
properties:
name:
type: string
enabled:
type: boolean
ResilienceRuntimeCacheState:
type: object
properties:
scorePrefix:
type: string
rankingKey:
type: string
historyPrefix:
type: string
intervalPrefix:
type: string
intervalMethodology:
type: string
ResilienceRankingCacheState:
type: object
properties:
fetchedAt:
type: string
count:
type: integer
format: int32
scored:
type: integer
format: int32
total:
type: integer
format: int32
ResilienceRuntimeIntervalState:
type: object
properties:
available:
type: boolean
description: |-
True only when the public sample interval matches the active formula,
education construct version, and interval methodology.
methodology:
type: string
description: Public methodology tag used to audit scoreInterval/rankStable semantics.
sampleCountry:
type: string
description: ISO2 country used for the public availability probe.
lastObservedAt:
type: string
description: Latest safe observed timestamp from interval seed-meta or sample payload.