API

The app provides an API for external tools to access and process the generated results. This can be used in conjunction with the API from Canvas.

API keys

For access to the API an API Key is required. This key can be requested from the administrator of the app. An API key provides full access to one or more courses similar to the reviewer access and should therefor be kept secret from unauthorised users, like a password.

To use an API key, the key needs to be provided in an HTTP Authorization header on each request, like this:

Authorization: Api-Key 12345678.abcdefghijklmnopqrstuvwxyz

Some endpoints are not available when using the API key authentication. These endpoints are all related to the Canvas app user interface and require an active user to operate.

API documentation

The API is accessible on the /lti/api uri on the app instance. Live documentation of the API is available on the /lti/api-doc uri on the app instance.

The available endpoints are:

GET /account/

List available Canvas accounts

Status Codes
Response JSON Object

  • [].base_url (string) – Base URL of the Canvas account (required)

  • [].canvas_guid (string) – GUID of the Canvas account (required)

  • [].id (integer) – Momotor LTI id for this Canvas account (required)

  • [].name (string) – Display name of the Canvas account

GET /account/{account_pk}/course/

List available courses for this account accounts

Parameters

  • account_pk (string) –

Status Codes
Response JSON Object

  • [].active (boolean) – Momotor processing is active for this course (required)

  • [].canvas_id (integer) – ID of the course (required)

  • [].code (string) – Code of the course as defined in Canvas (required)

  • [].name (string) – Display name of the course as defined in Canvas (required)

GET /account/{account_pk}/course/{canvas_id}/

Get details of a course

Parameters

  • account_pk (string) –

  • canvas_id (string) –

Status Codes
Response JSON Object

  • active (boolean) – Momotor processing is active for this course (required)

  • canvas_id (integer) – ID of the course (required)

  • code (string) – Code of the course as defined in Canvas (required)

  • name (string) – Display name of the course as defined in Canvas (required)

GET /account/{account_pk}/course/{course_canvas_id}/assignment/

List available assignments for this course

Parameters

  • account_pk (string) –

  • course_canvas_id (string) –

Status Codes
Response JSON Object

  • [].canvas_id (number) – (required)

  • [].configfile.name (string) –

  • [].configfile.url (string) –

  • [].name (string) – (required)

  • [].paused (boolean) – (required)

  • [].published (boolean) – (required)

  • [].recipefile.name (string) –

  • [].recipefile.url (string) –

GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/

List all latest results for an assignment, optionally filtered for a single section

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • course_canvas_id (string) –

Query Parameters

  • section (number) – Filter result to only contain given section id

Status Codes
Response JSON Object

  • accepted (boolean) – (required)

  • assignmentId (number) – (required)

  • attempt (number) – (required)

  • has_error (boolean) –

  • is_late (boolean) – (required)

  • is_latest (boolean) – (required)

  • label (string) –

  • processed_at (string) –

  • progress (number) –

  • queued_at (string) –

  • score (number) –

  • secret (boolean) –

  • sections[] (number) –

  • sequence_id (number) – (required)

  • started_at (string) –

  • state (string) – (required)

  • submitted_at (string) – (required)

  • summary (string) –

GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/csv/

Get all results for this assignment in CSV format

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • course_canvas_id (string) –

Status Codes
GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{result_user__canvas_id}/attempt/

List the results of all known attempts of a single user

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • course_canvas_id (string) –

  • result_user__canvas_id (string) –

Status Codes
Response JSON Object

  • accepted (boolean) – (required)

  • assignmentId (number) – (required)

  • attempt (number) – (required)

  • has_error (boolean) –

  • is_late (boolean) – (required)

  • is_latest (boolean) – (required)

  • label (string) –

  • processed_at (string) –

  • progress (number) –

  • queued_at (string) –

  • score (number) –

  • secret (boolean) –

  • sections[] (number) –

  • sequence_id (number) – (required)

  • started_at (string) –

  • state (string) – (required)

  • submitted_at (string) – (required)

  • summary (string) –

GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{result_user__canvas_id}/attempt/{attempt_attempt}/step/{id}/

Get details of a result step

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • attempt_attempt (string) –

  • course_canvas_id (string) –

  • id (string) –

  • result_user__canvas_id (string) –

Status Codes
Response JSON Object

  • accepted (boolean) – (required)

  • has_error (boolean) –

  • id (string) – (required)

  • label (string) –

  • score (number) –

  • secret (boolean) –

  • summary (string) –

GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{result_user__canvas_id}/attempt/{attempt}/

Get details of the result of an attempt of a single user

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • attempt (string) –

  • course_canvas_id (string) –

  • result_user__canvas_id (string) –

Status Codes
Response JSON Object

  • accepted (boolean) – (required)

  • assignmentId (number) – (required)

  • attempt (number) – (required)

  • has_error (boolean) –

  • is_late (boolean) – (required)

  • is_latest (boolean) – (required)

  • label (string) –

  • processed_at (string) –

  • progress (number) –

  • queued_at (string) –

  • score (number) –

  • secret (boolean) –

  • sections[] (number) –

  • sequence_id (number) – (required)

  • started_at (string) –

  • state (string) – (required)

  • steps[].accepted (boolean) – (required)

  • steps[].has_error (boolean) –

  • steps[].id (string) – (required)

  • steps[].label (string) –

  • steps[].score (number) –

  • steps[].secret (boolean) –

  • steps[].summary (string) –

  • submitted_at (string) – (required)

  • summary (string) –

GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{result_user__canvas_id}/attempt/{attempt}/basic_bundle/{path}/

Get a single file from a basic bundle

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • attempt (string) –

  • course_canvas_id (string) –

  • path (string) –

  • result_user__canvas_id (string) –

Status Codes
GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{result_user__canvas_id}/attempt/{attempt}/bundle/{path}/

Get a single file from a bundle. Uses full bundle if available otherwise the basic bundle

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • attempt (string) –

  • course_canvas_id (string) –

  • path (string) –

  • result_user__canvas_id (string) –

Status Codes
GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{result_user__canvas_id}/attempt/{attempt}/full_bundle/{path}/

Get a single file from a full bundle

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • attempt (string) –

  • course_canvas_id (string) –

  • path (string) –

  • result_user__canvas_id (string) –

Status Codes
GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{result_user__canvas_id}/step/{id}/

Get details of a result step

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • course_canvas_id (string) –

  • id (string) –

  • result_user__canvas_id (string) –

Status Codes
Response JSON Object

  • accepted (boolean) – (required)

  • has_error (boolean) –

  • id (string) – (required)

  • label (string) –

  • score (number) –

  • secret (boolean) –

  • summary (string) –

GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{user__canvas_id}/

Get details of the result of the latest attempt of a single user

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • course_canvas_id (string) –

  • user__canvas_id (string) –

Status Codes
Response JSON Object

  • accepted (boolean) – (required)

  • assignmentId (number) – (required)

  • attempt (number) – (required)

  • has_error (boolean) –

  • is_late (boolean) – (required)

  • is_latest (boolean) – (required)

  • label (string) –

  • processed_at (string) –

  • progress (number) –

  • queued_at (string) –

  • score (number) –

  • secret (boolean) –

  • sections[] (number) –

  • sequence_id (number) – (required)

  • started_at (string) –

  • state (string) – (required)

  • steps[].accepted (boolean) – (required)

  • steps[].has_error (boolean) –

  • steps[].id (string) – (required)

  • steps[].label (string) –

  • steps[].score (number) –

  • steps[].secret (boolean) –

  • steps[].summary (string) –

  • submitted_at (string) – (required)

  • summary (string) –

GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{user__canvas_id}/basic_bundle/{path}/

Get a single file from a basic bundle

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • course_canvas_id (string) –

  • path (string) –

  • user__canvas_id (string) –

Status Codes
GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{user__canvas_id}/bundle/{path}/

Get a single file from a bundle. Uses full bundle if available otherwise the basic bundle

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • course_canvas_id (string) –

  • path (string) –

  • user__canvas_id (string) –

Status Codes
GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{user__canvas_id}/full_bundle/{path}/

Get a single file from a full bundle

Parameters

  • account_pk (string) –

  • assignment_canvas_id (string) –

  • course_canvas_id (string) –

  • path (string) –

  • user__canvas_id (string) –

Status Codes
GET /account/{account_pk}/course/{course_canvas_id}/assignment/{canvas_id}/

Get details of an assignment

Parameters

  • account_pk (string) –

  • canvas_id (string) –

  • course_canvas_id (string) –

Status Codes
Response JSON Object

  • canvas_id (number) – (required)

  • configfile.name (string) –

  • configfile.url (string) –

  • name (string) – (required)

  • paused (boolean) – (required)

  • published (boolean) – (required)

  • recipefile.name (string) –

  • recipefile.url (string) –

