{
  "openapi": "3.1.0",
  "info": {
    "title": "PensionHunter",
    "version": "1.1.2",
    "description": "Identification and research only. States barriers with sources and read dates; routes are in the paid report, except a route an institution has asked us in writing to publish. No account, stores nothing.",
    "contact": {
      "url": "https://pensionhunter.ai/developers"
    }
  },
  "externalDocs": {
    "url": "https://pensionhunter.ai/mcp",
    "description": "Connector setup"
  },
  "servers": [
    {
      "url": "https://mcp.pensionhunter.ai",
      "description": "Public endpoint"
    },
    {
      "url": "https://givkcvqnhbuiprutblom.supabase.co/functions/v1/mcp-connector",
      "description": "Fallback: the same function on Supabase"
    }
  ],
  "paths": {
    "/tools/list_covered_countries": {
      "post": {
        "operationId": "list_covered_countries",
        "summary": "List covered countries",
        "description": "The countries PensionHunter covers, each with its ISO code and one sourced line on what exists there. Takes no input.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result. Every result ends with the report offer and an order link built for its countries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "countryCount": {
                      "type": "integer"
                    },
                    "countries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "country": {
                            "type": "string"
                          },
                          "iso2": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "whatExists": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.",
                            "properties": {
                              "text": {
                                "type": "string"
                              },
                              "source": {
                                "type": "string",
                                "description": "The publisher or document the fact comes from."
                              },
                              "read": {
                                "type": "string",
                                "description": "The date we read the source, for example 7 October 2026."
                              }
                            },
                            "required": [
                              "text",
                              "source",
                              "read"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "required": [
                          "country",
                          "iso2",
                          "whatExists"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "offer": {
                      "type": "string",
                      "description": "The report offer, with prices, delivery time and refund terms."
                    },
                    "orderUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Order page for the countries in this result: tier=country&country=<ISO> for one covered country, tier=global for several. It never carries personal data."
                    }
                  },
                  "required": [
                    "countryCount",
                    "countries",
                    "offer",
                    "orderUrl"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid input. The error says how to fix the call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Retry after the number of seconds in the Retry-After header."
          }
        }
      }
    },
    "/tools/country_pension_facts": {
      "post": {
        "operationId": "country_pension_facts",
        "summary": "Country pension facts",
        "description": "One country's stored facts: what the money is worth, why the free route fails from abroad, and dated obligations, each with source and read date. Accepts names, native names, aliases and ISO codes. A country outside our coverage returns covered: false with a note.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "country": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 200,
                    "description": "One country, as an English name, a native name, a common alias or an ISO 3166 alpha-2 or alpha-3 code, in any case. Examples: Netherlands, Nederland, Holland, NL, NLD; United Kingdom, UK, GB, Britain; Germany, Deutschland, DE."
                  }
                },
                "required": [
                  "country"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result. Every result ends with the report offer and an order link built for its countries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string",
                      "description": "The country string as sent."
                    },
                    "country": {
                      "type": "string",
                      "description": "The country it was read as."
                    },
                    "iso2": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "recognised": {
                      "type": "boolean",
                      "description": "False when the string is not a country we can read."
                    },
                    "covered": {
                      "type": "boolean"
                    },
                    "whatTheMoneyIsWorth": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.",
                      "properties": {
                        "text": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string",
                          "description": "The publisher or document the fact comes from."
                        },
                        "read": {
                          "type": "string",
                          "description": "The date we read the source, for example 7 October 2026."
                        }
                      },
                      "required": [
                        "text",
                        "source",
                        "read"
                      ],
                      "additionalProperties": false
                    },
                    "whyTheFreeRouteFailsFromAbroad": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.",
                      "properties": {
                        "text": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string",
                          "description": "The publisher or document the fact comes from."
                        },
                        "read": {
                          "type": "string",
                          "description": "The date we read the source, for example 7 October 2026."
                        }
                      },
                      "required": [
                        "text",
                        "source",
                        "read"
                      ],
                      "additionalProperties": false
                    },
                    "datedObligations": {
                      "type": "array",
                      "items": {
                        "type": [
                          "object",
                          "null"
                        ],
                        "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.",
                        "properties": {
                          "text": {
                            "type": "string"
                          },
                          "source": {
                            "type": "string",
                            "description": "The publisher or document the fact comes from."
                          },
                          "read": {
                            "type": "string",
                            "description": "The date we read the source, for example 7 October 2026."
                          }
                        },
                        "required": [
                          "text",
                          "source",
                          "read"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "contactAbroad": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "A contact route for people abroad that the institution has told us in writing we may publish, with that written reply as its source. Null for every other country: routes are in the paid report.",
                      "properties": {
                        "text": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string",
                          "description": "The publisher or document the fact comes from."
                        },
                        "read": {
                          "type": "string",
                          "description": "The date we read the source, for example 7 October 2026."
                        }
                      },
                      "required": [
                        "text",
                        "source",
                        "read"
                      ],
                      "additionalProperties": false
                    },
                    "pending": {
                      "type": "string"
                    },
                    "note": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "string",
                      "description": "The report offer, with prices, delivery time and refund terms."
                    },
                    "orderUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Order page for the countries in this result: tier=country&country=<ISO> for one covered country, tier=global for several. It never carries personal data."
                    }
                  },
                  "required": [
                    "query",
                    "country",
                    "iso2",
                    "recognised",
                    "covered",
                    "offer",
                    "orderUrl"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid input. The error says how to fix the call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Retry after the number of seconds in the Retry-After header."
          }
        }
      }
    },
    "/tools/check_work_history": {
      "post": {
        "operationId": "check_work_history",
        "summary": "Check a work history",
        "description": "For each country in a work history: whether a pension is likely to exist and why, why self service fails from abroad, and a dated obligation only where it applies to the subject. Countries accept names, native names, aliases and ISO codes. Nothing sent is stored.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "entries": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 60,
                    "description": "One entry per period of work in a country.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "country": {
                          "type": "string",
                          "minLength": 2,
                          "maxLength": 80,
                          "description": "One country, as an English name, a native name, a common alias or an ISO 3166 alpha-2 or alpha-3 code, in any case. Examples: Netherlands, Nederland, Holland, NL, NLD; United Kingdom, UK, GB, Britain; Germany, Deutschland, DE."
                        },
                        "from": {
                          "type": "integer",
                          "minimum": 1900,
                          "maximum": 2100,
                          "description": "First year of work there, four digits."
                        },
                        "to": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 1900,
                          "maximum": 2100,
                          "description": "Last year of work there, four digits; null or omitted if still working there."
                        },
                        "employer": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "maxLength": 120,
                          "description": "Employer name, optional."
                        }
                      },
                      "required": [
                        "country",
                        "from"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "subject": {
                    "type": "object",
                    "description": "Optional facts about the person, used only to decide which dated obligations apply.",
                    "properties": {
                      "birthYear": {
                        "type": "integer",
                        "minimum": 1900,
                        "maximum": 2100,
                        "description": "Year of birth, four digits."
                      },
                      "deceased": {
                        "type": "boolean",
                        "description": "True when the person has died and a relative is asking."
                      },
                      "pensionInPaymentCountries": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "description": "One country, as an English name, a native name, a common alias or an ISO 3166 alpha-2 or alpha-3 code, in any case. Examples: Netherlands, Nederland, Holland, NL, NLD; United Kingdom, UK, GB, Britain; Germany, Deutschland, DE."
                        },
                        "description": "Countries already paying the person a pension."
                      },
                      "childrenMentioned": {
                        "type": "boolean",
                        "description": "True when children are part of the question."
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "required": [
                  "entries"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result. Every result ends with the report offer and an order link built for its countries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "countries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "country": {
                            "type": "string"
                          },
                          "iso2": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "recognised": {
                            "type": "boolean"
                          },
                          "period": {
                            "type": "string"
                          },
                          "covered": {
                            "type": "boolean"
                          },
                          "likelyToExist": {
                            "type": "object",
                            "properties": {
                              "assessment": {
                                "type": "string"
                              },
                              "why": {
                                "type": [
                                  "object",
                                  "null"
                                ],
                                "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.",
                                "properties": {
                                  "text": {
                                    "type": "string"
                                  },
                                  "source": {
                                    "type": "string",
                                    "description": "The publisher or document the fact comes from."
                                  },
                                  "read": {
                                    "type": "string",
                                    "description": "The date we read the source, for example 7 October 2026."
                                  }
                                },
                                "required": [
                                  "text",
                                  "source",
                                  "read"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "assessment",
                              "why"
                            ],
                            "additionalProperties": false
                          },
                          "whySelfServiceFailsFromAbroad": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.",
                            "properties": {
                              "text": {
                                "type": "string"
                              },
                              "source": {
                                "type": "string",
                                "description": "The publisher or document the fact comes from."
                              },
                              "read": {
                                "type": "string",
                                "description": "The date we read the source, for example 7 October 2026."
                              }
                            },
                            "required": [
                              "text",
                              "source",
                              "read"
                            ],
                            "additionalProperties": false
                          },
                          "contactAbroad": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "description": "A contact route for people abroad that the institution has told us in writing we may publish. Null otherwise.",
                            "properties": {
                              "text": {
                                "type": "string"
                              },
                              "source": {
                                "type": "string",
                                "description": "The publisher or document the fact comes from."
                              },
                              "read": {
                                "type": "string",
                                "description": "The date we read the source, for example 7 October 2026."
                              }
                            },
                            "required": [
                              "text",
                              "source",
                              "read"
                            ],
                            "additionalProperties": false
                          },
                          "datedObligation": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.",
                            "properties": {
                              "text": {
                                "type": "string"
                              },
                              "source": {
                                "type": "string",
                                "description": "The publisher or document the fact comes from."
                              },
                              "read": {
                                "type": "string",
                                "description": "The date we read the source, for example 7 October 2026."
                              }
                            },
                            "required": [
                              "text",
                              "source",
                              "read"
                            ],
                            "additionalProperties": false
                          },
                          "toConfirm": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "employers": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "required": [
                          "country",
                          "iso2",
                          "recognised",
                          "period",
                          "covered",
                          "likelyToExist",
                          "whySelfServiceFailsFromAbroad",
                          "contactAbroad",
                          "datedObligation",
                          "toConfirm",
                          "employers"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "offer": {
                      "type": "string",
                      "description": "The report offer, with prices, delivery time and refund terms."
                    },
                    "orderUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Order page for the countries in this result: tier=country&country=<ISO> for one covered country, tier=global for several. It never carries personal data."
                    }
                  },
                  "required": [
                    "countries",
                    "offer",
                    "orderUrl"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid input. The error says how to fix the call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Retry after the number of seconds in the Retry-After header."
          }
        }
      }
    },
    "/tools/resolve_employer": {
      "post": {
        "operationId": "resolve_employer",
        "summary": "Place an employer in a country",
        "description": "The country an employer name implies, from evidence in the name itself, matched anywhere in it: a country or native country name, a city, a nationality word, or a national legal form such as B.V., GmbH, ASA, Oyj, S.L. or Pte. Ltd. A form used in several countries (GmbH, Ltd, S.A.) returns the candidates instead of a guess.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 200,
                    "description": "The employer name as the person knows it, ideally with its legal form and city, for example \"Shell Nederland B.V.\" or \"Deutsche Bank Frankfurt\"."
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result. Every result ends with the report offer and an order link built for its countries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "resolved": {
                      "type": "boolean"
                    },
                    "country": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "iso2": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "covered": {
                      "type": "boolean",
                      "description": "True when the country is one we cover."
                    },
                    "candidates": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Countries the evidence allows when it does not settle on one."
                    },
                    "evidence": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": [
                              "country",
                              "recorded",
                              "city",
                              "nationality",
                              "suffix"
                            ]
                          },
                          "matched": {
                            "type": "string"
                          },
                          "countries": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "required": [
                          "kind",
                          "matched",
                          "countries"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "reason": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "string",
                      "description": "The report offer, with prices, delivery time and refund terms."
                    },
                    "orderUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Order page for the countries in this result: tier=country&country=<ISO> for one covered country, tier=global for several. It never carries personal data."
                    }
                  },
                  "required": [
                    "name",
                    "resolved",
                    "country",
                    "iso2",
                    "covered",
                    "candidates",
                    "evidence",
                    "reason",
                    "offer",
                    "orderUrl"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid input. The error says how to fix the call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Retry after the number of seconds in the Retry-After header."
          }
        }
      }
    }
  }
}