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: 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. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/resilience/v1/get-resilience-ranking: get: tags: - ResilienceService summary: GetResilienceRanking description: PRO-gated. Requires an active Pro subscription. operationId: GetResilienceRanking security: - WorldMonitorKey: [] - ApiKeyHeader: [] - BearerAuth: [] parameters: - name: jmespath in: query description: >- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: coverage: 1.5 fetchedAt: '2026-01-15T12:00:00Z' greyedOut: - countryCode: US headlineEligible: true level: example lowConfidence: true overallCoverage: 1.5 items: - countryCode: US headlineEligible: true level: example lowConfidence: true overallCoverage: 1.5 partial: true schema: $ref: '#/components/schemas/GetResilienceRankingResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: Pro subscription required. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/resilience/v1/get-runtime-manifest: get: tags: - ResilienceService summary: GetResilienceRuntimeManifest description: >- GetResilienceRuntimeManifest returns the public resilience-scoring runtime manifest: manifest version, generation timestamp, active formula tag, cache state, construct versions, and interval availability. operationId: GetResilienceRuntimeManifest security: [] parameters: - name: jmespath in: query description: >- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: cache: historyPrefix: example intervalMethodology: example intervalPrefix: example rankingKey: example scorePrefix: example constructVersions: energy: example dataVersion: example deployedCommitSha: example flags: - enabled: true name: WorldMonitor Analyst schema: $ref: '#/components/schemas/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 . schemas: JmespathProjectionError: description: >- Returned when a REST jmespath projection is invalid or exceeds the expression/output byte limits. properties: _jmespath_error: description: Projection error discriminator and details. type: string original_keys: description: Top-level keys or shape of the unprojected response. items: type: string type: array required: - _jmespath_error - original_keys type: object UnauthorizedError: type: object properties: error: type: string description: Human-readable error message. required: - error description: >- Returned when the API key is missing, malformed, or lacks current API access. Error: type: object properties: message: type: string description: Error message (e.g., 'user not found', 'database connection failed') description: >- Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize. InvalidRequestBodyError: type: object description: Returned when a JSON POST request body is empty or malformed. properties: message: type: string description: Invalid request body required: - message GatewayError: type: object description: >- Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks. properties: error: oneOf: - type: string - type: object additionalProperties: true description: Gateway error reason or structured gateway failure details. required: - error RateLimitError: type: object description: Returned when a gateway or handler rate limit rejects the request. properties: error: type: string description: Human-readable rate-limit failure reason. required: - error ForbiddenError: type: object properties: error: type: string description: Human-readable entitlement failure reason. requiredTier: type: integer format: int32 description: Minimum entitlement tier required for this endpoint. currentTier: type: integer format: int32 description: Caller entitlement tier when known. planKey: type: string description: Caller plan key when known. required: - error description: >- Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier. FieldViolation: type: object properties: field: type: string description: >- The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key') description: type: string description: >- Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing') required: - field - description description: FieldViolation describes a single validation error for a specific field. ValidationError: type: object properties: violations: type: array items: $ref: '#/components/schemas/FieldViolation' description: List of validation violations required: - violations description: >- ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong. 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. 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 ResilienceRuntimeConstructVersions: type: object properties: energy: type: string description: >- Safe derived energy construct version. Valid values: "legacy" or "v2". ResilienceRuntimeIntervalState: type: object properties: available: type: boolean description: >- True only when the public sample interval can be read for the active formula. methodology: type: string description: >- Public methodology tag used to audit scoreInterval/rankStable semantics. sampleCountry: type: string description: ISO2 country used for the public availability probe. lastObservedAt: type: string description: >- Latest safe observed timestamp from interval seed-meta or sample payload.