API Reference
API reference
OpenDecisions read-only REST API, overview and base URLs
API reference
The OpenDecisions API is a read-only REST API that serves institutions, programs, admission cycles, cost profiles, outcome stats, cohort stats, and derived indexes. All responses conform to the OpenDecisions v1 schema. The API is the programmatic way to access the same decision-relevant data and "nutrition label" indexes described in the Overview.
Base URL and versioning
- Base URL: Your API instance (e.g.
http://localhost:8000or your deployed host). - Version: All documented endpoints are under
/v1/. Schema version isodg/v1.
Authentication
The reference implementation does not require authentication for read endpoints. If you deploy behind an API gateway, configure auth there.
Common behavior
- Content type: Responses are
application/json. - Pagination: List endpoints return
{ items, total, limit, offset }. Use?limit=and?offset=query parameters. - Errors: Standard HTTP status codes; error body may include
detail(string or array of objects).
OpenAPI docs
When the API is running, interactive docs are available:
- Swagger UI:
GET /api-docs - ReDoc:
GET /api-redoc - OpenAPI JSON:
GET /openapi.json
Endpoints overview
| Resource | List | Single |
|---|---|---|
| Institutions | GET /v1/institutions | GET /v1/institutions/{id} |
| Programs | GET /v1/programs | GET /v1/programs/{id} |
| Admission cycles | GET /v1/admission-cycles | GET /v1/admission-cycles/{id} |
| Cost profiles | GET /v1/cost-profiles | GET /v1/cost-profiles/{id} |
| Outcome stats | GET /v1/outcome-stats | GET /v1/outcome-stats/{id} |
| Cohort stats | GET /v1/cohort-stats | GET /v1/cohort-stats/{id} |
| Derived indexes | GET /v1/derived-indexes | GET /v1/derived-indexes/{id} |
Other routes
| Route | Method | Description |
|---|---|---|
/ | GET | API info, version, links to docs and health. |
/health | GET | Liveness/readiness; returns status, schema_version. |
/v1/ | GET | v1 version and schema pointer. |