CodeGrade API

This is the API documentation for API v1.0 of CodeGrade. The general API guidelines are firstly specified to subsequently provide a detailed documentation of the API of CodeGrade.

General API rules

URL buildup

All API URL’s should prefix /api/v$x where $x is the current version of the API, which is 1 at the moment of writing. After this prefix the first comes the first collection, a collection is a set of objects of something. Examples are schools, a set of multiple schools, feedback, a set of feedback, or users, the set of multiple users. All collections should always be plural nouns. When doing a request to the collection this should apply to all items in this collection, when allowed, filters can be used and should be passed as GET parameters.

However when querying a single object, always identified by id, this id should be a new path in the URL. So querying a single school should use the url /api/v1/schools/1.

Collections can be nested, so multiple collections in a single URL, however these rules should be followed. First a single directory in the URL should always contain only one collection. Second the URL should be read from left to right, so the URL /api/v1/schools/23/teachers/3/children/ should return all children of the teacher with id 3 of the school with id 23 (please not the required trailing slash). All but the last collection should have an id specifier when using nested collections, this means the pattern (collection/id)*/collection/(id)? (please note that there is no trailing slash after an id) should always be used. For example the URL /api/v1/schools/teachers/ is always illegal.

To sort, filter and search GET parameters should be passed (see the next section for Http methods documentation), it should follow the key=value where the key should be generic, category instead of school_category. A special case is the key sort, where there can be multiple options (separated by spaces) (these are the different sort options) and each value should be prepended with either a - or a + meaning respectively sort descending and sort ascending.

Http methods

Http methods should be used as the verb that can not be used in the URL. The possible http methods are:

  • GET: This method should be used to get something from the server. It should not have any side effects, so it should not alter the database for example.
  • POST: This method should create a new object within the given collection. Once again the URL is used for filtering, for example a POST to /api/v1/schools/5/teacher should create a new teacher in the school with id 5. The content type should be application/json and the payload should be a valid JSON object.
  • PUT: This method should be used to update an existing object or create the object if it does not exist. Filtering should be done using the URL (please note that /api/v1/schools/5/teacher is not valid as this is not a single object), the content type application/json and the payload should be a valid JSON object.
  • DELETE: This method should be used to delete a object. The same rules apply as for the PUT method.
  • PATCH: This method is the same as the PUT method, however it will NOT create a new object if the object does not exist.

Other Http methods may NOT be used.

API responses

Http status codes

Http status codes should be used to convey the status of the request. The entire list of status codes can be found online. However these are the most important ones:

  • 200: Everything went OK and the server should return a useful result.
  • 201: This status should be used when a new resource is created after a POST, PUT request.
  • 204: This status should be used if the request was correct but no content should be returned.
  • 400: Should be signaled when a request was invalid.
  • 401: Should be used when the user is not authorized, so if the user is not logged in.
  • 403: Should be used when the user is logged in but the user is not authorized to see the requested object(s).
  • 404: Should be used when the requested object does not exist.
  • 410: Should be used if the object is no longer available.

Response

The response of the server should always be a valid JSON object, unless the status code is 204, in this case there should not be a response at all.

This means that even if the status code is not 2xx (so not success), there should be a response. In this case the response should be a JSON object with at least the following keys:

  • message: A short message that is somewhat useful for a non technical user.
  • description: A technical error message that is somewhat useful for debugging purposes (please note that you should NOT send sensitive information).
  • code: The error code that should uniquely identify the error.

A error message may be nested, where the nested errors should be in an array behind the key errors and every item in the array should be a valid JSON error with the above specified required keys.

API documentation

Every API end point for every http method should be documented. The headline structure should follow that of the URL but in reverse. So the API end /api/v1/schools/3/teachers should be documented under the title Teachers, and under teachers there should be a subsection schools. Furthermore every API call should have an input object, with types for every key and description, and an example output object. Last every API call should have a higher level description of the use and working.

CodeGrade API Documentation

Resource Operation Description
  GET /api/v1/plagiarism/  
  GET /api/v1/lti/  
About GET /api/v1/about Get the version and features.
Assignment GET /api/v1/assignments/ Get all assignments.
  DELETE /api/v1/assignments/(int:assignment_id)/graders/(int:grader_id)/done Set the grader status to ‘not done’.
  POST /api/v1/assignments/(int:assignment_id)/graders/(int:grader_id)/done Set the grader status to ‘done’.
  GET /api/v1/assignments/(int:assignment_id)/groups/(int:group_id)/member_states/ Get LTI states for members of a group.
  PATCH /api/v1/assignments/(int:assignment_id)/division_parent Change the division parent of an assignment.
  GET /api/v1/assignments/(int:assignment_id)/submissions/ Get all works for an assignment.
  POST /api/v1/assignments/(int:assignment_id)/submissions/ Create works from a blackboard zip.
  POST /api/v1/assignments/(int:assignment_id)/submission Create work by uploading a file.
  GET /api/v1/assignments/(int:assignment_id)/plagiarism/ Get all plagiarism runs for an assignment.
  POST /api/v1/assignments/(int:assignment_id)/plagiarism Run a plagiarism checker for an assignment.
  GET /api/v1/assignments/(int:assignment_id)/feedbacks/ Get feedback for all submissions in a assignment.
  GET /api/v1/assignments/(int:assignment_id)/rubrics/ Get the rubric of an assignment.
  DELETE /api/v1/assignments/(int:assignment_id)/rubrics/ Delete the rubric of an assignment.
  PUT /api/v1/assignments/(int:assignment_id)/rubrics/ Add a rubric to an assignment.
  GET /api/v1/assignments/(int:assignment_id)/graders/ Get all graders for an assignment.
  GET /api/v1/assignments/(int:assignment_id)/linters/ Get all linters for a assignment.
  POST /api/v1/assignments/(int:assignment_id)/rubric Import a rubric from a different assignment.
  PATCH /api/v1/assignments/(int:assignment_id)/divide Divide a submission among given TA’s.
  POST /api/v1/assignments/(int:assignment_id)/linter Start linting an assignment with a given linter.
  GET /api/v1/assignments/(int:assignment_id) Get a single assignment by id.
  PATCH /api/v1/assignments/(int:assignment_id) Update assignment information.
Code PUT /api/v1/code/(int:code_id)/comments/(int:line) Add or change a comment.
  DELETE /api/v1/code/(int:code_id)/comments/(int:line) Remove a comment.
  GET /api/v1/code/(int:file_id) Get code or its metadata.
  DELETE /api/v1/code/(int:file_id) Delete the given file.
  PATCH /api/v1/code/(int:file_id) Update the content or name of the given file.
Course POST /api/v1/courses/ Add a new course.
  GET /api/v1/courses/ Get all courses the current user is enrolled in.
  GET /api/v1/courses/(int:course_id)/assignments/ Get all assignments for single course.
  POST /api/v1/courses/(int:course_id)/assignments/ Create a new assignment in a course.
  GET /api/v1/courses/(int:course_id)/permissions/ Get all the course permissions for the current user.
  GET /api/v1/courses/(int:course_id)/group_sets/ Get all group sets in the course.
  PUT /api/v1/courses/(int:course_id)/group_sets/ Create a new group set in the course.
  DELETE /api/v1/courses/(int:course_id)/roles/(int:role_id) Delete a course role from a course.
  PATCH /api/v1/courses/(int:course_id)/roles/(int:role_id) Update a permission for a certain role.
  POST /api/v1/courses/(int:course_id)/roles/ Add a new course role to a course.
  GET /api/v1/courses/(int:course_id)/roles/ Get all course roles for a single course.
  PUT /api/v1/courses/(int:course_id)/users/ Change the course role for a user.
  GET /api/v1/courses/(int:course_id)/users/ Get all users for a single course.
  GET /api/v1/courses/(int:course_id) Get data for a given course.
