{"openapi":"3.1.0","info":{"title":"NationsHelm API","version":"1.0.0","description":"Sourced, deterministic geopolitical scores for nations and their leaders, served from immutable pinned snapshots. Every value is sourced or derived and dated; null means No data — never a fabricated number. Every response carries a snapshot_id identifying the immutable published snapshot it came from — its publication is verifiable in /snapshots — and a cite_url that attribution terms require surfacing. Keys are self-serve at https://nationshelm.com/account. Current scoring model: 5.5.0."},"servers":[{"url":"https://nationshelm.com/api/v1"}],"security":[{"bearer":[]},{"apiKey":[]}],"paths":{"/resolve":{"get":{"summary":"Resolve free text to a canonical NationsHelm entity","description":"The front door for agents. Maps a natural-language mention (\"France\", \"the president of France\", \"Macron\") to a canonical nation or leader ref plus confidence. All other endpoints take canonical refs only.","parameters":[{"name":"q","in":"query","required":true,"description":"The mention to resolve: a nation name, ISO2, slug, a leader name, or a role phrase (\"the president of France\"). Max 200 characters.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Best match plus alternatives","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entity_type":{"type":"string","enum":["nation","leader"]},"entity_ref":{"type":"string","description":"Nation: ISO2 (\"FR\"). Leader: \"person/term\" slug pair."},"display_name":{"type":"string"},"confidence":{"type":"number"},"alternatives":{"type":"array","items":{"type":"object"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"no_match — nothing resolved"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/nations/{ref}":{"get":{"summary":"Nation scores, derived indices, momentum, current leader","parameters":[{"$ref":"#/components/parameters/nationRef"},{"$ref":"#/components/parameters/snapshot"}],"responses":{"200":{"description":"Nation profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Nation"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Unknown ref"},"410":{"$ref":"#/components/responses/SnapshotNotAvailable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/nations/{ref}/history":{"get":{"summary":"Historical series for one indicator","parameters":[{"$ref":"#/components/parameters/nationRef"},{"name":"metric","in":"query","required":true,"description":"Which indicator series to return. One id per request.","schema":{"type":"string","enum":["gdpGrowth","inflationAnnual","unemployment","debtToGdp","fiscalBalance","meanWage","govEffectiveness","ruleOfLaw","controlOfCorruption","regulatoryQuality","voiceAndAccountability","politicalStability","basicSanitation","safelyManagedSanitation","electricityAccess","cleanCookingAccess","povertyExtreme","airQualityPm25","patentApplications","tertiaryEnrolment","transparency","vdemElections","vdemCorruption","vdemCensorship","elecSolarPct","elecWindPct","elecHydroPct","elecCoalPct","elecGasPct","elecNuclearPct","selfSufficiencyPct","cerealYieldKgHa","irrigationPctCropland","foodTradeBalanceUsd","foodExportsPct","arableLandPct","arableLandHaPerCapita","freshwaterPerCapitaM3","mineralLithiumProd","mineralCopperProd","mineralRareEarthsProd"]}}],"responses":{"200":{"description":"Yearly points, ascending. Free-tier keys receive the last 10 years relative to the series' freshest point, with truncated:true.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"nation_ref":{"type":"string"},"metric":{"type":"string"},"label":{"type":"string"},"unit":{"type":["string","null"]},"source":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","format":"date"},"value":{"type":"number"},"unit":{"type":["string","null"]}}}},"truncated":{"type":"boolean"}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Missing or unknown metric"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Unknown ref"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Series store temporarily unavailable; retry"}}}},"/leaders/{person}/{term}":{"get":{"summary":"Leader ratings (eight dimensions), archetype, tenure, Analyst Outlook","parameters":[{"name":"person","in":"path","required":true,"description":"Person slug, e.g. \"emmanuel-macron\". Resolve one with /resolve.","schema":{"type":"string"}},{"name":"term","in":"path","required":true,"description":"Term slug — the tenure start year. Each tenure is scored separately, so the term is part of the identity, not an optional qualifier.","schema":{"type":"string"}},{"$ref":"#/components/parameters/snapshot"}],"responses":{"200":{"description":"Leader profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Leader"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Unknown person/term"},"410":{"$ref":"#/components/responses/SnapshotNotAvailable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/rankings/{slug}":{"get":{"summary":"A ranked list","parameters":[{"name":"slug","in":"path","required":true,"description":"Which ranked list to return.","schema":{"type":"string","enum":["most-stable-countries","least-stable-countries","strongest-economies","best-governance","worst-governance","highest-quality-of-life","most-innovative-countries","most-resilient-countries","best-countries-to-invest-in","best-countries-to-start-a-business","best-countries-to-emigrate-to","strongest-strategic-position","least-resilient-countries","top-countries-overall","most-undervalued-countries","small-nations-punching-above-their-weight","highest-rated-world-leaders"]}},{"$ref":"#/components/parameters/snapshot"}],"responses":{"200":{"description":"Ordered entries with scores","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"entity_type":{"type":"string","enum":["nation","leader"]},"metric_label":{"type":"string"},"score_kind":{"type":"string","enum":["score","gap"]},"scope_note":{"type":["string","null"]},"entries":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"entity_ref":{"type":["string","null"]},"display_name":{"type":"string"},"score":{"type":"number"},"score_display":{"type":["string","null"]}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Unknown ranking slug (body lists the catalog)"},"410":{"$ref":"#/components/responses/SnapshotNotAvailable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/compare/nations/{a}/{b}":{"get":{"summary":"Head-to-head nation comparison","parameters":[{"name":"a","in":"path","required":true,"description":"Left nation — ISO2 or site slug. Deltas are a minus b.","schema":{"type":"string"}},{"name":"b","in":"path","required":true,"description":"Right nation — ISO2 or site slug.","schema":{"type":"string"}},{"$ref":"#/components/parameters/snapshot"}],"responses":{"200":{"description":"Both profiles plus per-dimension deltas (a minus b)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"a":{"$ref":"#/components/schemas/Nation"},"b":{"$ref":"#/components/schemas/Nation"},"deltas":{"type":"object","description":"a minus b per dimension; null when either side is No data.","additionalProperties":{"type":["number","null"]}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Unknown ref"},"410":{"$ref":"#/components/responses/SnapshotNotAvailable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/metrics":{"get":{"summary":"Catalog: historical series available from /nations/{ref}/history","description":"Enumerable catalog of series ids. /resolve maps free text to entities; this answers what exists, which a program needs and a matcher cannot provide. availability is null only when coverage could not be read. A series no nation carries yet reports nations_covered 0 — a measured count, never a fabricated one.","responses":{"200":{"description":"Every series id with label, unit, source, and nation coverage","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"metrics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pass to /nations/{ref}/history?metric="},"label":{"type":"string"},"unit":{"type":["string","null"]},"group":{"type":"string"},"source":{"type":"string"},"availability":{"type":["object","null"],"properties":{"nations_covered":{"type":"integer"},"of":{"type":"integer"}}}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/indicators":{"get":{"summary":"Catalog: every indicator the scores are computed from","description":"The methodology in machine-readable form. `id` is a permanent public identifier: `name` is a display label and may be reworded, but the id it was derived from never changes. `type` is the provenance bucket — `sourced` (ingested verbatim) or `derived` (computed from sourced inputs), the only two values; `status` marks frozen or retired series, which must never be read as current.","responses":{"200":{"description":"Indicator rows with source, cadence, and lifecycle status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"indicators":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Permanent identifier."},"name":{"type":"string","description":"Display label; may change."},"kind":{"type":"string","enum":["primary","derived"]},"category_id":{"type":"string"},"category_label":{"type":"string"},"group":{"type":["string","null"]},"type":{"type":"string","enum":["sourced","derived"]},"source":{"type":"string"},"source_short":{"type":["string","null"]},"update":{"type":"string","description":"Published refresh cadence."},"status":{"type":"string","enum":["active","frozen","retired"]},"leader_stat":{"type":["string","null"]}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/dimensions":{"get":{"summary":"Catalog: the score keys a nation payload contains","description":"Makes /nations self-describing: where each key sits in the payload, its scale, which direction is better (risk is the one where higher is worse), and the indicator row documenting it.","responses":{"200":{"description":"Payload score keys with location, scale, and direction","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"dimensions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"location":{"type":"string","enum":["overall","scores","derived","derived.opportunity"]},"scale":{"type":"string","enum":["0-100"]},"direction":{"type":"string","enum":["higher_is_better","higher_is_worse"]},"indicator_id":{"type":["string","null"]}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/snapshots":{"get":{"summary":"Published snapshot registry (transparency surface)","responses":{"200":{"description":"Snapshot ids and publish dates, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"snapshots":{"type":"array","items":{"type":"object","properties":{"snapshot_id":{"type":"string"},"published_at":{"type":"string","format":"date-time"},"active":{"type":"boolean"},"scoring_model_version":{"type":["string","null"]}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/corrections":{"get":{"summary":"Append-only public corrections log (transparency surface)","responses":{"200":{"description":"Dated, signed correction entries; never deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"corrections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string","format":"date"},"entity":{"type":["string","null"]},"entity_type":{"type":["string","null"],"enum":["nation","leader",null]},"indicator":{"type":"string"},"summary":{"type":"string"},"before":{"type":["string","null"]},"after":{"type":["string","null"]},"signed":{"type":"string"}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Primary auth: \"Authorization: Bearer nh_live_…\". Keys are self-serve from https://nationshelm.com/account; shown once, stored hashed. Never send a key in a query string."},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Accepted alias for the same key."}},"parameters":{"nationRef":{"name":"ref","in":"path","required":true,"description":"ISO2 code or site slug; responses canonicalize to ISO2.","schema":{"type":"string"}},"snapshot":{"name":"snapshot","in":"query","required":false,"description":"Pin the response to a specific snapshot id. Default: the active snapshot. Ids other than the active one return 410 snapshot_not_available (v1 serves the active snapshot only; the parameter is part of the contract from day one).","schema":{"type":"string"}}},"responses":{"Unauthorized":{"description":"Missing, invalid, or revoked API key"},"RateLimited":{"description":"Rate limit exceeded for this key's plan. Always carries Retry-After and X-RateLimit-Limit / -Remaining / -Reset headers — back off on Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}}},"SnapshotNotAvailable":{"description":"Requested ?snapshot= id is not served; omit for the active snapshot."}},"schemas":{"Meta":{"type":"object","description":"Present on every data-bearing response; makes the payload citable stand-alone.","properties":{"snapshot_id":{"type":["string","null"]},"scoring_model_version":{"type":"string"},"scores_refreshed":{"type":"string","format":"date-time"},"cite_url":{"type":"string","format":"uri","description":"Canonical page to cite; attribution terms require surfacing it."},"provenance_legend":{"type":"string","format":"uri"}}},"ScoredValue":{"type":"object","description":"A score with inline provenance. null value = No data, never fabricated.","properties":{"value":{"type":["number","null"]},"provenance":{"type":"string","enum":["derived"]},"coverage":{"type":"object","properties":{"present":{"type":"integer"},"total":{"type":"integer"}}}}},"Nation":{"type":"object","properties":{"ref":{"type":"string","description":"ISO2"},"slug":{"type":"string"},"name":{"type":"string"},"overall":{"$ref":"#/components/schemas/ScoredValue"},"scores":{"type":"object","description":"Composite 0–100 pillars.","properties":{"economy":{"$ref":"#/components/schemas/ScoredValue"},"governance":{"$ref":"#/components/schemas/ScoredValue"},"quality_of_life":{"$ref":"#/components/schemas/ScoredValue"},"innovation":{"$ref":"#/components/schemas/ScoredValue"},"stability":{"$ref":"#/components/schemas/ScoredValue"}}},"derived":{"type":"object","properties":{"resilience":{"$ref":"#/components/schemas/ScoredValue"},"risk":{"allOf":[{"$ref":"#/components/schemas/ScoredValue"}],"description":"100 minus resilience."},"opportunity":{"type":"object","properties":{"invest_in":{"$ref":"#/components/schemas/ScoredValue"},"start_business":{"$ref":"#/components/schemas/ScoredValue"},"emigrate_to":{"$ref":"#/components/schemas/ScoredValue"}}},"strategic_position":{"$ref":"#/components/schemas/ScoredValue"}}},"momentum":{"type":["object","null"],"description":"null = insufficient committed history, never a fabricated delta.","properties":{"direction":{"type":"string","enum":["up","down","flat"]},"delta":{"type":"number"},"sparse":{"type":"boolean"},"indicator_basis":{"type":"integer"}}},"archetypes":{"type":"array","items":{"type":"string"}},"coverage":{"type":"object"},"current_leader":{"type":["object","null"],"properties":{"person":{"type":"string"},"term":{"type":"string"},"display_name":{"type":"string"},"role":{"type":"string"}}}}},"Leader":{"type":"object","properties":{"person":{"type":"string"},"term":{"type":"string"},"display_name":{"type":"string"},"nation_ref":{"type":"string"},"role":{"type":"string"},"status":{"type":"string","enum":["active","former","historical"]},"tenure":{"type":"object","properties":{"start":{"type":"string","format":"date"},"end":{"type":["string","null"],"format":"date"}}},"rating_model":{"type":"string","description":"Ratings measure per-tenure contribution vs global trends, not the country's level."},"overall":{"$ref":"#/components/schemas/ScoredValue"},"ratings":{"type":"object","description":"Eight dimensions (gov eco dip pol cri vis com int), 0–100 or null (No data).","additionalProperties":{"$ref":"#/components/schemas/ScoredValue"}},"archetype":{"type":["string","null"]},"sourced_stat_count":{"type":"integer"},"analyst_outlook":{"type":"object","description":"The one LLM-authored field in the API. Gated to Analyst+ keys; lower plans receive available:false + requires_plan. Always labeled ai_generated:true — never blended into any score.","properties":{"available":{"type":"boolean"},"requires_plan":{"type":["string","null"]},"ai_generated":{"type":"boolean"},"label":{"type":"string"},"headline":{"type":"string"},"predictions":{"type":"array","items":{"type":"object"}},"model":{"type":"string"},"as_of":{"type":"string"}}}}}}}}