{"openapi":"3.0.3","info":{"title":"Gnist Context — International Migration (UNHCR)","description":"Global displacement statistics from UNHCR — refugees, asylum seekers, IDPs, stateless persons. 70+ years of data across 200+ countries with demographics and durable solutions.\n\n- **MCP endpoint:** `https://context.gnist.ai/mcp/migration/`\n- **Toolkit page:** `/toolkits/migration`\n- **Full API spec:** `/api/openapi.json`\n- **Get an API key:** `/signup`","version":"1.0.0","contact":{"name":"GnistAI","url":"https://gnist.ai"}},"servers":[{"url":"https://context.gnist.ai","description":"Production"}],"paths":{"/rest/migration/get_population":{"post":{"tags":["Government"],"summary":"get_population","description":"Get refugee, asylum seeker, IDP, and stateless population statistics from UNHCR.\n\nCovers 70+ years of global displacement data across 200+ countries. Returns counts of\nrefugees, asylum seekers, internally displaced persons (IDPs), stateless persons,\nand other populations of concern by country of origin and asylum.\n\nExamples:\n    get_population(year=2023, country_of_origin=\"SYR\") → Syrian displacement worldwide\n    get_population(year=2023, country_of_asylum=\"DEU\") → All displaced populations in Germany\n    get_population(year=2023) → Global displacement snapshot\n\nReturns:\n    page, max_pages, results (list of population records by origin/asylum pair).","operationId":"migration_get_population","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by year (1951–2025). Example: 2023."},"country_of_origin":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ISO country code of origin (2 or 3 letter). Example: 'SYR' for Syria, 'UA' for Ukraine."},"country_of_asylum":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ISO country code of asylum (2 or 3 letter). Example: 'DEU' for Germany, 'US' for United States."},"limit":{"default":20,"description":"Results per page (1-100).","type":"integer"},"page":{"default":1,"description":"Page number.","type":"integer"}},"type":"object"}}}}}},"/rest/migration/get_demographics":{"post":{"tags":["Government"],"summary":"get_demographics","description":"Get age and gender demographic breakdowns of displaced populations.\n\nReturns female/male counts across age brackets (0-4, 5-11, 12-17, 18-59, 60+)\nfor each origin/asylum country pair.\n\nExamples:\n    get_demographics(year=2023, country_of_asylum=\"DEU\") → Age/gender of displaced in Germany\n    get_demographics(year=2023, country_of_origin=\"AFG\") → Afghan refugee demographics worldwide\n\nReturns:\n    page, max_pages, results (list with female/male age breakdowns).","operationId":"migration_get_demographics","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by year (1951–2025)."},"country_of_origin":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ISO country code of origin."},"country_of_asylum":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ISO country code of asylum."},"limit":{"default":20,"description":"Results per page (1-100).","type":"integer"},"page":{"default":1,"description":"Page number.","type":"integer"}},"type":"object"}}}}}},"/rest/migration/get_solutions":{"post":{"tags":["Government"],"summary":"get_solutions","description":"Get durable solutions data — refugee returns, resettlement, and naturalisation.\n\nTracks how displacement is resolved: voluntary repatriation (returned refugees),\nthird-country resettlement, naturalisation in country of asylum, and IDP returns.\n\nExamples:\n    get_solutions(year=2023) → Global solutions overview\n    get_solutions(year=2023, country_of_origin=\"SYR\") → Syrian returns and resettlement\n\nReturns:\n    page, max_pages, results (list with returned_refugees, resettlement, naturalisation, returned_idps).","operationId":"migration_get_solutions","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by year (1951–2025)."},"country_of_origin":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ISO country code of origin."},"country_of_asylum":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ISO country code of asylum."},"limit":{"default":20,"description":"Results per page (1-100).","type":"integer"},"page":{"default":1,"description":"Page number.","type":"integer"}},"type":"object"}}}}}},"/rest/migration/list_countries":{"post":{"tags":["Government"],"summary":"list_countries","description":"List all countries and territories in the UNHCR displacement dataset.\n\nReturns ISO codes, names, regions, and major areas for 200+ countries.\nUse these codes with get_population, get_demographics, and get_solutions.\n\nReturns:\n    total, countries (list of {code, iso, iso2, name, region, major_area}).","operationId":"migration_list_countries","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}]}},"/rest/migration/report_feedback":{"post":{"tags":["Government"],"summary":"report_feedback","description":"Report a bug, feature request, or general feedback for this data source.\n\nUse this when something doesn't work as expected, when you'd like\na new feature, or when you have suggestions for improvement.\n\nArgs:\n    feedback: Describe the issue or suggestion.\n    feedback_type: One of 'bug', 'feature_request', or 'general'.","operationId":"migration_report_feedback","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"feedback":{"type":"string"},"feedback_type":{"default":"general","type":"string"}},"required":["feedback"],"type":"object"}}}}}}},"tags":[{"name":"Government","description":"Data sources: Government"}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"gnist-api-key","description":"API key passed via request header."},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"gnist_api_key","description":"API key passed via query parameter."}}}}