File POST /api/v1/files/ Safe a file temporarily on the server.
  GET /api/v1/files/(file_name)/(name) Get an uploaded file directory.
  GET /api/v1/files/(file_name)  
Group DELETE /api/v1/groups/(int:group_id)/members/(int:user_id) Remove a member from a group.
  POST /api/v1/groups/(int:group_id)/member Add a member to a group.
  POST /api/v1/groups/(int:group_id)/name Update the name of a group.
  GET /api/v1/groups/(int:group_id) Get a single group by id.
  DELETE /api/v1/groups/(int:group_id) Delete a group by id.
GroupSet GET /api/v1/group_sets/(int:group_set_id)/groups/ Get the groups of this assignment.
  POST /api/v1/group_sets/(int:group_set_id)/group Create a group in a given group set.
  GET /api/v1/group_sets/(int:group_set_id) Get a single group set by id.
  DELETE /api/v1/group_sets/(int:group_set_id) Delete a single group set by id.
LTI POST /api/v1/lti/launch/1 Do a LTI Launch.
  POST /api/v1/lti/launch/2 Do the callback of a LTI launch.
Linter GET /api/v1/linters/(linter_id)/linter_instances/(linter_instance_id) Get the state of a given linter.
  DELETE /api/v1/linters/(linter_id) Delete all linter input for a given linter.
  GET /api/v1/linters/(linter_id) Get the state of a given linter.
Permission GET /api/v1/permissions/ Get global permissions or all the course permissions for the current user.
Plagiarism GET /api/v1/plagiarism/(int:plagiarism_id)/cases/(int:case_id) Get a single plagiarism case.
  GET /api/v1/plagiarism/(int:plagiarism_id)/cases/ Get the cases for a plagiarism run.
  DELETE /api/v1/plagiarism/(int:plagiarism_id) Delete a plagiarism run and all its cases.
  GET /api/v1/plagiarism/(int:plagiarism_id) Get a single plagiarism run.
Role GET /api/v1/roles/ Get all global roles with their permissions.
  PATCH /api/v1/roles/(int:role_id) Update a permission for a certain role.
Snippet GET /api/v1/snippets/ Get all snippets for the currently logged in user.
  PUT /api/v1/snippet Add or modify a snippet.
  PATCH /api/v1/snippets/(int:snippet_id) Change a snippets key and value.
  DELETE /api/v1/snippets/(int:snippet_id) Delete a snippet.
Submission GET /api/v1/submissions/(int:submission_id)/grade_history/ Get the grade history for the given submission.
  DELETE /api/v1/submissions/(int:submission_id)/rubricitems/(int:rubric_item_id) Unselect the given rubric item.
  PATCH /api/v1/submissions/(int:submission_id)/rubricitems/(int:rubricitem_id) Select a rubric item.
  PATCH /api/v1/submissions/(int:submission_id)/rubricitems/ Select multiple rubric items.
  GET /api/v1/submissions/(int:submission_id)/feedbacks/ Get all (linter, user and general) feedback.
  GET /api/v1/submissions/(int:submission_id)/rubrics/ Get a rubric and its selected items.
  PATCH /api/v1/submissions/(int:submission_id)/grader Update grader for the submission.
  DELETE /api/v1/submissions/(int:submission_id)/grader Delete grader for the submission.
  POST /api/v1/submissions/(int:submission_id)/files/ Create a new file or directory for a submission.
  GET /api/v1/submissions/(int:submission_id)/files/ Get the directory contents for a submission.
  GET /api/v1/submissions/(int:submission_id) Get a single submission.
  DELETE /api/v1/submissions/(int:submission_id) Delete a submission and all its files.
  PATCH /api/v1/submissions/(int:submission_id) Update a submissions grade and feedback.
User POST /api/v1/login Login a given user.
  GET /api/v1/login Get information about the currently logged in user.
  PATCH /api/v1/login Update the currently logged users information or reset a password.
  GET /api/v1/users/ Fuzzy search for a user by name and username.
  POST /api/v1/user Create a new user by registering it.
GET /api/v1/about

Get the version and features of the currently running instance.

Response JSON Object:
 
  • version (string) – The version of the running instance.
  • features (object) – A mapping from string to a boolean for every feature indicating if the current instance has it enabled.
Response JSON Object:
 

The mapping as described above.

rtype:JSONResponse[Mapping[str, Union[str, object, Mapping[str, bool]]]]
GET /api/v1/assignments/

Get all the models.Assignment objects that the current user can see.

Response JSON Object:
 

An array of models.Assignment items encoded in JSON.

Query Parameters:
 
  • only_with_rubric – When this parameter is given only assignments that have a rubric will be loaded.
Possible error responses:
 

PermissionException – If there is no logged in user. (NOT_LOGGED_IN)

rtype:JSONResponse[Sequence[Assignment]]
GET /api/v1/assignments/(int: assignment_id)

Return the given models.Assignment.

Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

A response containing the JSON serialized assignment

Possible error responses:
 
rtype:JSONResponse[Assignment]
PATCH /api/v1/assignments/(int: assignment_id)

Update the given models.Assignment with new values.

Request JSON Object:
 
  • state (str) – The new state of the assignment, can be hidden, open or done. (OPTIONAL)
  • name (str) – The new name of the assignment, this string should not be empty. (OPTIONAL)
  • deadline (str) – The new deadline of the assignment. This should be a ISO 8061 date without timezone information. (OPTIONAL)
  • done_type (str) – The type to determine if a assignment is done. This can be any value of models.AssignmentDoneType or null. (OPTIONAL)
  • done_email (str) – The emails to send an email to if the assignment is done. Can be null to disable these emails. (OPTIONAL)
  • reminder_time (str) – The time on which graders which are causing the grading to be not should be reminded they have to grade. Can be null to disable these emails. (OPTIONAL)
  • max_grade (float) – The maximum possible grade for this assignment. You can reset this by passing null as value. This value has to be > 0. (OPTIONAL)
  • group_set_id (int) – The group set id for this assignment. Set to null to make this assignment not a group assignment.

If any of done_type, done_email or reminder_time is given all the other values should be given too.

Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

An empty response with return code 204.

Possible error responses:
 

APIException – If an invalid value is submitted. (INVALID_PARAM)

rtype:JSONResponse[Assignment]
PATCH /api/v1/assignments/(int: assignment_id)/divide

Assign graders to all the latest models.Work objects of the given models.Assignment.

The redivide tries to minimize shuffles. This means that calling it twice with the same data is effectively a noop. If the relative weight (so the percentage of work) of a user doesn’t change it will not lose or gain any submissions.

Warning

If a user was marked as done grading and gets assigned new submissions this user is marked as not done and gets a notification email!

Request JSON Object:
 
  • graders (dict) – A mapping that maps user ids (strings) and the new weight they should get (numbers).
Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

An empty response with return code 204

Possible error responses:
 
  • APIException – If no assignment with given id exists or the assignment has no submissions. (OBJECT_ID_NOT_FOUND)
  • APIException – If there was no grader in the request. (MISSING_REQUIRED_PARAM)
  • APIException – If some grader id is invalid or some grader does not have the permission to grade the assignment. (INVALID_PARAM)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user is not allowed to divide submissions for this assignment. (INCORRECT_PERMISSION)
rtype:EmptyResponse
PATCH /api/v1/assignments/(int: assignment_id)/division_parent

Change the division parent of an assignment.

Set the division parent of this assignment. See the documentation about dividing submissions for more information about division parents.

