{"openapi":"3.1.0","info":{"title":"Cohort college data API","version":"1.0.0","description":"Free, read-only college and California high school data for students. Rates are fractions 0-1; money is USD per year. Call /v1/methodology for sources.","contact":{"url":"https://collegecohort.com"}},"servers":[{"url":"https://api.collegecohort.com"}],"security":[],"paths":{"/v1/colleges":{"get":{"operationId":"search_colleges","summary":"Search colleges","description":"Find US colleges by name, nickname (UCLA, Cal, MIT) or city, optionally filtered by state, public/private, tuition ceiling, acceptance-rate band, test policy, or a major. Returns compact rows with id, location, enrollment, acceptance rate (fraction 0-1), tuition in/out of state (USD per year), average net price, graduation rates (fractions; see the methodology: graduationRate4yr currently holds the six-year completion rate for four-year colleges), and median earnings 10 years after entry (USD). Use the returned id with get_college, compare_colleges, programs_and_earnings, admissions_by_major or essay_prompts. `count` is the number of rows returned (capped by limit), not the total number of matches. Data: IPEDS and College Scorecard, most recent published year.","parameters":[{"name":"query","in":"query","required":false,"description":"Free text: college name, nickname, or city.","schema":{"type":"string","maxLength":120}},{"name":"state","in":"query","required":false,"description":"Two-letter US state codes; any of them matches.","schema":{"maxItems":10,"type":"array","items":{"type":"string","minLength":2,"maxLength":2}},"style":"form","explode":false},{"name":"type","in":"query","required":false,"description":"public, or private (nonprofit and for-profit).","schema":{"type":"string","enum":["public","private"]}},{"name":"maxTuition","in":"query","required":false,"description":"Maximum in-state tuition in USD per year.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"minAcceptanceRate","in":"query","required":false,"description":"Fraction 0-1.","schema":{"type":"number","minimum":0,"maximum":1}},{"name":"maxAcceptanceRate","in":"query","required":false,"description":"Fraction 0-1.","schema":{"type":"number","minimum":0,"maximum":1}},{"name":"testPolicy","in":"query","required":false,"description":"SAT/ACT policy.","schema":{"type":"string","enum":["optional","blind","required"]}},{"name":"major","in":"query","required":false,"description":"Major name fragment (e.g. 'engineering') or a two-digit CIP family code such as '14' (dotted codes are accepted; families 01-09 may not match).","schema":{"type":"string","maxLength":80}},{"name":"sort","in":"query","required":false,"description":"Sort order. Default: best text match, else enrollment. majorSalary requires major.","schema":{"type":"string","enum":["name","acceptanceRate","tuition","majorSalary"]}},{"name":"limit","in":"query","required":false,"description":"1-25, default 10.","schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}],"responses":{"200":{"description":"JSON result plus dataVersion.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input; error.message explains."},"429":{"description":"Rate limited; retry after a minute."}}}},"/v1/college":{"get":{"operationId":"get_college","summary":"Get a college profile","description":"Full profile for one college by id (preferred) or name/nickname: identity and website, admissions (acceptance rate as a fraction, applied/admitted/enrolled counts, SAT and ACT 25th-75th percentiles, admitted GPA range with its basis), application plans and deadlines with early-round stats, costs (tuition, room and board, average net price and net price by family income band, median debt, aid shares), outcomes (graduation rates, median earnings 10 years after entry), demographics (fractions), Common Data Set admission factors, recommendation-letter rules, test policy, CSU impaction, up to 15 bachelor's programs with the highest median earnings, essay prompt count, and the campus photo credit. If the name is ambiguous, returns up to five candidates with ids instead of guessing. Provide id or name; at least one is required (id preferred).","parameters":[{"name":"id","in":"query","required":false,"description":"College id from search_colleges. Provide id or name; at least one is required (id preferred).","schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},{"name":"name","in":"query","required":false,"description":"College name or nickname, used when id is unknown. Provide id or name; at least one is required (id preferred).","schema":{"type":"string","maxLength":120}}],"responses":{"200":{"description":"JSON result plus dataVersion.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input; error.message explains."},"429":{"description":"Rate limited; retry after a minute."}}}},"/v1/compare":{"get":{"operationId":"compare_colleges","summary":"Compare colleges","description":"Side-by-side headline metrics for 2 to 6 colleges by id: acceptance rate and graduation rates as fractions 0-1, SAT/ACT 25th-75th percentiles of enrolled students, tuition in/out of state, room and board, average net price, and median debt in USD per year, student-faculty ratio, median earnings 10 years after entry in USD per year, enrollment as total headcount, test policy. Also returns cross-admit pairs among the requested colleges: shareChoosingA is the fraction of students admitted to both who enrolled at collegeA (source Parchment, with a confidence interval and sample size). Unknown ids are listed in missingIds.","parameters":[{"name":"ids","in":"query","required":true,"description":"Two to six distinct college ids. REST accepts a comma-separated string.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false}],"responses":{"200":{"description":"JSON result plus dataVersion.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input; error.message explains."},"429":{"description":"Rate limited; retry after a minute."}}}},"/v1/major-admissions":{"get":{"operationId":"admissions_by_major","summary":"Admission rates by major","description":"Per-major admission statistics where a college publishes them (mostly UC and CSU campuses): major label, CIP code, applied and admitted counts, admit rate as a fraction 0-1, and the admissions cycle (e.g. 'Fall 2025'). Query by collegeId to list a college's majors, or by major name / CIP prefix to see which colleges report it. Absence means the college does not publish major-level admits, not that the major is unselective. `count` is the number of rows returned (capped by limit), not the total number of matches. Provide collegeId or major; at least one is required.","parameters":[{"name":"collegeId","in":"query","required":false,"description":"College id. Provide collegeId or major; at least one is required.","schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},{"name":"major","in":"query","required":false,"description":"Major name fragment (e.g. 'engineering') or a two-digit CIP family code such as '14' (dotted codes are accepted; families 01-09 may not match). Provide collegeId or major; at least one is required.","schema":{"type":"string","maxLength":80}},{"name":"limit","in":"query","required":false,"description":"1-50, default 25.","schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}],"responses":{"200":{"description":"JSON result plus dataVersion.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input; error.message explains."},"429":{"description":"Rate limited; retry after a minute."}}}},"/v1/programs":{"get":{"operationId":"programs_and_earnings","summary":"Programs and earnings","description":"Degree programs with outcomes. By collegeId: that college's programs, highest median earnings first. By major (name fragment or CIP prefix): colleges offering it, highest median earnings first. Each row has program name, CIP code, degree level (certificate, associate, bachelor, graduate), enrollment share (fraction of the college's completions), median earnings a few years after completion in USD (earningsSource 'scorecard' = College Scorecard field-of-study, 'pseo' = Census PSEO fallback), and median debt. Default degree level is bachelor. `count` is the number of rows returned (capped by limit), not the total number of matches. Provide collegeId or major; at least one is required.","parameters":[{"name":"collegeId","in":"query","required":false,"description":"College id. Provide collegeId or major; at least one is required.","schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},{"name":"major","in":"query","required":false,"description":"Program name fragment (e.g. 'computer') or a two-digit CIP family code such as '11' (dotted codes are accepted; families 01-09 may not match). Provide collegeId or major; at least one is required.","schema":{"type":"string","maxLength":80}},{"name":"degreeLevel","in":"query","required":false,"description":"Default bachelor.","schema":{"type":"string","enum":["certificate","associate","bachelor","graduate"]}},{"name":"limit","in":"query","required":false,"description":"1-50, default 25.","schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}],"responses":{"200":{"description":"JSON result plus dataVersion.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input; error.message explains."},"429":{"description":"Rate limited; retry after a minute."}}}},"/v1/high-school":{"get":{"operationId":"high_school_outcomes","summary":"High school outcomes","description":"For a California high school: California Department of Education college-going outcomes for the most recent graduating cohort (college-going rate as a fraction, counts enrolled at UC, CSU, community college, in-state private, out-of-state), the University of California's source-school admissions for each of the nine UC campuses (applied, admitted, enrolled, admit rate; the UC suppresses counts under three students, which come back as null with suppressed=true, not zero), and any class destination lists Cohort has collected (acceptances and matriculations by college). Pass city when the name is common. Returns candidates instead of guessing when several schools match.","parameters":[{"name":"name","in":"query","required":true,"description":"High school name, e.g. 'Amador Valley'.","schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"city","in":"query","required":false,"description":"City, to disambiguate.","schema":{"type":"string","maxLength":80}}],"responses":{"200":{"description":"JSON result plus dataVersion.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input; error.message explains."},"429":{"description":"Rate limited; retry after a minute."}}}},"/v1/admit-destinations":{"get":{"operationId":"admit_destinations","summary":"Admit destinations and cross-admit pairs","description":"Two views of where admitted students actually enroll. campusId (a UC campus id): the University of California's published list of institutions its admits enrolled at, ranked, with counts and share of all admits as a fraction. pair (two college ids A,B): among students admitted to both, the fraction who chose A (shareChoosingA) with a confidence interval and sample size, source Parchment. Use search_colleges to get ids. Provide campusId or pair; if both are sent, pair wins.","parameters":[{"name":"campusId","in":"query","required":false,"description":"UC campus college id, e.g. 110635 for UC Berkeley. Provide campusId or pair; if both are sent, pair wins.","schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},{"name":"pair","in":"query","required":false,"description":"Two college ids, A then B. REST accepts 'idA,idB'. Provide campusId or pair; if both are sent, pair wins.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false}],"responses":{"200":{"description":"JSON result plus dataVersion.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input; error.message explains."},"429":{"description":"Rate limited; retry after a minute."}}}},"/v1/essays":{"get":{"operationId":"essay_prompts","summary":"Essay prompts","description":"Supplemental essay prompts for one college, newest application cycle only (e.g. '2026-27'): prompt text, word limit, whether it is required, and the cycle. Prompts are quoted from the college's own application pages and attributed; always cite the college and link its website when you show them. An empty list means Cohort has no prompts on file for that college, not that it has no essays.","parameters":[{"name":"collegeId","in":"query","required":true,"description":"College id from search_colleges.","schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}],"responses":{"200":{"description":"JSON result plus dataVersion.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input; error.message explains."},"429":{"description":"Rate limited; retry after a minute."}}}},"/v1/methodology":{"get":{"operationId":"methodology","summary":"Data sources, units and limits","description":"Markdown describing every dataset, its source and cycle, units (rates are fractions 0-1), and suppression rules. Read once before interpreting numbers.","parameters":[],"responses":{"200":{"description":"Markdown text.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}}}}