Endpoints
OpenDecisions v1 API endpoints, query parameters and response shapes
Endpoints
Conventions
- Field names: All request and response JSON use snake_case (e.g.
institution_id,updated_at,computed_from). The published schema uses camelCase in JSON-LD; the REST API uses snake_case for consistency. - Pagination: List endpoints support
limit(default 20, max 100) andoffset. Response shape:{ items: T[], total: number, limit: number, offset: number }. - Provenance: Every entity response includes
provenance: { sources: string[], updated_at: string | null }. UseGET /v1/sources/{source_id}to resolve source IDs to full Source metadata ("no source, no claim").
Get-by-ID: stable IDs vs internal UUIDs
- Stable string IDs (use in path):
institution_id,program_id,index_id,source_id. Example:GET /v1/institutions/inst:us:ipeds:166027,GET /v1/derived-indexes/index:inst:us:ipeds:166027:public:v1. - Internal UUIDs (returned in list, use in path for single-resource get):
admission_cycle_id,cost_profile_id,outcome_stats_id,cohort_stats_id,program_funding_id,program_outcomes_id. List the resource (e.g. withinstitution_idorprogram_idfilter), then use the UUID from the list response for the get-by-id path.
Institutions
| Method | Path | Description |
|---|---|---|
| GET | /v1/institutions | Paginated list of institutions. |
| GET | /v1/institutions/{institution_id} | Single institution by stable ID (e.g. inst:us:ipeds:166027). |
List query parameters: country, limit, offset.
Response: Institution object(s) with provenance (sources, updated_at). Field names snake_case.
Programs
| Method | Path | Description |
|---|---|---|
| GET | /v1/programs | Paginated list of programs. |
| GET | /v1/programs/{program_id} | Single program by stable program ID. |
List query parameters: institution_id, country, limit, offset.
Response: Program object(s) with provenance. Field names snake_case.
Program funding (cost & scholarships)
Program-level estimated cost and scholarships, critical for learners comparing programs.
| Method | Path | Description |
|---|---|---|
| GET | /v1/program-funding | Paginated list of program funding records. |
| GET | /v1/program-funding/{program_funding_id} | Single program funding by internal UUID (from list). |
List query parameters: program_id, limit, offset.
Response: ProgramFunding (program_id, estimated_cost_json, scholarships_json, valid_from, valid_to, provenance). Get-by-id uses UUID.
Program outcomes (earnings, debt, completion)
Program-level completion, median earnings, debt, and repayment, critical for learners.
| Method | Path | Description |
|---|---|---|
| GET | /v1/program-outcomes | Paginated list of program outcomes. |
| GET | /v1/program-outcomes/{program_outcomes_id} | Single program outcomes by internal UUID (from list). |
List query parameters: program_id, limit, offset.
Response: ProgramOutcomes (program_id, completion_rate, median_earnings, outcomes_json, measurement_basis, provenance). Get-by-id uses UUID.
Admission cycles
| Method | Path | Description |
|---|---|---|
| GET | /v1/admission-cycles | Paginated list of admission cycles. |
| GET | /v1/admission-cycles/{admission_cycle_id} | Single admission cycle by internal UUID (from list). |
List query parameters: institution_id, limit, offset.
Response: AdmissionCycle (cycle_id, institution_id, counts, test_scores, policies, provenance). Get-by-id uses UUID, not cycle_id.
Cost profiles
| Method | Path | Description |
|---|---|---|
| GET | /v1/cost-profiles | Paginated list of cost profiles. |
| GET | /v1/cost-profiles/{cost_profile_id} | Single cost profile by internal UUID (from list). |
Response: CostProfile (sticker_price, net_price, financial_aid, debt, provenance). Get-by-id uses UUID.
Outcome stats
| Method | Path | Description |
|---|---|---|
| GET | /v1/outcome-stats | Paginated list of outcome stats. |
| GET | /v1/outcome-stats/{outcome_stats_id} | Single outcome stats by internal UUID (from list). |
Response: OutcomeStats (completion, retention, earnings, repayment, provenance). Get-by-id uses UUID.
Cohort stats
| Method | Path | Description |
|---|---|---|
| GET | /v1/cohort-stats | Paginated list of cohort stats. |
| GET | /v1/cohort-stats/{cohort_stats_id} | Single cohort stats by internal UUID (from list). |
Response: CohortStats (student_body, regional_context, federal_aid, provenance). Get-by-id uses UUID.
Derived indexes
| Method | Path | Description |
|---|---|---|
| GET | /v1/derived-indexes | Paginated list of derived index sets. |
| GET | /v1/derived-indexes/{index_id} | Single derived index by stable index_id. |
List query parameters: institution_id, program_id, limit, offset.
Response: DerivedIndex (index_id, indexes_json, profiled_indexes_json, provenance, computed_from: source IDs used to compute this index).
Sources
| Method | Path | Description |
|---|---|---|
| GET | /v1/sources | Paginated list of sources. |
| GET | /v1/sources/{source_id} | Single source by stable source_id. |
List query parameters: country, limit, offset.
Response: Source (source_id, publisher, title, source_url, valid_for_year, coverage, etc.). Resolve provenance.sources from entity responses here.
For exact request/response schemas and status codes, use the running API's OpenAPI spec: GET /openapi.json or GET /api-docs (Swagger UI).