Parameters:
  • assignment_id – The id of the assignment you want to change.
Request JSON Object:
 
  • parent_assignment_id – The id of the assignment that should be the division parent of the given assignment. If this is set to null the division parent of this assignment will be cleared.
Response JSON Object:
 

An empty response with status code code 204.

rtype:EmptyResponse
GET /api/v1/assignments/(int: assignment_id)/feedbacks/

Get all feedbacks for all latest submissions for a given assignment.

Parameters:
  • assignment_id (int) – The assignment to query for.
Response JSON Object:
 

A mapping between the id of the submission and a object contain three keys: general for general feedback as a string, user for user feedback as a list of strings and linter for linter feedback as a list of strings. If a user cannot see others work only submissions by the current users are returned.

rtype:JSONResponse[Mapping[str, Mapping[str, Union[Sequence[str], str]]]]
GET /api/v1/assignments/(int: assignment_id)/graders/

Gets a list of all models.User objects who can grade the given models.Assignment.

Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

A response containing the JSON serialized graders.

Response JSON Array of Objects:
 
  • name (string) – The name of the grader.
  • id (int) – The user id of this grader.
  • divided (bool) – Is this user assigned to any submission for this assignment.
  • done (bool) – Is this user done grading?
Possible error responses:
 
  • APIException – If no assignment with given id exists. (OBJECT_ID_NOT_FOUND)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user is not allowed to view graders of this assignment. (INCORRECT_PERMISSION)
rtype:JSONResponse[Sequence[Mapping[str, Union[float, str, bool]]]]
POST /api/v1/assignments/(int: assignment_id)/graders/(int: grader_id)/done

Indicate that the given grader is done grading the given :class:.models.Assignment.

Parameters:
  • assignment_id – The id of the assignment the grader is done grading.
  • grader_id – The id of the :class:.models.User that is done grading.
Response JSON Object:
 

An empty response with return code 204

Possible error responses:
 
  • APIException – If the given grader was indicated as done before calling this endpoint. (INVALID_STATE)
  • PermissionException – If the current user wants to change a status of somebody else but the user does not have the can_update_grader_status permission. (INCORRECT_PERMISSION)
  • PermissionException – If the current user wants to change its own status but does not have the can_update_grader_status or the can_grade_work permission. (INCORRECT_PERMISSION)
rtype:EmptyResponse
DELETE /api/v1/assignments/(int: assignment_id)/graders/(int: grader_id)/done

Indicate that the given grader is not yet done grading the given :class:.models.Assignment.

Parameters:
  • assignment_id – The id of the assignment the grader is not yet done grading.
  • grader_id – The id of the :class:.models.User that is not yet done grading.
Response JSON Object:
 

An empty response with return code 204

Possible error responses:
 
  • APIException – If the given grader was not indicated as done before calling this endpoint. (INVALID_STATE)
  • PermissionException – If the current user wants to change a status of somebody else but the user does not have the can_update_grader_status permission. (INCORRECT_PERMISSION)
  • PermissionException – If the current user wants to change its own status but does not have the can_update_grader_status or the can_grade_work permission. (INCORRECT_PERMISSION)
rtype:EmptyResponse
GET /api/v1/assignments/(int: assignment_id)/groups/(int: group_id)/member_states/

Get the LTI states for the members of a group for the given assignment.

Parameters:
  • assignment_id – The assignment for which the LTI states should be given.
  • group_id – The group for which the states should be returned.
Response JSON Object:
 

A mapping between user id and a boolean indicating if we can already passback grades for this user. If the assignment is any LTI assignment and any of the values in this mapping is False trying to submit anyway will result in a failure.

rtype:JSONResponse[Mapping[int, bool]]
POST /api/v1/assignments/(int: assignment_id)/linter

Starts running a specific linter on all the latest submissions (models.Work) of the given models.Assignment.

Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

A response containing the serialized linter that is started by the request

Possible error responses:
 
  • APIException – If a required parameter is missing. (MISSING_REQUIRED_PARAM)
  • APIException – If a linter of the same name is already running on the assignment. (INVALID_STATE)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not user linters in this course. (INCORRECT_PERMISSION)
rtype:JSONResponse[AssignmentLinter]
GET /api/v1/assignments/(int: assignment_id)/linters/

Get all linters for the given models.Assignment.

Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

A response containing the JSON serialized linters which is sorted by the name of the linter.

Response JSON Array of Objects:
 
  • state (str) – The state of the linter, which can be new, or any state from models.LinterState.
  • name (str) – The name of this linter.
  • id (str) – The id of the linter, this will only be present when state is not new.
  • *rest – All items as described in linters.get_all_linters()
Possible error responses:
 
rtype:JSONResponse[Sequence[Mapping[str, Any]]]
POST /api/v1/assignments/(int: assignment_id)/plagiarism

Run a plagiarism checker for the given models.Assignment.

Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

The json serialization newly created models.PlagiarismRun.

Note

This route is weird in one very important way. You can provide your json input in two different ways. One is the ‘normal’ way, the body of the request is the json data and the content-type is set appropriately. However as this route allows you to upload files, this approach will not always work. Therefore for this route it is also possible to provide json by uploading it as a file under the json key.

Request JSON Object:
 
  • provider (str) – The name of the plagiarism checker to use.
  • old_assignments (list) – The id of the assignments that need to be used as old assignments.
  • has_base_code – Does this request contain base code that should be used by the plagiarism checker.
  • has_old_submissions – Does this request contain old submissions that should be used by the plagiarism checker.
  • **rest – The other options used by the provider, as indicated by /api/v1/plagiarism/. Each key should be a possible option and its value is the value that should be used.
Possible error responses:
 

PermissionException – If the user can not manage plagiarism runs or cases for this course. (INCORRECT_PERMISSION)

rtype:JSONResponse[PlagiarismRun]
GET /api/v1/assignments/(int: assignment_id)/plagiarism/

Get all plagiarism runs for the given models.Assignment.

Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

A response containing the JSON serialized list of plagiarism runs.

Possible error responses:
 

PermissionException – If the user can not view plagiarism runs or cases for this course. (INCORRECT_PERMISSION)

rtype:JSONResponse[Iterable[PlagiarismRun]]
POST /api/v1/assignments/(int: assignment_id)/rubric

Import a rubric from a different assignment.

Parameters:
  • assignment_id – The id of the assignment in which you want to import the rubric. This assignment shouldn’t have a rubric.
Response JSON Object:
 
  • old_assignment_id – The id of the assignment from which the rubric should be imported. This assignment should have a rubric.
Response JSON Object:
 

The rubric rows of the assignment in which the rubric was imported, so the assignment with id assignment_id and not old_assignment_id.

rtype:JSONResponse[Sequence[RubricRow]]
PUT /api/v1/assignments/(int: assignment_id)/rubrics/

Add or update rubric of an assignment.

Response JSON Object:
 
  • rows (array) – An array of rows. Each row should be an object that should contain a header mapping to a string, a description key mapping to a string, an items key mapping to an array and it may contain an id key mapping to the current id of this row. The items array should contain objects with a description (string), header (string) and points (number) and optionally an id if you are modifying an existing item in an existing row.
  • max_points (number) – Optionally override the maximum amount of points you can get for this rubric. By passing null you reset this value, by not passing it you keep its current value. (OPTIONAL)
Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

An empty response with return code 204

Possible error responses:
 
rtype:JSONResponse[Sequence[RubricRow]]
DELETE /api/v1/assignments/(int: assignment_id)/rubrics/

Delete the rubric for the given assignment.

Parameters:
  • assignment_id – The id of the models.Assignment whose rubric should be deleted.
Response JSON Object:
 

Nothing.

