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:
account¶
- GET /account/¶
List available Canvas accounts
- Status Codes
200 OK –
- 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/{id}/¶
Get details of a Canvas account
- Parameters
id (integer) – A unique integer value identifying this account.
- Status Codes
200 OK –
404 Not Found – Account not found
- 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
course¶
- GET /account/{account_pk}/course/¶
List available courses for this account
- Parameters
account_pk (string) –
- Status Codes
200 OK –
- 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)
[].readonly (boolean) – The course is read-only (required)
[].valid (boolean) – The course exists on Canvas (required)
- GET /account/{account_pk}/course/{canvas_id}/¶
Get details of a course
- Parameters
account_pk (string) –
canvas_id (string) –
- Status Codes
200 OK –
404 Not Found – Course not found
- 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)
readonly (boolean) – The course is read-only (required)
valid (boolean) – The course exists on Canvas (required)
assignment¶
- 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
200 OK –
- Response JSON Object
[].active (boolean) – (read only)
[].canvas_id (integer) – (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/{canvas_id}/¶
Get details of an assignment
- Parameters
account_pk (string) –
canvas_id (string) –
course_canvas_id (string) –
- Status Codes
200 OK –
404 Not Found – Assignment not found
- Response JSON Object
active (boolean) – (read only)
canvas_id (integer) – (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
active (boolean) – (read only)
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
200 OK –
400 Bad Request – Bad request
404 Not Found – Assignment not found
- Response JSON Object
active (boolean) – (read only)
canvas_id (integer) – (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
active (boolean) – (read only)
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
200 OK –
400 Bad Request – Bad request
404 Not Found – Assignment not found
- Response JSON Object
active (boolean) – (read only)
canvas_id (integer) – (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}/refresh/¶
Request refresh of assignment. Only works for inactive assignments. Active assignments are refreshed automatically.Posting to this endpoint will initiate a refresh of the assignment info and submission from Canvas. This is normally not needed. Only for when Momotor thinks an assignment is not active anymore, but it’s status on Canvas changed. There is a cooldown timer on this request, it can only be called once per 15 minutes.
- Parameters
account_pk (string) –
canvas_id (string) –
course_canvas_id (string) –
- Request JSON Object
canvas_id (integer) – (read only)
configfile.name (string) – (read only)
configfile.url (string) – (read only)
evaluate (string) – (required)
name (string) – (read only)
paused (boolean) –
published (boolean) –
recipefile.name (string) – (read only)
recipefile.url (string) – (read only)
- Status Codes
204 No Content – Request received
404 Not Found – Assignment not found
409 Conflict – Assignment is already active
429 Too Many Requests – Too many requests. Wait at least 15 minutes between these requests
- 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
204 No Content – Request received
400 Bad Request – Bad request
503 Service Unavailable – Unable to process request
result¶
- 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
200 OK –
- Response JSON Object
[].accepted (boolean) –
[].assignmentId (integer) – (required)
[].attempt (integer) – (required)
[].has_error (boolean) –
[].is_late (boolean) – (required)
[].is_latest (boolean) – (required)
[].label (string) –
[].preview_url (string) –
[].processed_at (string) –
[].progress (number) –
[].queued_at (string) –
[].score (number) –
[].secret (boolean) –
[].sections[] (integer) –
[].sequence_id (integer) –
[].started_at (string) –
[].state (string) – (required)
[].submitted_at (string) – (required)
[].summary (string) –
[].user (object) – (required)
- 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
200 OK –
- Response JSON Object
[].accepted (boolean) –
[].assignmentId (integer) – (required)
[].attempt (integer) – (required)
[].has_error (boolean) –
[].is_late (boolean) – (required)
[].is_latest (boolean) – (required)
[].label (string) –
[].preview_url (string) –
[].processed_at (string) –
[].progress (number) –
[].queued_at (string) –
[].score (number) –
[].secret (boolean) –
[].sections[] (integer) –
[].sequence_id (integer) –
[].started_at (string) –
[].state (string) – (required)
[].submitted_at (string) – (required)
[].summary (string) –
[].user (object) – (required)
- 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
200 OK –
404 Not Found – Result not found
- Response JSON Object
accepted (boolean) – (required)
details (object) –
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
200 OK –
404 Not Found – Result not found
- Response JSON Object
accepted (boolean) –
assignmentId (integer) – (required)
attempt (integer) – (required)
has_error (boolean) –
is_late (boolean) – (required)
is_latest (boolean) – (required)
label (string) –
preview_url (string) –
processed_at (string) –
progress (number) –
queued_at (string) –
score (number) –
secret (boolean) –
sections[] (integer) –
sequence_id (integer) –
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) –
user (object) – (required)
- 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
200 OK –
404 Not Found – Result not found
- Response JSON Object
accepted (boolean) – (required)
details (object) –
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
200 OK –
404 Not Found – Result not found
- Response JSON Object
accepted (boolean) –
assignmentId (integer) – (required)
attempt (integer) – (required)
has_error (boolean) –
is_late (boolean) – (required)
is_latest (boolean) – (required)
label (string) –
preview_url (string) –
processed_at (string) –
progress (number) –
queued_at (string) –
score (number) –
secret (boolean) –
sections[] (integer) –
sequence_id (integer) –
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) –
user (object) – (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
200 OK –
- Response JSON Object
[].accepted (boolean) –
[].assignmentId (integer) – (required)
[].attempt (integer) – (required)
[].has_error (boolean) –
[].is_late (boolean) – (required)
[].is_latest (boolean) – (required)
[].label (string) –
[].preview_url (string) –
[].processed_at (string) –
[].progress (number) –
[].queued_at (string) –
[].score (number) –
[].secret (boolean) –
[].sections[] (integer) –
[].sequence_id (integer) –
[].started_at (string) –
[].state (string) – (required)
[].submitted_at (string) – (required)
[].summary (string) –
[].user (object) – (required)
result download¶
- 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
200 OK –
404 Not Found – Assignment not found
- GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{result_user__canvas_id}/attempt/{attempt}/basic_bundle/¶
Get basic bundle zip or xml
- Parameters
account_pk (string) –
assignment_canvas_id (string) –
attempt (string) –
course_canvas_id (string) –
result_user__canvas_id (string) –
- Status Codes
200 OK –
404 Not Found – Result not found
410 Gone – Result is gone
- 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
200 OK –
404 Not Found – Result or specified file not found
410 Gone – Result is gone
- GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{result_user__canvas_id}/attempt/{attempt}/bundle/¶
Get bundle zip or xml. Returns full bundle if available otherwise the basic bundle
- Parameters
account_pk (string) –
assignment_canvas_id (string) –
attempt (string) –
course_canvas_id (string) –
result_user__canvas_id (string) –
- Status Codes
200 OK –
404 Not Found – Result not found
410 Gone – Result is gone
- 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
200 OK –
404 Not Found – Result or specified file not found
410 Gone – Result is gone
- GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{result_user__canvas_id}/attempt/{attempt}/full_bundle/¶
Get full bundle zip or xml
- Parameters
account_pk (string) –
assignment_canvas_id (string) –
attempt (string) –
course_canvas_id (string) –
result_user__canvas_id (string) –
- Status Codes
200 OK –
404 Not Found – Result not found
410 Gone – Full bundle is gone
- 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
200 OK –
404 Not Found – Result or specified file not found
410 Gone – Full bundle is gone
- GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{user__canvas_id}/basic_bundle/¶
Get basic bundle zip or xml
- Parameters
account_pk (string) –
assignment_canvas_id (string) –
course_canvas_id (string) –
user__canvas_id (string) –
- Status Codes
200 OK –
404 Not Found – Result not found
410 Gone – Result is gone
- 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
200 OK –
404 Not Found – Result or specified file not found
410 Gone – Result is gone
- GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{user__canvas_id}/bundle/¶
Get bundle zip or xml. Returns full bundle if available otherwise the basic bundle
- Parameters
account_pk (string) –
assignment_canvas_id (string) –
course_canvas_id (string) –
user__canvas_id (string) –
- Status Codes
200 OK –
404 Not Found – Result not found
410 Gone – Result is gone
- 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
200 OK –
404 Not Found – Result or specified file not found
410 Gone – Result is gone
- GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{user__canvas_id}/full_bundle/¶
Get full bundle zip or xml
- Parameters
account_pk (string) –
assignment_canvas_id (string) –
course_canvas_id (string) –
user__canvas_id (string) –
- Status Codes
200 OK –
404 Not Found – Result not found
410 Gone – Full bundle is gone
- 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
200 OK –
404 Not Found – Result or specified file not found
410 Gone – Full bundle is gone
product download¶
- GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{result_user__canvas_id}/attempt/{attempt}/product/¶
Get the product bundle for this result
- Parameters
account_pk (string) –
assignment_canvas_id (string) –
attempt (string) –
course_canvas_id (string) –
result_user__canvas_id (string) –
- Status Codes
200 OK –
404 Not Found – Product not found
410 Gone – Product is gone
- GET /account/{account_pk}/course/{course_canvas_id}/assignment/{assignment_canvas_id}/result/{user__canvas_id}/product/¶
Get the product bundle for this result
- Parameters
account_pk (string) –
assignment_canvas_id (string) –
course_canvas_id (string) –
user__canvas_id (string) –
- Status Codes
200 OK –
404 Not Found – Product not found
410 Gone – Product is gone
user¶
- 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
200 OK –
- 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
200 OK –
- 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
200 OK –
- 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
200 OK –
404 Not Found – User not found