{"openapi":"3.1.0","info":{"title":"BrightKey Data API","version":"1.0.0","description":"Independent, bilingual (EN+ZH) international-education data: university tier profiles (S/A/B/C/D across 6 dimensions — tiers, not a single rank), an international-school directory, degree ROI, and cited answers. No payments from schools; verified public sources. Free to use and cite with attribution + a link to the source page. MCP server for agents: https://brightkey.co/api/mcp","contact":{"name":"BrightKey","url":"https://brightkey.co"},"license":{"name":"Free with attribution + link to source"}},"servers":[{"url":"https://brightkey.co/v1"}],"paths":{"/universities":{"get":{"operationId":"listUniversities","summary":"List universities with optional filters.","parameters":[{"name":"country","in":"query","schema":{"type":"string"},"description":"Country slug, e.g. uk, us, germany."},{"name":"ib","in":"query","schema":{"type":"boolean"},"description":"Filter to universities that accept the IB."},{"name":"minTier","in":"query","schema":{"type":"string","enum":["S","A","B","C","D"]},"description":"Keep universities whose average tier is at least this."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Name/city substring search."},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Matching universities."}}}},"/universities/{slug}":{"get":{"operationId":"getUniversity","summary":"Full BrightKey profile for one university: tiers + why, verdict, strengths/weaknesses, cost, admissions tips.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. harvard-university, eth-zurich."},{"name":"locale","in":"query","schema":{"type":"string","enum":["en","zh"],"default":"en"},"description":"Response language."}],"responses":{"200":{"description":"University profile."},"404":{"description":"Not found."}}}},"/compare":{"get":{"operationId":"compareUniversities","summary":"Compare two universities on the 6 BrightKey dimensions; returns tier deltas + a sourced tier-delta paragraph.","parameters":[{"name":"a","in":"query","schema":{"type":"string"},"description":"First university slug."},{"name":"b","in":"query","schema":{"type":"string"},"description":"Second university slug."},{"name":"pair","in":"query","schema":{"type":"string"},"description":"Alternative: a-vs-b slug."},{"name":"locale","in":"query","schema":{"type":"string","enum":["en","zh"],"default":"en"},"description":"Response language."}],"responses":{"200":{"description":"Comparison."},"404":{"description":"A slug was not found."}}}},"/roi":{"post":{"operationId":"degreeRoi","summary":"5-year-after-graduation net ROI + break-even year for a degree.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["country"],"properties":{"country":{"type":"string","description":"ROI destination slug, e.g. germany, uk-oxbridge, us-private."}}},{"type":"object","required":["degreeCost","startSalary","taxRate"],"properties":{"degreeCost":{"type":"number"},"startSalary":{"type":"number"},"taxRate":{"type":"number","description":"Effective rate 0–1."}}}]}}}},"responses":{"200":{"description":"ROI result."},"400":{"description":"Invalid input."}}}},"/roi/countries":{"get":{"operationId":"listRoiCountries","summary":"ROI destination dataset, ranked best→worst by net ROI.","responses":{"200":{"description":"Ranked destinations."}}}},"/schools":{"get":{"operationId":"listSchools","summary":"List international schools, filtered by city and/or curriculum.","parameters":[{"name":"city","in":"query","schema":{"type":"string"},"description":"e.g. singapore, tokyo, dubai."},{"name":"curriculum","in":"query","schema":{"type":"string"},"description":"e.g. IB, A-Levels, AP."},{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching schools."}}}},"/answers":{"get":{"operationId":"searchAnswers","summary":"Search BrightKey's cited answers to common international-education questions.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Question keywords."},{"name":"category","in":"query","schema":{"type":"string","enum":["curriculum","schools","universities","visas","process"]}},{"name":"locale","in":"query","schema":{"type":"string","enum":["en","zh"],"default":"en"},"description":"Response language."}],"responses":{"200":{"description":"Best-match answers."}}}}}}