Possible error responses:
 
  • PermissionException – If the user does not have the manage_rubrics permission (INCORRECT_PERMISSION).
  • APIException – If the assignment has no rubric. (OBJECT_ID_NOT_FOUND)
rtype:EmptyResponse
GET /api/v1/assignments/(int: assignment_id)/rubrics/

Return the rubric corresponding to the given assignment_id.

Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

A list of JSON of models.RubricRows items.

Possible error responses:
 
  • APIException – If no assignment with given id exists. (OBJECT_ID_NOT_FOUND)
  • APIException – If the assignment has no rubric. (OBJECT_ID_NOT_FOUND)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
rtype:JSONResponse[Sequence[RubricRow]]
POST /api/v1/assignments/(int: assignment_id)/submission

Upload one or more files as models.Work to the given models.Assignment.

Query Parameters:
 
  • ignored_files – How to handle ignored files. The options are: ignore: this the default, sipmly do nothing about ignored files, delete: delete the ignored files, error: raise an APIException when there are ignored files in the archive.
  • author – The username of the user that should be the author of this new submission. Simply don’t give this if you want to be the author.
Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

A JSON serialized work and with the status code 201.

Possible error responses:
 
  • APIException – If the request is bigger than the maximum upload size. (REQUEST_TOO_LARGE)
  • APIException – If there was no file in the request. (MISSING_REQUIRED_PARAM)
  • APIException – If some file was under the wrong key or some filename is empty. (INVALID_PARAM)
rtype:ExtendedJSONResponse[Work]
GET /api/v1/assignments/(int: assignment_id)/submissions/

Return all models.Work objects for the given models.Assignment.

Query Parameters:
 
  • extended (boolean) – Whether to get extended or normal models.Work objects. The default value is false, you can enable extended by passing true, 1 or an empty string.
Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

A response containing the JSON serialized submissions.

Possible error responses:
 
rtype:Union[JSONResponse[Sequence[Work]], ExtendedJSONResponse[Sequence[Work]]]
POST /api/v1/assignments/(int: assignment_id)/submissions/

Add submissions to the given:class:.models.Assignment from a blackboard zip file as models.Work objects.

You should upload a file as multiform post request. The key should start with ‘file’. Multiple blackboard zips are not supported and result in one zip being chosen at (psuedo) random.

Parameters:
  • assignment_id (int) – The id of the assignment
Response JSON Object:
 

An empty response with return code 204

Possible error responses:
 
  • APIException – If no assignment with given id exists. (OBJECT_ID_NOT_FOUND)
  • APIException – If there was no file in the request. (MISSING_REQUIRED_PARAM)
  • APIException – If the file parameter name is incorrect or if the given file does not contain any valid submissions. (INVALID_PARAM)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user is not allowed to manage the course attached to the assignment. (INCORRECT_PERMISSION)
rtype:EmptyResponse
PUT /api/v1/code/(int: code_id)/comments/(int: line)

Create or change a single models.Comment of a code models.File.

Parameters:
  • code_id (int) – The id of the code file
  • line (int) – The line number of the comment
Response JSON Object:
 

An empty response with return code 204

Request JSON Object:
 
  • comment (str) – The comment to add to the given file on the given line.
Possible error responses:
 
rtype:EmptyResponse
DELETE /api/v1/code/(int: code_id)/comments/(int: line)

Removes the given models.Comment in the given models.File

Parameters:
  • code_id (int) – The id of the code file
  • line (int) – The line number of the comment
Response JSON Object:
 

An empty response with return code 204

Possible error responses:
 
  • APIException – If there is no comment at the given line number. (OBJECT_NOT_FOUND)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not can grade work in the attached course. (INCORRECT_PERMISSION)
rtype:EmptyResponse
DELETE /api/v1/code/(int: file_id)

Delete the given file.

If a student does this request before the deadline, the file will be completely deleted. If the request is done after the deadline the user doing the delete will be removed from the ownership of the file and if there are no owners left the file is deleted.

If the file owner of the given file is the same as that of the user doing the request (so the file will be completely deleted) the given file should not have any comments (Linter or normal) associated with it. If it still has comments the request will fail with error code 400.

Response JSON Object:
 

Nothing.

Possible error responses:
 
  • APIException – If the request will result in wrong state. (INVALID_STATE)
  • APIException – If there is not file with the given id. (OBJECT_ID_NOT_FOUND)
  • APIException – If you do not have permission to delete the given file. (INCORRECT_PERMISSION)
rtype:EmptyResponse
GET /api/v1/code/(int: file_id)

Get data from the models.File with the given id.

The are several options to change the data that is returned. Based on the argument type in the request different functions are called.

  • If type == 'metadata' the JSON serialized models.File is returned.
  • If type == 'file-url' or type == 'pdf' (deprecated) an object with a single key, name, with as value the return values of get_file_url().
  • If type == 'feedback' or type == 'linter-feedback' see code.get_feedback()
  • Otherwise the content of the file is returned as plain text.
Parameters:
  • file_id (int) – The id of the file
Response JSON Object:
 

A response containing a plain text file unless specified otherwise.

Possible error responses:
 
  • APIException – If there is not file with the given id. (OBJECT_ID_NOT_FOUND)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the file does not belong to user and the user can not view files in the attached course. (INCORRECT_PERMISSION)
rtype:Union[Response, JSONResponse[Union[Mapping[str, str], File, dict[str, Union[Comment, MutableSequence[tuple[str, LinterComment]]]]]]]
PATCH /api/v1/code/(int: file_id)

Update the content or name of the given file.

If a student does this request before the deadline, the owner of the file will be the student and the teacher (both), if the request is done after the deadline the owner of the new file will be the one doing the request while the old file will be removed or given to the other owner if the file was owned by both. You can give a request parameter operation to determine the operation:

  • If operation is rename the request should also contain a new path for the file under the key new_path.
  • If operation is content the body of the request should contain the new content of the file. This operation is used if no or no valid operation was given.

Note

The id of the returned code object can change, but does not have to.

Response JSON Object:
 

The created code object.

Possible error responses:
 
  • APIException – If there is not file with the given id. (OBJECT_ID_NOT_FOUND)
  • APIException – If you do not have permission to change the given file. (INCORRECT_PERMISSION)
  • APIException – If the request is bigger than the maximum upload size. (REQUEST_TOO_LARGE)
rtype:JSONResponse[File]
POST /api/v1/courses/

Add a new models.Course.

Response JSON Object:
 

A response containing the JSON serialization of the new course

Possible error responses:
 
rtype:JSONResponse[Course]
GET /api/v1/courses/

Return all models.Course objects the current user is a member of.

Response JSON Object:
 

A response containing the JSON serialized courses

Parameters:
  • extended (str) – If set to true, 1 or the empty string all the assignments and group sets for each course are also included under the key assignments and group_sets respectively.
Response JSON Array of Objects:
 
  • role (str) – The name of the role the current user has in this course.
  • **rest – JSON serialization of psef.models.Course.
Possible error responses:
 

PermissionException – If there is no logged in user. (NOT_LOGGED_IN)

rtype:JSONResponse[Sequence[Mapping[str, Any]]]
GET /api/v1/courses/(int: course_id)

Return course data for a given models.Course.

Parameters:
  • course_id (int) – The id of the course
Response JSON Object:
 

A response containing the JSON serialized course

Response JSON Object:
 
  • role (str) – The name of the role the current user has in this course.
  • **rest – JSON serialization of psef.models.Course.
Possible error responses:
 
rtype:JSONResponse[Mapping[str, Any]]
POST /api/v1/courses/(int: course_id)/assignments/

Create a new course for the given assignment.