PUT /account/{account_pk}/course/{course_canvas_id}/assignment/{canvas_id}/

Update details of an assignment

Parameters

  • account_pk (string) –

  • canvas_id (string) –

  • course_canvas_id (string) –

Request JSON Object

  • configfile (file) –

  • evaluate (string) – Following values are valid: - “pp”: Process submissions currently in ‘paused’ state - “all”: Start re-evaluation of all latest submissions - “old”: Start re-evaluation of all latest submissions processed with an older configuration - “[…]”: a json list with result id’s to re-evaluate

  • paused (boolean) –

  • published (boolean) –

  • recipefile (file) –

Status Codes
Response JSON Object

  • canvas_id (number) – (required)

  • configfile.name (string) –

  • configfile.url (string) –

  • name (string) – (required)

  • paused (boolean) – (required)

  • published (boolean) – (required)

  • recipefile.name (string) –

  • recipefile.url (string) –

PATCH /account/{account_pk}/course/{course_canvas_id}/assignment/{canvas_id}/

Update details of an assignment

Parameters

  • account_pk (string) –

  • canvas_id (string) –

  • course_canvas_id (string) –

Request JSON Object

  • configfile (file) –

  • evaluate (string) – Following values are valid: - “pp”: Process submissions currently in ‘paused’ state - “all”: Start re-evaluation of all latest submissions - “old”: Start re-evaluation of all latest submissions processed with an older configuration - “[…]”: a json list with result id’s to re-evaluate

  • paused (boolean) –

  • published (boolean) –

  • recipefile (file) –

Status Codes
Response JSON Object

  • canvas_id (number) – (required)

  • configfile.name (string) –

  • configfile.url (string) –

  • name (string) – (required)

  • paused (boolean) – (required)

  • published (boolean) – (required)

  • recipefile.name (string) –

  • recipefile.url (string) –

POST /account/{account_pk}/course/{course_canvas_id}/assignment/{canvas_id}/upload/

Request upload of scores to Canvas

Parameters

  • account_pk (string) –

  • canvas_id (string) –

  • course_canvas_id (string) –

Request JSON Object

  • replaceExisting (boolean) – (required)

  • sectionId (integer) –

  • uploadFailed (boolean) – (required)

  • uploadPassed (boolean) – (required)

Status Codes
GET /account/{account_pk}/course/{course_canvas_id}/user/prefs/

Get preferences for current user. Only available for reviewers

Parameters

  • account_pk (string) –

  • course_canvas_id (string) –

Status Codes
POST /account/{account_pk}/course/{course_canvas_id}/user/prefs/

Save preferences for current user. Only available for reviewers

Parameters

  • account_pk (string) –

  • course_canvas_id (string) –

Status Codes
GET /account/{account_pk}/course/{course_canvas_id}/user/state/

Retrieve the current user’s current state from Canvas

Parameters

  • account_pk (string) –

  • course_canvas_id (string) –

Status Codes
GET /account/{account_pk}/course/{course_canvas_id}/user/{canvas_id}/

Get details of a user

Parameters

  • account_pk (string) –

  • canvas_id (string) –

  • course_canvas_id (string) –

Status Codes
Response JSON Object

  • id (integer) – (required)

  • name (string) – (required)

  • secondaryId (string) – (required)

GET /account/{account_pk}/course/{course_canvas_id}/user/{user_canvas_id}/result/

List the results of the latest attempts of a single user for all assignments

Parameters

  • account_pk (string) –

  • course_canvas_id (string) –

  • user_canvas_id (string) –

Status Codes
Response JSON Object

  • accepted (boolean) – (required)

  • assignmentId (number) – (required)

  • attempt (number) – (required)

  • has_error (boolean) –

  • is_late (boolean) – (required)

  • is_latest (boolean) – (required)

  • label (string) –

  • processed_at (string) –

  • progress (number) –

  • queued_at (string) –

  • score (number) –

  • secret (boolean) –

  • sections[] (number) –

  • sequence_id (number) – (required)

  • started_at (string) –

  • state (string) – (required)

  • submitted_at (string) – (required)

  • summary (string) –

GET /account/{id}/

Get details of a Canvas account

Parameters

  • id (integer) – A unique integer value identifying this account.

Status Codes
Response JSON Object

  • base_url (string) – Base URL of the Canvas account (required)

  • canvas_guid (string) – GUID of the Canvas account (required)

  • id (integer) – Momotor LTI id for this Canvas account (required)

  • name (string) – Display name of the Canvas account