Semestra

Grades and GPA

List a course's assessments with deadline, weight and score.

GET
/courses/{course_id}/assessments

Use to see what is graded or still pending in a course. To locate one assessment the user named in words ("Lab 3", "the midterm"), prefer grading.assessment.find.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

course_id*Course Id

Course id

Query Parameters

status?|

graded, or pending (no score yet)

fields?array<>|

Agent/MCP only: return just these fields of each assessment (and its id)

cursor?|

next_cursor of the previous page

limit?Limit

Page size

Default200

Response Body

Successful Response

application/json
  1. response
items*array<>
next_cursor*string|null
Example Request
curl -X GET 'https://example.com/courses/string/assessments'
Example Response
{  "items": [    {      "id": "string",      "course_id": "string",      "category_id": "string",      "title": "string",      "due_at": "2019-08-24T14:15:22Z",      "due_has_time": true,      "due_date": "2019-08-24",      "due_time": "14:15:22Z",      "weight": 0,      "score_percentage": 0,      "points_earned": 0,      "points_possible": 0,      "dropped": true,      "note": "string",      "source_kind": "lms",      "source_ref": "string",      "position": 0,      "status": "graded",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string"}

Add an assessment (quiz, exam, assignment...) to a course gradebook.

POST
/courses/{course_id}/assessments

Use when the user adds a graded item. Give the deadline as due_date (and due_time if known) in the Program's time zone. Do not use to record a score on an existing assessment; use grading.assessment.update.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

course_id*Course Id

Course id

Request Body

application/json
  1. body
title*Title

Assessment title, e.g. 'Midterm 1'

Length1 <= length <= 200
category_id?|

Category id

due_at?|

Exact deadline with time zone; wins over due_date/due_time

due_date?|

Deadline date in the Program's time zone

due_time?|

Deadline time in the Program's time zone; without it the deadline is the end of due_date and only the date is shown

weight?Weight

Share of the course grade in percent

Range0 <= value <= 100
Default0
score_percentage?|

Score in percent; leave empty until it is graded

points_earned?|

Points earned, e.g. 18 of 20; sets the percentage

points_possible?|

Points possible

dropped?Dropped

Ignored in every calculation (e.g. lowest quiz dropped)

Defaultfalse
note?|

Free-form note

source_kind?|

Where an imported item came from; used to skip duplicates

source_ref?|

Id of the item in its source, used with source_kind

Response Body

Successful Response

application/json
  1. response
id*Id
course_id*Course Id
category_id*string|null
title*Title
due_at*|

Deadline (UTC)

due_has_time*Due Has Time

False when only the date is known

due_date*|

Deadline date in the Program's time zone

due_time*|

Deadline time in the Program's time zone

weight*Weight
score_percentage*number|null
points_earned*number|null
points_possible*number|null
dropped*Dropped
note*string|null
source_kind*|null
source_ref*string|null
position*Position
status*Status
Value in"graded""pending"
created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X POST 'https://example.com/courses/string/assessments' \  -H 'Content-Type: application/json' \  -d '{  "title": "string"}'
Example Response
{  "id": "string",  "course_id": "string",  "category_id": "string",  "title": "string",  "due_at": "2019-08-24T14:15:22Z",  "due_has_time": true,  "due_date": "2019-08-24",  "due_time": "14:15:22Z",  "weight": 0,  "score_percentage": 0,  "points_earned": 0,  "points_possible": 0,  "dropped": true,  "note": "string",  "source_kind": "lms",  "source_ref": "string",  "position": 0,  "status": "graded",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Add one or more assessments (quiz, exam, assignment...) to a course gradebook.

POST
/courses/{course_id}/assessments:batch

Use when the user adds graded items in the chat, one or several. Give each deadline as due_date (and due_time if known) in the Program's time zone. Do not use to record a score on an existing assessment; use grading.assessment.update. A grading scheme in a file goes through imports.session.create, and LMS assignments through lms.assignment.import. Items that carry source_kind and source_ref are skipped when the course already has an assessment from the same source, so repeating an import creates no duplicates.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

course_id*Course Id

Course id

Request Body

application/json
  1. body
assessments*array<>

Assessments to add

Items1 <= items <= 200

Response Body

Successful Response

application/json
  1. response
created*array<>
skipped*array<>

Items left out because the course already has one from the same source

Example Request
curl -X POST 'https://example.com/courses/string/assessments:batch' \  -H 'Content-Type: application/json' \  -d '{  "assessments": [    {      "title": "string"    }  ]}'
Example Response
{  "created": [    {      "id": "string",      "course_id": "string",      "category_id": "string",      "title": "string",      "due_at": "2019-08-24T14:15:22Z",      "due_has_time": true,      "due_date": "2019-08-24",      "due_time": "14:15:22Z",      "weight": 0,      "score_percentage": 0,      "points_earned": 0,      "points_possible": 0,      "dropped": true,      "note": "string",      "source_kind": "lms",      "source_ref": "string",      "position": 0,      "status": "graded",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "skipped": [    {      "source_kind": "lms",      "source_ref": "string",      "assessment_id": "string"    }  ]}

Change an assessment, mainly to record its score.

PATCH
/assessments/{assessment_id}

Record a score with score_percentage (82), or points_earned with points_possible (18 of 20). Send null to clear the score again. Also changes title, category, deadline, weight, dropped (ignore it in every calculation) and note. Only the fields that are sent change.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

assessment_id*Assessment Id

Assessment id

Request Body

application/json
  1. body
title?|

Title

category_id?|

Category id, or null for none

due_at?|

Exact deadline, or null to clear

due_date?|

Deadline date, or null to clear

due_time?|

Deadline time, or null for date only

weight?|

Share of the course in percent

score_percentage?|

Score in percent, or null

points_earned?|

Points earned, or null

points_possible?|

Points possible, or null

dropped?|

Ignored in every calculation

note?|

Note, or null to clear

Response Body

Successful Response

application/json
  1. response
id*Id
course_id*Course Id
category_id*string|null
title*Title
due_at*|

Deadline (UTC)

due_has_time*Due Has Time

False when only the date is known

due_date*|

Deadline date in the Program's time zone

due_time*|

Deadline time in the Program's time zone

weight*Weight
score_percentage*number|null
points_earned*number|null
points_possible*number|null
dropped*Dropped
note*string|null
source_kind*|null
source_ref*string|null
position*Position
status*Status
Value in"graded""pending"
created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X PATCH 'https://example.com/assessments/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "course_id": "string",  "category_id": "string",  "title": "string",  "due_at": "2019-08-24T14:15:22Z",  "due_has_time": true,  "due_date": "2019-08-24",  "due_time": "14:15:22Z",  "weight": 0,  "score_percentage": 0,  "points_earned": 0,  "points_possible": 0,  "dropped": true,  "note": "string",  "source_kind": "lms",  "source_ref": "string",  "position": 0,  "status": "graded",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Delete an assessment from a gradebook.

DELETE
/assessments/{assessment_id}

Irreversible: the score and its place in the grade are gone. To ignore an assessment in the grade, set dropped with grading.assessment.update instead. Find the id with grading.assessment.find.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

assessment_id*Assessment Id

Assessment id

Response Body

Successful Response

application/json
  1. response
deleted?Deleted
Defaulttrue
Example Request
curl -X DELETE 'https://example.com/assessments/string'
Example Response
{  "deleted": true}

Set the order of a course's assessments.

PUT
/courses/{course_id}/assessment-order

Assessments not listed keep their order after the listed ones.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

course_id*Course Id

Course id

Request Body

application/json
  1. body
assessment_ids*array<>

Assessment ids in order

Itemsitems <= 500

Response Body

Successful Response

application/json
  1. response
course_id*Course Id
assessment_ids*array<string>
Example Request
curl -X PUT 'https://example.com/courses/string/assessment-order' \  -H 'Content-Type: application/json' \  -d '{  "assessment_ids": [    "string"  ]}'
Example Response
{  "course_id": "string",  "assessment_ids": [    "string"  ]}

Ungraded assessments with a deadline, soonest first, for a Program, term or course.

GET
/programs/{program_id}/upcoming-assessments

Use for "what is due next". Overdue ones come first; graded and dropped ones are left out.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Query Parameters

term_id?|

Only the courses of this term

course_id?|

Only this course

limit?Limit

Max assessments

Default10

Response Body

Successful Response

application/json
  1. response
items*array<>

Ungraded, with a deadline, soonest first

Example Request
curl -X GET 'https://example.com/programs/string/upcoming-assessments'
Example Response
{  "items": [    {      "id": "string",      "course_id": "string",      "category_id": "string",      "title": "string",      "due_at": "2019-08-24T14:15:22Z",      "due_has_time": true,      "due_date": "2019-08-24",      "due_time": "14:15:22Z",      "weight": 0,      "score_percentage": 0,      "points_earned": 0,      "points_possible": 0,      "dropped": true,      "note": "string",      "source_kind": "lms",      "source_ref": "string",      "position": 0,      "status": "graded",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ]}

Add an assessment category (e.g. 'Midterm') to a course's gradebook.

POST
/courses/{course_id}/grading-categories

Use when the syllabus has a kind of assessment the built-in categories lack.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

course_id*Course Id

Course id

Request Body

application/json
  1. body
name*Name

Category name, e.g. 'Midterm'

Length1 <= length <= 200
color?Color

Color name or #rrggbb

Match^(blue|amber|emerald|violet|cyan|rose|slate|#[0-9a-fA-F]{6})$
Default"slate"
key?|

Stable key; derived from the name when omitted

Response Body

Successful Response

application/json
  1. response
id*Id
course_id*Course Id
key*Key
name*Name
color*Color
position*Position
archived*Archived
Example Request
curl -X POST 'https://example.com/courses/string/grading-categories' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
Example Response
{  "id": "string",  "course_id": "string",  "key": "string",  "name": "string",  "color": "string",  "position": 0,  "archived": true}

Rename, recolor or archive an assessment category.

PATCH
/grading-categories/{category_id}

Partial update. Archived categories keep their assessments but leave the pickers.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

category_id*Category Id

Category id

Request Body

application/json
  1. body
name?|

New name

color?|

New color

archived?|

Archived categories are hidden from pickers

Response Body

Successful Response

application/json
  1. response
id*Id
course_id*Course Id
key*Key
name*Name
color*Color
position*Position
archived*Archived
Example Request
curl -X PATCH 'https://example.com/grading-categories/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "course_id": "string",  "key": "string",  "name": "string",  "color": "string",  "position": 0,  "archived": true}

Delete an assessment category; its assessments become uncategorised.

DELETE
/grading-categories/{category_id}

Irreversible, but no assessment is deleted. Prefer archiving.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

category_id*Category Id

Category id

Response Body

Successful Response

application/json
  1. response
deleted?Deleted
Defaulttrue
Example Request
curl -X DELETE 'https://example.com/grading-categories/string'
Example Response
{  "deleted": true}

Set the display order of a course's assessment categories.

PUT
/courses/{course_id}/grading-category-order

Categories not listed keep their order after the listed ones.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

course_id*Course Id

Course id

Request Body

application/json
  1. body
category_ids*array<>

Category ids in display order

Itemsitems <= 50

Response Body

Successful Response

application/json
  1. response
items*array<>
Example Request
curl -X PUT 'https://example.com/courses/string/grading-category-order' \  -H 'Content-Type: application/json' \  -d '{  "category_ids": [    "string"  ]}'
Example Response
{  "items": [    {      "id": "string",      "course_id": "string",      "key": "string",      "name": "string",      "color": "string",      "position": 0,      "archived": true    }  ]}

Change how a course is graded: official final grade, target, pass/fail, forecast.

PATCH
/courses/{course_id}/grade

Use to enter the official final grade (final_override_percentage, which wins over the calculated one; null clears it), set the target in grade points, switch a course to pass/fail, or enter a final grade for a course without a gradebook (manual_percentage with gradebook_enabled: false). To record the score of one assessment use grading.assessment.update.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

course_id*Course Id

Course id

Request Body

application/json
  1. body
basis?|

'pass_fail' courses have no GPA

manual_percentage?|

Final grade of a course without a gradebook, or null

final_override_percentage?|

Official final grade; wins over the calculated one. Null clears

pass_fail_result?|

Result of a pass/fail course, or null while unknown

target_points?|

Goal in grade points, or null for the scale's maximum

forecast_model?|

Forecast model

gradebook_enabled?|

False when only a final grade is entered for the course

Response Body

Successful Response

application/json
  1. response
course_id*Course Id
basis*Basis
Value in"percentage""pass_fail"
manual_percentage*number|null
final_override_percentage*number|null
pass_fail_result*|null
target_points*|

Chosen goal; the scale's top points if null

forecast_model*Forecast Model
Value in"auto""simple_minimum_needed"
gradebook_enabled*Gradebook Enabled
updated_at*Updated At
Formatdate-time
Example Request
curl -X PATCH 'https://example.com/courses/string/grade' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "course_id": "string",  "basis": "percentage",  "manual_percentage": 0,  "final_override_percentage": 0,  "pass_fail_result": "pass",  "target_points": 0,  "forecast_model": "auto",  "gradebook_enabled": true,  "updated_at": "2019-08-24T14:15:22Z"}

The grade, grade points and status of every course in a Program.

GET
/programs/{program_id}/course-grades

Use to compare courses or list which are finished, in progress or pass/fail.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Query Parameters

include_in_progress?Include In Progress

Count the current average of unfinished courses

Defaultfalse

Response Body

Successful Response

application/json
  1. response
program_id*Program Id
max_points*Max Points
hide_gpa*Hide Gpa
items*array<>
Example Request
curl -X GET 'https://example.com/programs/string/course-grades'
Example Response
{  "program_id": "string",  "max_points": 0,  "hide_gpa": true,  "items": [    {      "course_id": "string",      "code": "string",      "title": "string",      "alias": "string",      "credits": 0,      "include_in_gpa": true,      "basis": "percentage",      "status": "completed",      "percentage": 0,      "current_percentage": 0,      "points": 0,      "letter": "string",      "counts_in_gpa": true,      "year_long": true,      "attributed_credits": 0    }  ]}

A course's gradebook: categories, assessments, and every calculated figure.

GET
/courses/{course_id}/gradebook

Use to answer questions about a course's grade: the current average, the final grade, the forecast, or what the remaining assessments must average to reach a target grade (summary.required_average). The summary figures are null while the weights do not add up to 100 (summary.weight_gap says how much is missing). Never calculate grades yourself.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

course_id*Course Id

Course id

Response Body

Successful Response

application/json
  1. response
course_id*Course Id
program_id*Program Id
scale*
result*
categories*array<>
assessments*array<>
summary*

Every figure of M03 §3 for one course; null where it cannot be calculated.

Example Request
curl -X GET 'https://example.com/courses/string/gradebook'
Example Response
{  "course_id": "string",  "program_id": "string",  "scale": {    "max_points": 0,    "hide_gpa": true,    "round_before_lookup": true  },  "result": {    "course_id": "string",    "basis": "percentage",    "manual_percentage": 0,    "final_override_percentage": 0,    "pass_fail_result": "pass",    "target_points": 0,    "forecast_model": "auto",    "gradebook_enabled": true,    "updated_at": "2019-08-24T14:15:22Z"  },  "categories": [    {      "id": "string",      "course_id": "string",      "key": "string",      "name": "string",      "color": "string",      "position": 0,      "archived": true    }  ],  "assessments": [    {      "id": "string",      "course_id": "string",      "category_id": "string",      "title": "string",      "due_at": "2019-08-24T14:15:22Z",      "due_has_time": true,      "due_date": "2019-08-24",      "due_time": "14:15:22Z",      "weight": 0,      "score_percentage": 0,      "points_earned": 0,      "points_possible": 0,      "dropped": true,      "note": "string",      "source_kind": "lms",      "source_ref": "string",      "position": 0,      "status": "graded",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "summary": {    "status": "completed",    "weight_total": 0,    "weight_gap": 0,    "weights_ok": true,    "graded_count": 0,    "remaining_count": 0,    "graded_weight": 0,    "remaining_weight": 0,    "locked_contribution": 0,    "current_percentage": 0,    "current_points": 0,    "current_letter": "string",    "final_percentage": 0,    "final_points": 0,    "final_letter": "string",    "final_source": "override",    "overridden": true,    "forecast_percentage": 0,    "forecast_points": 0,    "forecast_letter": "string",    "predictions": {      "property1": 0,      "property2": 0    },    "missing_history_category_ids": [      "string"    ],    "target_points": 0,    "target_percentage": 0,    "required_average": 0,    "reachable": true,    "categories": [      {        "category_id": "string",        "weight": 0,        "graded_weight": 0,        "average": 0,        "contribution": 0      }    ]  }}

Get a Program's grading scale: percentage ranges → grade points and letters.

GET
/programs/{program_id}/grading-scale

Use to convert a percentage to grade points or a letter, or to read the Program's grading defaults (how year-long courses count, default categories, hidden GPA).

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Response Body

Successful Response

application/json
  1. response
program_id*Program Id
bands*array<>

Highest percentage first

max_points*Max Points

Points of a perfect grade, e.g. 4.0

year_course_attribution*Year Course Attribution

Which term a year-long course's grade counts in

Value in"end_term""split_evenly"
default_forecast_model*Default Forecast Model
Value in"auto""simple_minimum_needed"
default_categories*array<>

Categories every new course of the Program starts with

hide_gpa*Hide Gpa
round_before_lookup*Round Before Lookup

Percentages are rounded to whole numbers (half up) before the band lookup

updated_at*Updated At
Formatdate-time
Example Request
curl -X GET 'https://example.com/programs/string/grading-scale'
Example Response
{  "program_id": "string",  "bands": [    {      "min": 0,      "max": 0,      "points": 0,      "letter": "string"    }  ],  "max_points": 0,  "year_course_attribution": "end_term",  "default_forecast_model": "auto",  "default_categories": [    {      "key": "string",      "name": "string",      "color": "string"    }  ],  "hide_gpa": true,  "round_before_lookup": true,  "updated_at": "2019-08-24T14:15:22Z"}

Change a Program's grading scale or grading defaults.

PUT
/programs/{program_id}/grading-scale

Partial update: only the fields that are sent change. bands replaces the whole table; the ranges must not overlap and must reach from 0 to 100, with points of at most max_points. Every GPA of the Program is recalculated from the new scale.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Request Body

application/json
  1. body
bands?array<>|

The percentage → points table; must cover 0-100 without overlapping

max_points?|

Points of a perfect grade

year_course_attribution?|

'end_term' counts a year-long course once in its last term

default_forecast_model?|

Forecast model new courses start with

default_categories?array<>|

Category template for new courses

hide_gpa?|

Mask GPA figures in the interface

round_before_lookup?|

Round percentages to whole numbers before reading the scale (84.6 → 85)

Response Body

Successful Response

application/json
  1. response
program_id*Program Id
bands*array<>

Highest percentage first

max_points*Max Points

Points of a perfect grade, e.g. 4.0

year_course_attribution*Year Course Attribution

Which term a year-long course's grade counts in

Value in"end_term""split_evenly"
default_forecast_model*Default Forecast Model
Value in"auto""simple_minimum_needed"
default_categories*array<>

Categories every new course of the Program starts with

hide_gpa*Hide Gpa
round_before_lookup*Round Before Lookup

Percentages are rounded to whole numbers (half up) before the band lookup

updated_at*Updated At
Formatdate-time
Example Request
curl -X PUT 'https://example.com/programs/string/grading-scale' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "program_id": "string",  "bands": [    {      "min": 0,      "max": 0,      "points": 0,      "letter": "string"    }  ],  "max_points": 0,  "year_course_attribution": "end_term",  "default_forecast_model": "auto",  "default_categories": [    {      "key": "string",      "name": "string",      "color": "string"    }  ],  "hide_gpa": true,  "round_before_lookup": true,  "updated_at": "2019-08-24T14:15:22Z"}

List the built-in grading scales (UofT 4.0, US 4.0 and 4.33, standard 4.0, China 100-point, Australia 7-point, Korea 4.5, custom).

GET
/grading/scale-presets

Use to offer ready-made scales; apply one with grading.scale.update.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Response Body

Successful Response

application/json
  1. response
items*array<>
Example Request
curl -X GET 'https://example.com/grading/scale-presets'
Example Response
{  "items": [    {      "id": "string",      "max_points": 0,      "bands": [        {          "min": 0,          "max": 0,          "points": 0,          "letter": "string"        }      ]    }  ]}

Suggest a score for every ungraded assessment that reaches the target grade.

POST
/courses/{course_id}/gradebook:suggest

Scores follow the student's results so far in each category and land exactly on the target. Used to auto-fill a what-if plan. Fails with grading.weights_not_100 while the weights do not add up.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

course_id*Course Id

Course id

Request Body

application/json
  1. body
target?|

Goal; the course's own target when omitted

Response Body

Successful Response

application/json
  1. response
items*array<>
target_percentage*number|null
resulting_percentage*Resulting Percentage
reachable*Reachable
Example Request
curl -X POST 'https://example.com/courses/string/gradebook:suggest' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "items": [    {      "assessment_id": "string",      "score": 0    }  ],  "target_percentage": 0,  "resulting_percentage": 0,  "reachable": true}

What-if: the course figures if ungraded assessments scored the given marks.

POST
/courses/{course_id}/gradebook:simulate

Use to answer "what if I get 80 on the final". Nothing is saved: never change real scores to simulate. Scores it could not use (already graded, not of this course) come back in ignored. Fails with grading.weights_not_100 while the weights do not add up.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

course_id*Course Id

Course id

Request Body

application/json
  1. body
scores?

Assumed score in percent per ungraded assessment id; nothing is saved

target?|

Goal; the course's own target when omitted

Response Body

Successful Response

application/json
  1. response
status*Status
Value in"completed""in_progress""passed""failed"
weight_total*Weight Total
weight_gap*Weight Gap

100 - weight_total; positive means weight is missing

weights_ok*Weights Ok

False: the weights do not add up to 100, so no figures

graded_count*Graded Count
remaining_count*Remaining Count
graded_weight*Graded Weight
remaining_weight*Remaining Weight
locked_contribution*|

The final grade if everything still to come scored 0

current_percentage*|

Weighted average of the graded items

current_points*number|null
current_letter*string|null
final_percentage*|

Official or fully calculated final grade, null while the course is running

final_points*number|null
final_letter*string|null
final_source*|null
overridden*Overridden
forecast_percentage*|

Predicted final grade ('auto' model)

forecast_points*number|null
forecast_letter*string|null
predictions*

Predicted score per ungraded assessment id

missing_history_category_ids*array<string|null>

Categories of ungraded items predicted from the course average

target_points*Target Points
target_percentage*|

Lowest percentage reaching the target

required_average*|

Average the remaining items need to reach the target

reachable*|

False when the target needs more than 100%

categories*array<>

Per category; in a simulation assumed scores count as scores

ignored*array<>

Assumed scores that were not used

Example Request
curl -X POST 'https://example.com/courses/string/gradebook:simulate' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "status": "completed",  "weight_total": 0,  "weight_gap": 0,  "weights_ok": true,  "graded_count": 0,  "remaining_count": 0,  "graded_weight": 0,  "remaining_weight": 0,  "locked_contribution": 0,  "current_percentage": 0,  "current_points": 0,  "current_letter": "string",  "final_percentage": 0,  "final_points": 0,  "final_letter": "string",  "final_source": "override",  "overridden": true,  "forecast_percentage": 0,  "forecast_points": 0,  "forecast_letter": "string",  "predictions": {    "property1": 0,    "property2": 0  },  "missing_history_category_ids": [    "string"  ],  "target_points": 0,  "target_percentage": 0,  "required_average": 0,  "reachable": true,  "categories": [    {      "category_id": "string",      "weight": 0,      "graded_weight": 0,      "average": 0,      "contribution": 0    }  ],  "ignored": [    {      "id": "string",      "reason": "graded"    }  ]}

What-if for a term: the term GPA if unfinished courses ended with given marks.

POST
/terms/{term_id}/grade-summary:simulate

Pass assumed final percentages per unfinished course in scores; with target_gpa the result says whether it is reachable and what average the other unfinished courses need. Marks it could not use (finished or unknown courses) come back in ignored. Nothing is saved.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

term_id*Term Id

Term id

Request Body

application/json
  1. body
scores?

Assumed final percentage per unfinished course id; nothing is saved

target_gpa?|

Term GPA to aim for

include_in_progress?|

Count the current average of unfinished courses; omitted follows the Program setting (grading.count_in_progress)

Response Body

Successful Response

application/json
  1. response
term_id*Term Id
gpa*number|null
average_percentage*number|null
credits_counted*Credits Counted
target_gpa*number|null
gap*|

target - simulated GPA; positive means short

max_possible_gpa*number|null
reachable*boolean|null
required_percentage*|

One average for the courses left blank that reaches the target

ignored*array<>

Assumed percentages that were not used

Example Request
curl -X POST 'https://example.com/terms/string/grade-summary:simulate' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "term_id": "string",  "gpa": 0,  "average_percentage": 0,  "credits_counted": 0,  "target_gpa": 0,  "gap": 0,  "max_possible_gpa": 0,  "reachable": true,  "required_percentage": 0,  "ignored": [    {      "id": "string",      "reason": "finished"    }  ]}

Cumulative GPA, earned credits, progress to graduation and GPA per term.

GET
/programs/{program_id}/grade-summary

Use for "what is my overall GPA" or "how many credits do I have left". Every course counts once, a year-long one in the term the Program's setting names.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Query Parameters

include_in_progress?Include In Progress

Count the current average of unfinished courses

Defaultfalse

Response Body

Successful Response

application/json
  1. response
program_id*Program Id
max_points*Max Points
hide_gpa*Hide Gpa
gpa*number|null
average_percentage*number|null
credits_counted*Credits Counted
credits_earned*Credits Earned
credits_required*number|null
progress*|

credits_earned / credits_required, 0-1

graded_course_count*Graded Course Count
term_count*Term Count
terms*array<>

Chronological, for charts

Example Request
curl -X GET 'https://example.com/programs/string/grade-summary'
Example Response
{  "program_id": "string",  "max_points": 0,  "hide_gpa": true,  "gpa": 0,  "average_percentage": 0,  "credits_counted": 0,  "credits_earned": 0,  "credits_required": 0,  "progress": 0,  "graded_course_count": 0,  "term_count": 0,  "terms": [    {      "term_id": "string",      "name": "string",      "start_date": "2019-08-24",      "gpa": 0,      "cumulative_gpa": 0,      "credits_counted": 0,      "cumulative_credits": 0    }  ]}

A term's GPA, average, credits and every course's grade.

GET
/terms/{term_id}/grade-summary

Use for "what is my GPA this term". Unfinished courses count at their current average when include_in_progress is true; left out, it follows the Program's "count unfinished courses" setting.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

term_id*Term Id

Term id

Query Parameters

include_in_progress?|

Count the current average of unfinished courses; omitted follows the Program setting (grading.count_in_progress)

Response Body

Successful Response

application/json
  1. response
term_id*Term Id
max_points*Max Points
hide_gpa*Hide Gpa
gpa*number|null
average_percentage*number|null
credits_counted*Credits Counted

Credits behind the GPA

credits_total*Credits Total

Credits of all courses landing in the term

credits_earned*Credits Earned
excluded_count*Excluded Count

Finished courses outside the GPA (pass/fail, not counted, no credits)

in_progress_count*In Progress Count

Courses still waiting for their grade

courses*array<>
Example Request
curl -X GET 'https://example.com/terms/string/grade-summary'
Example Response
{  "term_id": "string",  "max_points": 0,  "hide_gpa": true,  "gpa": 0,  "average_percentage": 0,  "credits_counted": 0,  "credits_total": 0,  "credits_earned": 0,  "excluded_count": 0,  "in_progress_count": 0,  "courses": [    {      "course_id": "string",      "code": "string",      "title": "string",      "alias": "string",      "credits": 0,      "include_in_gpa": true,      "basis": "percentage",      "status": "completed",      "percentage": 0,      "current_percentage": 0,      "points": 0,      "letter": "string",      "counts_in_gpa": true,      "year_long": true,      "attributed_credits": 0    }  ]}