Parameters:
  • course_id (int) – The course to create an assignment in.
Request JSON Object:
 
  • name (str) – The name of the new assignment.
Response JSON Object:
 

The newly created assignment.

Possible error responses:
 

PermissionException – If the current user does not have the can_create_assignment permission (INCORRECT_PERMISSION).

rtype:JSONResponse[Assignment]
GET /api/v1/courses/(int: course_id)/assignments/

Get all models.Assignment objects of the given models.Course.

The returned assignments are sorted by deadline.

Parameters:
  • course_id (int) – The id of the course
Response JSON Object:
 

A response containing the JSON serialized assignments sorted by deadline of the assignment. See models.Assignment.__to_json__() for the way assignments are given.

Possible error responses:
 
  • APIException – If there is no course with the given id. (OBJECT_ID_NOT_FOUND)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not see assignments in the given course. (INCORRECT_PERMISSION)
rtype:JSONResponse[Sequence[Assignment]]
PUT /api/v1/courses/(int: course_id)/group_sets/

Create or update a models.GroupSet in the given course id.

Response JSON Object:
 
  • minimum_size (int) – The minimum size attribute that the group set should have.
  • maximum_size (int) – The maximum size attribute that the group set should have.
  • id (int) – The id of the group to update.
Parameters:
  • course_id – The id of the course in which the group set should be created or updated. The course id of a group set cannot change.
Response JSON Object:
 

The created or updated group.

rtype:JSONResponse[GroupSet]
GET /api/v1/courses/(int: course_id)/group_sets/

Get the all the models.GroupSet objects in the given course.

Parameters:
  • course_id (int) – The id of the course of which the group sets should be retrieved.
Response JSON Object:
 

A list of group sets.

rtype:JSONResponse[Sequence[GroupSet]]
GET /api/v1/courses/(int: course_id)/permissions/

Get all the course models.Permission of the currently logged in models.User

Parameters:
  • course_id (int) – The id of the course of which the permissions should be retrieved.
Response JSON Object:
 

A mapping between the permission name and a boolean indicating if the currently logged in user has this permission.

rtype:JSONResponse[CoursePermMap]
POST /api/v1/courses/(int: course_id)/roles/

Add a new models.CourseRole to the given models.Course.

Parameters:
  • course_id (int) – The id of the course
Response JSON Object:
 

An empty response with return code 204.

Request JSON Object:
 
  • name (str) – The name of the new course role.
Possible error responses:
 
  • APIException – If the name parameter was not in the request. (MISSING_REQUIRED_PARAM)
  • APIException – If the course with the given id was not found. (OBJECT_NOT_FOUND)
  • APIException – If the course already has a role with the submitted name. (INVALID_PARAM)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not manage the course with the given id. (INCORRECT_PERMISSION)
rtype:EmptyResponse
GET /api/v1/courses/(int: course_id)/roles/

Get a list of all models.CourseRole objects of a given models.Course.

Parameters:
  • course_id (int) – The id of the course to get the roles for.
Response JSON Object:
 

An array of all course roles for the given course.

Response JSON Array of Objects:
 
  • perms (t.Mapping[str, bool]) – All permissions this role has as returned by models.CourseRole.get_all_permissions().
  • own (bool) – True if the current course role is the current users course role.
  • **rest – The course role as returned by models.CourseRole.__to_json__()
Possible error responses:
 
rtype:JSONResponse[Union[Sequence[CourseRole], Sequence[MutableMapping[str, Union[Mapping[str, bool], bool]]]]]
DELETE /api/v1/courses/(int: course_id)/roles/(int: role_id)

Remove a models.CourseRole from the given models.Course.

Parameters:
  • course_id (int) – The id of the course
Response JSON Object:
 

An empty response with return code 204

Possible error responses:
 
  • APIException – If the role with the given ids does not exist. (OBJECT_NOT_FOUND)
  • APIException – If there are still users with this role. (INVALID_PARAM)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not manage the course with the given id. (INCORRECT_PERMISSION)
rtype:EmptyResponse
PATCH /api/v1/courses/(int: course_id)/roles/(int: role_id)

Update the models.Permission of a given models.CourseRole in the given models.Course.

Parameters:
  • course_id (int) – The id of the course.
  • role_id (int) – The id of the course role.
Response JSON Object:
 

An empty response with return code 204.

Request JSON Object:
 
  • permission (str) – The name of the permission to change.
  • value (bool) – The value to set the permission to (True means the specified role has the specified permission).
Possible error responses:
 
  • APIException – If the value or permission parameter are not in the request. (MISSING_REQUIRED_PARAM)
  • APIException – If the role with the given id does not exist or the permission with the given name does not exist. (OBJECT_NOT_FOUND)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not manage the course with the given id. (INCORRECT_PERMISSION)
rtype:EmptyResponse
GET /api/v1/courses/(int: course_id)/users/

Return a list of all models.User objects and their models.CourseRole in the given models.Course.

Parameters:
  • course_id (int) – The id of the course
Query Parameters:
 
  • q (string) – Search for users matching this query string. This will change the output to a list of users.
Response JSON Object:
 

A response containing the JSON serialized users and course roles

Response JSON Array of Objects:
 
  • User (User) – A member of the given course.
  • CourseRole (CourseRole) – The role that this user has.
rtype:JSONResponse[Union[list[_UserCourse], list[User]]]
PUT /api/v1/courses/(int: course_id)/users/

Set the models.CourseRole of a models.User in the given models.Course.

Parameters:
  • course_id (int) – The id of the course
Response JSON Object:
 

If the user_id parameter is set in the request the response will be empty with return code 204. Otherwise the response will contain the JSON serialized user and course role with return code 201

Possible error responses:
 
  • APIException – If the parameter role_id or not at least one of user_id and user_email are in the request. (MISSING_REQUIRED_PARAM)
  • APIException – If no role with the given role_id or no user with the supplied parameters exists. (OBJECT_ID_NOT_FOUND)
  • APIException – If the user was selected by email and the user is already in the course. (INVALID_PARAM)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not manage the course with the given id. (INCORRECT_PERMISSION)

Todo

This function should probability be splitted.

rtype:Union[EmptyResponse, JSONResponse[_UserCourse]]
POST /api/v1/files/

Temporarily store some data on the server.

Note

The posted data will be removed after 60 seconds.

Response JSON Object:
 

A response with the JSON serialized name of the file as content and return code 201.

Possible error responses:
 
  • APIException – If the request is bigger than the maximum upload size. (REQUEST_TOO_LARGE)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
rtype:JSONResponse[str]
GET /api/v1/files/(file_name)/(name)
GET /api/v1/files/(file_name)

Serve some specific file in the uploads folder.

Note

Only files uploaded using POST /api/v1/files/ may be retrieved.

Parameters:
  • file_name (str) – The filename of the file to get.
Response JSON Object:
 

The requested file.

Possible error responses:
 

PermissionException – If there is no logged in user. (NOT_LOGGED_IN)

rtype:Response
DELETE /api/v1/group_sets/(int: group_set_id)

Delete the given models.GroupSet.

You can only delete a group set if there are no groups in the set and no assignment is connected to the group set.

Parameters:
  • group_set_id (int) – The id of the group set
rtype:EmptyResponse
GET /api/v1/group_sets/(int: group_set_id)

Return the given models.GroupSet.

Parameters:
  • group_set_id (int) – The id of the group set
Response JSON Object:
 

A response containing the JSON serialized group set.

rtype:JSONResponse[GroupSet]
POST /api/v1/group_sets/(int: group_set_id)/group

Create a group for the given group set.

Parameters:
  • group_set_id – The id of the group set where the new group should be placed in.
