OneRoster API
Roster and course management
Overview
OneRoster manages the structure of your educational app: courses, units, lessons, student enrollments, and grades.
It provides three core services:
- Rostering (who's in what course)
- Gradebook (scores and results)
- Resources (learning materials)
Think of it as the organizational backbone, defining what content exists, who has access, and how students are performing.
External Documentation
| Resource | Link |
|---|---|
| Official API Docs | OneRoster API Docs |
| Specification | 1EdTech OneRoster v1.2 |
Key Concepts
| Concept | Description |
|---|---|
| Course | The top-level container for educational content (e.g. "Education App: Grade 5") |
| Component | A unit, module, or lesson within a course: components can be nested |
| Resource | The actual learning material: videos, articles, quizzes, or assessments |
| Enrollment | Links a student to a course, controlling what content they can access |
Common Use Cases
- Build course structures: Organize content into courses, units, and lessons
- Manage student rosters: Enroll students and control access to grade-specific content
- Query enrollments: Check which courses a student is enrolled in
Essential Endpoints
| Endpoint | Purpose |
|---|---|
POST /courses | Create a new course |
POST /courses/components | Add units, modules, or lessons to a course |
POST /courses/component-resources | Attach learning materials to components |
POST /enrollments | Enroll a student in a course |
GET /enrollments | Query student enrollments |
Examples
Create a Course
Request
curl -X POST $TIMEBACK_API_URL/ims/oneroster/rostering/v1p2/courses \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "course": { "sourcedId": "math-grade-5", "status": "active", "title": "Math Grade 5", "courseCode": "MATH-G5", "grades": ["05"], "subjects": ["Math"], "org": { "sourcedId": "PLAYCADEMY" } } }'const response = await fetch(`${TIMEBACK_API_URL}/ims/oneroster/rostering/v1p2/courses`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ course: { sourcedId: 'math-grade-5', status: 'active', title: 'Math Grade 5', courseCode: 'MATH-G5', grades: ['05'], subjects: ['Math'], org: { sourcedId: 'PLAYCADEMY' }, }, }),})Get Student Enrollments
Request
curl "$TIMEBACK_API_URL/ims/oneroster/rostering/v1p2/enrollments?filter=user.sourcedId%3D%27student-123%27" \ -H "Authorization: Bearer $ACCESS_TOKEN"const enrollments = await fetch( `${TIMEBACK_API_URL}/ims/oneroster/rostering/v1p2/enrollments?filter=user.sourcedId='student-123'`, { headers: { Authorization: `Bearer ${accessToken}`, }, },)