OneRoster Gradebook v1.2

OneRoster Gradebook provides read-only access to student grades and assignments based on the 1EdTech OneRoster v1.2 standard.

Base URL

https://api.<environment>.onedhub.io/<orgId>/ims/oneroster/gradebook/v1p2/

For more information about environments and URL structure see the environments section.

Open API Specifications

You can find the Open API specifications for the different environments at the following URLs:

https://api.<environment>.onedhub.io/<orgId>/ims/oneroster/gradebook/v1p2/swagger-ui/index.html

Examples:

• https://api.staging.onedhub.io/vigilo.no/ims/oneroster/gradebook/v1p2/swagger-ui/index.html
• https://api.onedhub.io/vigilo.no/ims/oneroster/gradebook/v1p2/swagger-ui/index.html

Authentication

Authentication follows the same OAuth 2.0 client credentials flow as the rest of OnEdHub. See Authentication for details.

The following scopes grant access to the Gradebook API:

Scope	Description
roster.readonly	Full read access to rostering and gradebook data
roster-core.readonly	Read access to core rostering and gradebook data

Endpoints

Results (grades)

Method	Endpoint	Description
GET	/results	Returns all results
GET	/results/{sourcedId}	Returns a single result by sourcedId

Line items (assignments)

Method	Endpoint	Description
GET	/lineItems	Returns all line items
GET	/lineItems/{sourcedId}	Returns a single line item by sourcedId

Assessment line items (coming soon)

Method	Endpoint	Description
GET	/assessmentLineItems	Returns all assessment line items
GET	/assessmentLineItems/{sourcedId}	Returns a single assessment line item by sourcedId

Assessment results (coming soon)

Method	Endpoint	Description
GET	/assessmentResults	Returns all assessment results
GET	/assessmentResults/{sourcedId}	Returns a single assessment result by sourcedId

Query Parameters

All collection endpoints support the following query parameters:

Parameter	Type	Default	Description
limit	integer	100	Maximum number of records to return
offset	integer	0	Number of records to skip before returning results
sort	string	—	Field name to sort by (e.g. dateLastModified)
orderBy	string	asc	Sort direction: asc or desc
filter	string	—	Filter expression (e.g. student.sourcedId='abc')
fields	string	—	Comma-separated list of fields to include in the response

Data Models

Result

A Result represents a student's grade for a specific line item (assignment).

Field	Type	Description
sourcedId	string	Unique identifier for the result
status	string	active or tobedeleted
dateLastModified	datetime	Last modification timestamp (ISO 8601)
lineItem	GUIDRef	Reference to the associated line item
student	GUIDRef	Reference to the student
score	number	Numeric score achieved
textScore	string	Textual representation of the score
scoreDate	date	Date the score was recorded (ISO 8601)
comment	string	Optional comment from the teacher

{
  "sourcedId": "result-001",
  "status": "active",
  "dateLastModified": "2026-02-01T10:00:00Z",
  "lineItem": {
    "sourcedId": "lineitem-001",
    "type": "lineItem",
    "href": "https://api.onedhub.io/vigilo.no/ims/oneroster/gradebook/v1p2/lineItems/lineitem-001"
  },
  "student": {
    "sourcedId": "user-001",
    "type": "user",
    "href": "https://api.onedhub.io/vigilo.no/ims/oneroster/rostering/v1p2/users/user-001"
  },
  "score": 85.0,
  "textScore": "85",
  "scoreDate": "2026-01-28",
  "comment": "Good effort"
}

LineItem

A LineItem represents an assignment or assessment task within a class.

Field	Type	Description
sourcedId	string	Unique identifier for the line item
status	string	active or tobedeleted
dateLastModified	datetime	Last modification timestamp (ISO 8601)
title	string	Name of the assignment
clazz	GUIDRef	Reference to the class this line item belongs to
description	string	Optional description of the assignment
resultValueMin	number	Minimum possible score
resultValueMax	number	Maximum possible score
category	GUIDRef	Reference to the grading category
gradingPeriod	GUIDRef	Reference to the grading period

{
  "sourcedId": "lineitem-001",
  "status": "active",
  "dateLastModified": "2026-01-15T08:30:00Z",
  "title": "Math Test — Chapter 5",
  "clazz": {
    "sourcedId": "class-001",
    "type": "class",
    "href": "https://api.onedhub.io/vigilo.no/ims/oneroster/rostering/v1p2/classes/class-001"
  },
  "description": "Written test covering fractions and decimals",
  "resultValueMin": 0.0,
  "resultValueMax": 100.0,
  "category": {
    "sourcedId": "category-001",
    "type": "category",
    "href": "https://api.onedhub.io/vigilo.no/ims/oneroster/gradebook/v1p2/categories/category-001"
  },
  "gradingPeriod": {
    "sourcedId": "term-001",
    "type": "academicSession",
    "href": "https://api.onedhub.io/vigilo.no/ims/oneroster/rostering/v1p2/academicSessions/term-001"
  }
}

GUIDRef

A GUIDRef is a lightweight reference to another resource. It contains:

Field	Type	Description
sourcedId	string	The unique identifier of the referenced resource
type	string	The resource type (e.g. user, class, lineItem)
href	string	The full URL to retrieve the referenced resource

Common Use Cases

Get all results for a student

curl -H "Authorization: Bearer <token>" \
  "https://api.onedhub.io/<orgId>/ims/oneroster/gradebook/v1p2/results?filter=student.sourcedId%3D'<studentSourcedId>'"

Get all line items for a class

curl -H "Authorization: Bearer <token>" \
  "https://api.onedhub.io/<orgId>/ims/oneroster/gradebook/v1p2/lineItems?filter=clazz.sourcedId%3D'<classSourcedId>'"

Paginate through results

# First page
curl -H "Authorization: Bearer <token>" \
  "https://api.onedhub.io/<orgId>/ims/oneroster/gradebook/v1p2/results?limit=100&offset=0"

# Second page
curl -H "Authorization: Bearer <token>" \
  "https://api.onedhub.io/<orgId>/ims/oneroster/gradebook/v1p2/results?limit=100&offset=100"