Response JSON Object:
 
  • member_ids – A list of user ids of users that should be the initial members of the group. This may be an empty list.
  • name – The name of the group. This key is optional and a random ‘funny’ name will be generated when not given.
Response JSON Object:
 

The newly created group.

rtype:JSONResponse[Group]
GET /api/v1/group_sets/(int: group_set_id)/groups/

Get all groups for a given group set.

Parameters:
  • group_set_id – The group set for which the groups should be returned.
Response JSON Object:
 

All the groups for the given group set.

rtype:JSONResponse[Sequence[Group]]
DELETE /api/v1/groups/(int: group_id)

Delete a group by id.

Warning

This action is irreversible!

Parameters:
  • group_id – The id of the group to delete.
Response JSON Object:
 

Nothing

Possible error responses:
 

APIException – If the group has submissions associated with it. (INVALID_PARAM)

rtype:EmptyResponse
GET /api/v1/groups/(int: group_id)

Get a group by id.

Parameters:
  • group_id – The id of the group to get.
Response JSON Object:
 

The requested group.

rtype:JSONResponse[Group]
POST /api/v1/groups/(int: group_id)/member

Add a user (member) to a group.

Parameters:
  • group_id – The id of the group the user should be added to.
Response JSON Object:
 
  • username – The name of the user that should be added to the group.
Response JSON Object:
 

The group with the newly added user.

rtype:JSONResponse[Group]
DELETE /api/v1/groups/(int: group_id)/members/(int: user_id)

Remove a user (member) from a group.

Parameters:
  • group_id – The group the user should be removed from.
  • user_id – The user that should be removed.
Response JSON Object:
 

The group without the removed user.

Possible error responses:
 

APIException – If the group has submissions associated with it and the given user was the last member. (INVALID_STATE)

rtype:JSONResponse[Group]
POST /api/v1/groups/(int: group_id)/name

Update the name of the group.

Parameters:
  • group_id – The id of the group that should be updated.
Response JSON Object:
 
  • name – The new name of the group.
Response JSON Object:
 

The group with the updated name.

Possible error responses:
 

ValidationException – If the name of the group has less than 3 characters. (iNVALID_PARAM)

rtype:JSONResponse[Group]
DELETE /api/v1/linters/(linter_id)

Delete the all the output created by the models.AssignmentLinter with the given id.

Parameters:
  • linter_id (int) – The id of the linter
Response JSON Object:
 

An empty response with return code 204

Possible error responses:
 
  • APIException – If the linter with the given id does not exist. (OBJECT_ID_NOT_FOUND)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not use the linters in the course attached to the linter with the given id. (INCORRECT_PERMISSION)
rtype:EmptyResponse
GET /api/v1/linters/(linter_id)

Get the state of the models.AssignmentLinter with the given id.

Parameters:
  • linter_id (str) – The id of the linter
Response JSON Object:
 

A response containing the JSON serialized linter

Possible error responses:
 
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not use the linters in the course attached to the linter with the given id. (INCORRECT_PERMISSION)
rtype:Union[ExtendedJSONResponse[AssignmentLinter], JSONResponse[AssignmentLinter]]
GET /api/v1/linters/(linter_id)/linter_instances/(linter_instance_id)

Get the state of the models.AssignmentLinter with the given id.

Parameters:
  • linter_id (str) – The id of the linter
Response JSON Object:
 

A response containing the JSON serialized linter

rtype:ExtendedJSONResponse[LinterInstance]
PATCH /api/v1/login
Change data of the current models.User and handle passsword
resets.
  • If type is reset_password reset the password of the user with the given user_id with the given token to the given new_password.
  • If type is reset_email send a email to the user with the given username that enables this user to reset its password.
  • if type is reset_on_lti the reset_email_on_lti attribute for the current is set to True.
  • Otherwise change user info of the currently logged in user.
Response JSON Object:
 

An empty response with return code 204 unless type is reset_password, in this case a mapping between access_token and a jwt token is returned.

Request JSON Object:
 
  • user_id (int) – The id of the user, only when type is reset_password.
  • username (str) – The username of the user, only when type is reset_email.
  • token (str) – The reset password token. Only if type is reset_password.
  • email (str) – The new email of the user.
  • name (str) – The new full name of the user.
  • old_password (str) – The old password of the user.
  • new_password (str) – The new password of the user.
Possible error responses:
 
  • APIException – If not all required parameters (‘email’, ‘o_password’, ‘name’, ‘n_password’) were in the request. (MISSING_REQUIRED_PARAM)
  • APIException – If the old password was not correct. (INVALID_CREDENTIALS)
  • APIException – If the new password or name is not valid. (INVALID_PARAM)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not edit his own info. (INCORRECT_PERMISSION)
rtype:Union[EmptyResponse, JSONResponse[Mapping[str, str]]]
POST /api/v1/login

Login a models.User if the request is valid.

Response JSON Object:
 

A response containing the JSON serialized user

Request JSON Object:
 
  • username (str) – The username of the user to log in.
  • password (str) – The password of the user to log in.
Query Parameters:
 
  • with_permissions – Setting this to true will add the key permissions to the user. The value will be a mapping indicating which global permissions this user has.
Response JSON Object:
 
  • user (User) – The user that was logged in.
  • access_token (str) – A JWT token that can be used to send requests to the server logged in as the given user.
Possible error responses:
 
  • APIException – If no user with username exists or the password is wrong. (LOGIN_FAILURE)
  • APIException – If the user with the given username and password is inactive. (INACTIVE_USER)
rtype:ExtendedJSONResponse[Mapping[str, Union[MutableMapping[str, Any], str]]]
GET /api/v1/login

Get the info of the currently logged in models.User.

Query Parameters:
 
  • type – If this is roles a mapping between course_id and role name will be returned, if this is extended the result of models.User.__extended_to_json__() will be returned. If this is something else or not present the result of models.User.__to_json__() will be returned.
  • with_permissions – Setting this to true will add the key permissions to the user. The value will be a mapping indicating which global permissions this user has.
Response JSON Object:
 

A response containing the JSON serialized user

Possible error responses:
 

PermissionException – If there is no logged in user. (NOT_LOGGED_IN)

rtype:Union[JSONResponse[Union[User, MutableMapping[str, Any], Mapping[int, str]]], ExtendedJSONResponse[Union[User, MutableMapping[str, Any]]]]
GET /api/v1/lti/

Get a LTI config xml for this CodeGrade instance

Query Parameters:
 
  • lms (str) – The name of the LMS to get the config for. This is required.
Response JSON Object:
 

An xml that can be used as a config for the specified LMS.

rtype:Response
POST /api/v1/lti/launch/1

Do a LTI launch.

rtype:Any
POST /api/v1/lti/launch/2

Do the second part of an LTI launch.

Response JSON Object:
 
  • jwt_token (string) – The JWT token that is the current LTI state. This token can only be acquired using the /lti/launch/1 route.
Request JSON Object:
 
  • assignment – The assignment that the LTI launch was for.
  • new_role_created (bool) – Was a new role created in the LTI launch.
  • access_token – A fresh access token for the current user. This value is not always available, this depends on internal state so you should simply check.
  • updated_email – The new email of the current user. This is value is also not always available, check!
Possible error responses:
 

APIException – If the given Jwt token is not valid. (INVALID_PARAM)

rtype:JSONResponse[Mapping[str, Union[str, Assignment, bool, None]]]
GET /api/v1/permissions/

Get all the global psef.models.Permission or the value of a permission in all courses of the currently logged in psef.models.User

Query Parameters:
 
  • type (str) – The type of permissions to get. This can be global or course.
  • permission (str) – The permissions to get when getting course permissions. You can pass this parameter multiple times to get multiple permissions. DEPRECATED: This option is deprecated, as it is preferred that you simply get all permissions for a course.
