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 grade value (e.g. 4.0). null for non-numeric grades
textScore	string	Grade as text — see textScore values
scoreDate	date	Date the grade was recorded (YYYY-MM-DD)
comment	string	Optional comment from the teacher

textScore values

For numeric grades, textScore contains the number as a string (e.g. "4"). For non-numeric grades, the following values are used:

textScore	Meaning
IV	Ikke vurdert — no basis for assessment
F	Fritatt — exempt from assessment
IM	Ikke møtt — student did not show up
D	Deltatt — participated (used for vocational subjects)
--	No grade recorded

{
  "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": 4.0,
  "textScore": "4",
  "scoreDate": "2026-01-28",
  "comment": null
}

LineItem

A LineItem represents a grading context for a subject group — one per term for halvårsvurdering, and one for standpunktkarakter or eksamenskarakter.

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	Subject variant name, or fagkode if no name is available
description	string	Optional description
class	GUIDRef	Reference to the subject group (class)
school	GUIDRef	Reference to the school (org)
gradingPeriod	GUIDRef	Reference to the academic session (term)
scoreScale	GUIDRef	Optional reference to a score scale
resultValueMin	number	Minimum numeric grade value
resultValueMax	number	Maximum numeric grade value
metadata	object	OnEdHub-specific fields — see LineItem metadata

LineItem metadata

Norwegian-specific fields are exposed under metadata:

Key	Type	Description
onedhub.type	string	Grade type — see Grade types
onedhub.subjectCode	string	Norwegian fagkode (e.g. NOR1211)
onedhub.isWritten	boolean	Whether this is a written subject variant
onedhub.isFirstLanguage	boolean	Whether this is the first-language variant
onedhub.examForm	string	Exam form — S (skriftlig), M (muntlig), or MP (muntlig-praktisk). Only set when onedhub.type is EK

Grade types

The onedhub.type field identifies what kind of grade the line item represents:

Value	Description
H1	Halvårsvurdering — half-year assessment midway through the school year
H2	Halvårsvurdering — half-year assessment at the end of the school year
ST	Standpunktkarakter — final standing grade
EK	Eksamenskarakter — exam grade

Values for H1, H2, and ST follow Vigo's B13 Karaktertermin codes. EK is kept distinct rather than collapsed into ST so consumers can read exam vs. standing grades directly from onedhub.type without joining on onedhub.examForm.

{
  "sourcedId": "123:550e8400-e29b-41d4-a716-446655440000:a3bb189e-8bf9-3888-9912-ace4e6543002:10:NOR1211:2",
  "status": "active",
  "dateLastModified": "2026-01-15T08:30:00Z",
  "title": "Norsk",
  "class": {
    "sourcedId": "123",
    "type": "class",
    "href": "https://api.onedhub.io/vigilo.no/ims/oneroster/rostering/v1p2/classes/123"
  },
  "school": {
    "sourcedId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "org",
    "href": "https://api.onedhub.io/vigilo.no/ims/oneroster/rostering/v1p2/orgs/550e8400-e29b-41d4-a716-446655440000"
  },
  "gradingPeriod": {
    "sourcedId": "term-001",
    "type": "academicSession",
    "href": "https://api.onedhub.io/vigilo.no/ims/oneroster/rostering/v1p2/academicSessions/term-001"
  },
  "metadata": {
    "onedhub.type": "H1",
    "onedhub.subjectCode": "NOR1211",
    "onedhub.isWritten": true,
    "onedhub.isFirstLanguage": true
  }
}

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=class.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"