Response JSON Object:
 

The returning object depends on the given type. If it was global a mapping between permissions name and a boolean indicating if the currently logged in user has this permissions is returned.

If it was course such a mapping is returned for every course the user is enrolled in. So it is a mapping between course ids and permission mapping. The permissions given as permission query parameter are the only ones that are present in the permission map. When no permission query is given all course permissions are returned.

rtype:JSONResponse[Union[GlobalPermMap, Mapping[int, CoursePermMap]]]
GET /api/v1/plagiarism/

Get all plagiarism providers for this instance.

Response JSON Object:
 

An array of plagiarism providers.

Response JSON Array of Objects:
 
  • name (str) – The name of the plagiarism provider.
  • base_code (bool) – Does this plagiarism provider support base code.
  • options (array) – The extra possible options for this provider, this is an array of JSON serialized plagiarism.Option classes.
rtype:JSONResponse[list[dict[str, object]]]
DELETE /api/v1/plagiarism/(int: plagiarism_id)

Delete a given plagiarism run and all its cases.

Warning

This is irreversible, so make sure the user really wants this!

Parameters:
  • plagiarism_id (int) – The id of the run to delete.
Response JSON Object:
 

Nothing.

Possible error responses:
 

PermissionException – If the user can not manage plagiarism runs or cases for the course associated with the run. (INCORRECT_PERMISSION)

rtype:EmptyResponse
GET /api/v1/plagiarism/(int: plagiarism_id)

Get a models.PlagiarismRun.

Query Parameters:
 
  • extended (boolean) – Whether to get an extended or normal models.PlagiarismRun object. The default value is false, you can enable extended by passing true, 1 or an empty string.
Parameters:
  • plagiarism_id (int) – The of the plagiarism run.
Response JSON Object:
 

An single plagiarism run.

Possible error responses:
 

PermissionException – If the user can not view plagiarism runs or cases for the course associated with the run. (INCORRECT_PERMISSION)

rtype:Union[JSONResponse[PlagiarismRun], ExtendedJSONResponse[PlagiarismRun]]
GET /api/v1/plagiarism/(int: plagiarism_id)/cases/

Get all the models.PlagiarismCase`s for the given :class:.models.PlagiarismRun`.

Parameters:
  • plagiarism_id (int) – The of the plagiarism run.
Response JSON Object:
 

An array of JSON serialized plagiarism cases.

Possible error responses:
 

PermissionException – If the user can not view plagiarism runs or cases for the course associated with the run. (INCORRECT_PERMISSION)

rtype:JSONResponse[Iterable[PlagiarismCase]]
GET /api/v1/plagiarism/(int: plagiarism_id)/cases/(int: case_id)

Get the extended view of a single models.PlagiarismCase object.

Parameters:
  • plagiarism_id (int) – The id of the run the case should belong to.
  • case_id (int) – The id of the case requested.
Response JSON Object:
 

The extended JSON serialization of the plagiarism case requested.

Possible error responses:
 

PermissionException – If the user can not view plagiarism runs or cases for the course associated with the run. (INCORRECT_PERMISSION)

rtype:ExtendedJSONResponse[PlagiarismCase]
GET /api/v1/roles/

Get all global roles with their permissions

Response JSON Object:
 A object as described in models.Role.__to_json__() with the following keys added:
  • perms: All permissions of this role, as described in models.Role.get_all_permissions().
  • own: Is the given role the role of the current user.
Possible error responses:
 PermissionException – If the current user does not have the can_manage_site_users permission. (INCORRECT_PERMISSION)
rtype:JSONResponse[Sequence[Mapping[str, Any]]]
PATCH /api/v1/roles/(int: role_id)

Update the models.Permission of a given models.Role.

Parameters:
  • role_id (int) – The id of the (non course) role.
Response JSON Object:
 

An empty response with return code 204.

Request JSON Object:
 
  • permission (str) – The name of the permission to change.
  • value (bool) – The value to set the permission to (True means the specified role has the specified permission).
Possible error responses:
 

PermissionException – If the current user does not have the can_manage_site_users permission. (INCORRECT_PERMISSION)

rtype:EmptyResponse
PUT /api/v1/snippet

Add or modify a models.Snippet by key.

Response JSON Object:
 

A response containing the JSON serialized snippet and return code 201.

Request JSON Object:
 
  • value (str) – The new value of the snippet.
  • key (str) – The key of the new or existing snippet.
Possible error responses:
 
  • APIException – If the parameters “key” and/or “value” were not in the request. (MISSING_REQUIRED_PARAM)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not user snippets (INCORRECT_PERMISSION)
rtype:JSONResponse[Snippet]
GET /api/v1/snippets/

Get all snippets (models.Snippet) of the curren models.User.

Response JSON Object:
 

The an array containing all snippets for the currently logged in user.

Possible error responses:
 
rtype:JSONResponse[Sequence[Snippet]]
DELETE /api/v1/snippets/(int: snippet_id)

Delete the models.Snippet with the given id.

Parameters:
  • snippet_id (int) – The id of the snippet
Response JSON Object:
 

An empty response with return code 204

Possible error responses:
 
  • APIException – If the snippet with the given id does not exist. (OBJECT_ID_NOT_FOUND)
  • APIException – If the snippet does not belong the current user. (INCORRECT_PERMISSION)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not use snippets. (INCORRECT_PERMISSION)
rtype:EmptyResponse
PATCH /api/v1/snippets/(int: snippet_id)

Modify the models.Snippet with the given id.

Parameters:
  • snippet_id (int) – The id of the snippet to change.
Response JSON Object:
 

An empty response with return code 204.

Request JSON Object:
 
  • key (str) – The new key of the snippet.
  • value (str) – The new value of the snippet.
Possible error responses:
 
  • APIException – If the parameters “key” and/or “value” were not in the request. (MISSING_REQUIRED_PARAM)
  • APIException – If the snippet does not belong to the current user. (INCORRECT_PERMISSION)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not use snippets. (INCORRECT_PERMISSION)
rtype:EmptyResponse
DELETE /api/v1/submissions/(int: submission_id)

Delete a submission and all its files.

Warning

This is irreversible, so make sure the user really wants this!

Parameters:
  • submission_id – The submission to delete.
Response JSON Object:
 

Nothing

rtype:EmptyResponse
GET /api/v1/submissions/(int: submission_id)

Get the given submission (models.Work).

This API has some options based on the ‘type’ argument in the request

  • If type == 'zip' see get_zip()
  • If type == 'feedback' see submissions.get_feedback()
Parameters:
  • submission_id (int) – The id of the submission
Response JSON Object:
 

A response with the JSON serialized submission as content unless specified otherwise

Response JSON type:
 

flask.Response

Query Parameters:
 
  • owner (str) – The type of files to list, if set to teacher only teacher files will be listed, otherwise only student files will be listed.
Possible error responses:
 
  • APIException – If the submission with given id does not exist. (OBJECT_ID_NOT_FOUND)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the submission does not belong to the current user and the user can not see others work in the attached course. (INCORRECT_PERMISSION)
rtype:ExtendedJSONResponse[Union[Work, Mapping[str, str]]]
PATCH /api/v1/submissions/(int: submission_id)

Update the given submission (models.Work) if it already exists.

Parameters:
  • submission_id (int) – The id of the submission
Response JSON Object:
 

Empty response with return code 204

Response JSON Object:
 
  • grade (float) – The new grade, this can be null or float where null resets the grade or clears it. This field is optional
  • feedback (str) – The feedback for the student. This field is optional.
Possible error responses:
 
  • APIException – If the submission with the given id does not exist (OBJECT_ID_NOT_FOUND)
  • APIException – If the value of the “grade” parameter is not a float (INVALID_PARAM)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If user can not grade the submission with the given id (INCORRECT_PERMISSION)
rtype:JSONResponse[Work]
GET /api/v1/submissions/(int: submission_id)/feedbacks/

Get all feedback for a submission

Response JSON Object:
 
  • general – The general feedback given on this submission.
  • user – A mapping between file id and a mapping that is between line and feedback. So for example: {5: {0: 'Nice job!'}} means that file with id 5 has feedback on line 0.
  • linter – A mapping that is almost the same the user feedback mapping, only the final key is not a string but a list of tuples where the first item is the linter code and the second item is a models.LinterComment.
  • authors – The authors of the user feedback. In the example above the author of the feedback ‘Nice job!’ would be at {5: {0: $USER}}.
rtype:JSONResponse[Feedback]
POST /api/v1/submissions/(int: submission_id)/files/

Create a new file or directory for the given submission.

Parameters:
  • path (str) – The path of the new file to create. If the path ends in a forward slash a new directory is created and the body of the request is ignored, otherwise a regular file is created.
Response JSON Object:
 

Stat information about the new file, see files.get_stat_information()

Possible error responses:
 

APIException – If the request is bigger than the maximum upload size. (REQUEST_TOO_LARGE)

rtype:JSONResponse[Mapping[str, Any]]
GET /api/v1/submissions/(int: submission_id)/files/

Return the file directory info of a file of the given submission (models.Work).

The default file is the root of the submission, but a specific file can be specified with the file_id argument in the request.

Parameters:
  • submission_id (int) – The id of the submission
Response JSON Object:
 

A response with the JSON serialized directory structure as content and return code 200. For the exact structure see File.list_contents(). If path is given the return value will be stat datastructure, see files.get_stat_information().

Query Parameters:
 
  • file_id (int) – The file id of the directory to get. If this is not given the parent directory for the specified submission is used.
  • path (str) – The path that should be searched. The file_id query parameter is used if both file_id and path are present.
  • owner (str) – The type of files to list, if set to teacher only teacher files will be listed, otherwise only student files will be listed.
Possible error responses:
 
  • APIException – If the submission with the given id does not exist or when a file id was specified no file with this id exists. (OBJECT_ID_NOT_FOUND)
  • APIException – wWhen a file id is specified and the submission id does not match the submission id of the file. (INVALID_URL)
  • APIException – When a file id is specified and the file with that id is not a directory. (OBJECT_WRONG_TYPE)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If submission does not belong to the current user and the user can not view files in the attached course. (INCORRECT_PERMISSION)
rtype:Union[JSONResponse[FileTree], JSONResponse[Mapping[str, Any]]]
GET /api/v1/submissions/(int: submission_id)/grade_history/

Get the grade history for the given submission.

Response JSON Object:
 A list of models.GradeHistory object serialized to json for the given assignment.
Possible error responses:
 PermissionException – If the current user has no permission to see the grade history. (INCORRECT_PERMISSION)
rtype:JSONResponse[Sequence[GradeHistory]]
DELETE /api/v1/submissions/(int: submission_id)/grader

Change the assigned grader of the given submission.

Response JSON Object:
 Empty response and a 204 status.
Possible error responses:
 PermissionException – If the logged in user cannot manage the course of the submission. (INCORRECT_PERMISSION)
rtype:EmptyResponse
PATCH /api/v1/submissions/(int: submission_id)/grader

Change the assigned grader of the given submission.

Response JSON Object:
 

Empty response and a 204 status.

Response JSON Object:
 
  • user_id (int) – Id of the new grader. This is a required parameter.
Possible error responses:
 
  • PermissionException – If the logged in user cannot manage the course of the submission. (INCORRECT_PERMISSION)
  • APIException – If the new grader does not have the correct permission to grade this submission. (INCORRECT_PERMISSION)
rtype:EmptyResponse
PATCH /api/v1/submissions/(int: submission_id)/rubricitems/

Select the given rubric items for the given submission.

Parameters:
  • submission_id – The submission to unselect the item for.
Response JSON Object:
 
  • items (array) – The ids of the rubric items you want to select.
Response JSON Object:
 

Nothing.

Possible error responses:
 
  • APIException – If the assignment of a given item does not belong to the assignment of the given submission. of the submission (INVALID_PARAM).
  • PermissionException – If the current user cannot grace work (INCORRECT_PERMISSION).
rtype:EmptyResponse
DELETE /api/v1/submissions/(int: submission_id)/rubricitems/(int: rubric_item_id)

Unselect the given rubric item for the given submission.

Parameters:
  • submission_id – The submission to unselect the item for.
  • rubric_item_id – The rubric items id to unselect.
Response JSON Object:
 

Nothing.

rtype:EmptyResponse
PATCH /api/v1/submissions/(int: submission_id)/rubricitems/(int: rubricitem_id)

Select a rubric item of the given submission (models.Work).

Parameters:
  • submission_id (int) – The id of the submission
  • rubricitem_id (int) – The id of the rubric item
Response JSON Object:
 

Nothing.

Possible error responses:
 
  • APIException – If either the submission or rubric item with the given ids does not exist. (OBJECT_ID_NOT_FOUND)
  • APIException – If the assignment of the rubric is not the assignment of the submission. (INVALID_PARAM)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not grade the given submission (INCORRECT_PERMISSION)
rtype:EmptyResponse
GET /api/v1/submissions/(int: submission_id)/rubrics/

Return full rubric of the models.Assignment of the given submission (models.Work).

Parameters:
  • submission_id (int) – The id of the submission
Response JSON Object:
 

A response containing the JSON serialized rubric as described in Work.__rubric_to_json__().

Possible error responses:
 
  • APIException – If the submission with the given id does not exist. (OBJECT_ID_NOT_FOUND)
  • PermissionException – If there is no logged in user. (NOT_LOGGED_IN)
  • PermissionException – If the user can not see the assignment of the given submission. (INCORRECT_PERMISSION)
rtype:JSONResponse[Mapping[str, Any]]
POST /api/v1/user

Create a new models.User.

Request JSON Object:
 
  • username (str) – The username of the new user.
  • password (str) – The password of the new user.
  • email (str) – The email of the new user.
  • name (str) – The full name of the new user.
Response JSON Object:
 
  • access_token (str) – The JWT token that can be used to log in the newly created user.
Possible error responses:
 
  • APIException – If the not all given strings are at least 1 char. (INVALID_PARAM)
  • APIException – If there is already a user with the given username. (OBJECT_ALREADY_EXISTS)
  • APIException – If the given email is not a valid email. (INVALID_PARAM)
rtype:JSONResponse[Mapping[str, str]]
GET /api/v1/users/

Search for a user by name and username.

Query Parameters:
 
  • q (str) – The string to search for, all SQL wildcard are escaped and spaces are replaced by wildcards.
  • exclude_course (int) – Exclude all users that are in the given course from the search results. You need the permission can_list_course_users on this course to use this parameter.
Response JSON Object:
 

A list of models.User objects that match the given query string.

Possible error responses:
 
  • APIException – If the query string less than 3 characters long. (INVALID_PARAM)
  • PermissionException – If the currently logged in user does not have the permission can_search_users. (INCORRECT_PERMISSION)
  • RateLimitExceeded – If you hit this end point more than once per second. (RATE_LIMIT_EXCEEDED)
rtype:JSONResponse[Sequence[User]]
GET /static/(path: filename)

Function used internally to send static files from the static folder to the browser.

New in version 0.5.