Submissions API

API for accessing and updating submissions for an assignment. The submission id in these URLs is the id of the student in the course, there is no separate submission id exposed in these APIs.

All submission actions can be performed with either the course id, or the course section id. SIS ids can be used, prefixed by "siscourseid:" or "sissectionid:" as described in the API documentation on SIS IDs.

A MediaComment object looks like:

{
  
  "content-type": "audio/mp4",
  
  "display_name": "something",
  
  "media_id": "3232",
  
  "media_type": "audio",
  
  "url": "http://example.com/media_url"
}

A SubmissionComment object looks like:

{
  
  "id": 37,
  
  "author_id": 134,
  
  "author_name": "Toph Beifong",
  
  "comment": "Well here's the thing...",
  
  "created_at": "2012-01-01T01:00:00Z",
  
  "media_comment": ""
}

A Submission object looks like:

{
  
  //The submission's assignment id
  "assignment_id": 23,
  
  //The submission's assignment (see the assignments API) (optional)
  "assignment": "Assignment",
  
  //The submission's course (see the course API) (optional)
  "course": "Course",
  
  //This is the submission attempt number.
  "attempt": 1,
  
  //The content of the submission, if it was submitted directly in a text field.
  "body": "There are three factors too...",
  
  //The grade for the submission, translated into the assignment grading scheme (so
  //a letter grade, for example).
  "grade": "A-",
  
  //A boolean flag which is false if the student has re-submitted since the
  //submission was last graded.
  "grade_matches_current_submission": "true",
  
  //URL to the submission. This will require the user to log in.
  "html_url": "http://example.com/courses/255/assignments/543/submissions/134",
  
  //URL to the submission preview. This will require the user to log in.
  "preview_url": "http://example.com/courses/255/assignments/543/submissions/134?preview=1",
  
  //The raw score
  "score": "13.5",
  
  //Associated comments for a submission (optional)
  "submission_comments": "",
  
  //The types of submission ex:
  //('online_text_entry'|'online_url'|'online_upload'|'media_recording')
  "submission_type": "online_text_entry",
  
  //The timestamp when the assignment was submitted
  "submitted_at": "2012-01-01T01:00:00Z",
  
  //The URL of the submission (for 'online_url' submissions).
  "url": "",
  
  //The id of the user who created the submission
  "user_id": 134,
  
  //The id of the user who graded the submission
  "grader_id": 86,
  
  //The submissions user (see user API) (optional)
  "user": "User",
  
  //Whether the submission was made after the applicable due date
  "late": "false"
}

Submit an assignment SubmissionsController#create

POST /api/v1/courses/:course_id/assignments/:assignment_id/submissions

POST /api/v1/sections/:section_id/assignments/:assignment_id/submissions

Make a submission for an assignment. You must be enrolled as a student in the course/section to do this.

All online turn-in submission types are supported in this API. However, there are a few things that are not yet supported:

  • Files can be submitted based on a file ID of a user or group file. However, there is no API yet for listing the user and group files, or uploading new files via the API. A file upload API is coming soon.

  • Media comments can be submitted, however, there is no API yet for creating a media comment to submit.

  • Integration with Google Docs is not yet supported.

Request Parameters:

  • comment[text_comment]
    String

    Include a textual comment with the submission.

  • submission[submission_type]
    String, "online_text_entry"|"online_url"|"online_upload"|"media_recording"

    The type of submission being made. The assignment submission_types must include this submission type as an allowed option, or the submission will be rejected with a 400 error.

    The submission_type given determines which of the following parameters is used. For instance, to submit a URL, submission must be set to "online_url", otherwise the submission parameter will be ignored.

  • submission[body]
    String

    Submit the assignment as an HTML document snippet. Note this HTML snippet will be sanitized using the same ruleset as a submission made from the Canvas web UI. The sanitized HTML will be returned in the response as the submission body. Requires a submission_type of "online_text_entry".

  • submission[url]
    String

    Submit the assignment as a URL. The URL scheme must be "http" or "https", no "ftp" or other URL schemes are allowed. If no scheme is given (e.g. "www.example.com") then "http" will be assumed. Requires a submission_type of "online_url".

  • submission[file_ids][]
    Integer

    Submit the assignment as a set of one or more previously uploaded files residing in the submitting user's files section (or the group's files section, for group assignments).

    To upload a new file to submit, see the submissions Upload a file API.

    Requires a submission_type of "online_upload".

  • submission[media_comment_id]
    Integer

    The media comment id to submit. Media comment ids can be submitted via this API, however, note that there is not yet an API to generate or list existing media comments, so this functionality is currently of limited use.

    Requires a submission_type of "media_recording".

  • submission[media_comment_type]
    String, "audio"|"video"

    The type of media comment being submitted.

List assignment submissions SubmissionsApiController#index

GET /api/v1/courses/:course_id/assignments/:assignment_id/submissions

GET /api/v1/sections/:section_id/assignments/:assignment_id/submissions

Get all existing submissions for an assignment.

Request Parameters:

  • include[]
    String, "submission_history"|"submission_comments"|"rubric_assessment"|"assignment"

    Associations to include with the group.

API response field:

  • assignment_id

    The unique identifier for the assignment.

  • user_id

    The id of the user who submitted the assignment.

  • grader_id

    The id of the user who graded the assignment.

  • submitted_at

    The timestamp when the assignment was submitted, if an actual submission has been made.

  • score

    The raw score for the assignment submission.

  • attempt

    If multiple submissions have been made, this is the attempt number.

  • body

    The content of the submission, if it was submitted directly in a text field.

  • grade

    The grade for the submission, translated into the assignment grading scheme (so a letter grade, for example).

  • grade_matches_current_submission

    A boolean flag which is false if the student has re-submitted since the submission was last graded.

  • preview_url

    Link to the URL in canvas where the submission can be previewed. This will require the user to log in.

  • url

    If the submission was made as a URL.

  • late

    Whether the submission was made after the applicable due date.

List submissions for multiple assignments SubmissionsApiController#for_students

GET /api/v1/courses/:course_id/students/submissions

GET /api/v1/sections/:section_id/students/submissions

Get all existing submissions for a given set of students and assignments.

Request Parameters:

  • student_ids[]
    String

    List of student ids to return submissions for. If this argument is omitted, return submissions for the calling user. Students may only list their own submissions. Observers may only list those of associated students. The special id "all" will return submissions for all students in the course/section as appropriate.

  • assignment_ids[]
    String

    List of assignments to return submissions for. If none are given, submissions for all assignments are returned.

  • grouped
    Boolean

    If this argument is present, the response will be grouped by student, rather than a flat array of submissions.

  • include[]
    String, "submission_history"|"submission_comments"|"rubric_assessment"|"assignment"|"total_scores"

    Associations to include with the group. `total_scores` requires the `grouped` argument.

Example Response:

# Without grouped:

[
  { "assignment_id": 100, grade: 5, "user_id": 1, ... },
  { "assignment_id": 101, grade: 6, "user_id": 2, ... }

# With grouped:

[
  {
    "user_id": 1,
    "submissions": [
      { "assignment_id": 100, grade: 5, ... },
      { "assignment_id": 101, grade: 6, ... }
    ]
  }
]

Get a single submission SubmissionsApiController#show

GET /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id

GET /api/v1/sections/:section_id/assignments/:assignment_id/submissions/:user_id

Get a single submission, based on user id.

Request Parameters:

  • include[]
    String, "submission_history"|"submission_comments"|"rubric_assessment"

    Associations to include with the group.

Upload a file SubmissionsApiController#create_file

POST /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id/files

POST /api/v1/sections/:section_id/assignments/:assignment_id/submissions/:user_id/files

Upload a file to a submission.

This API endpoint is the first step in uploading a file to a submission as a student. See the File Upload Documentation for details on the file upload workflow.

The final step of the file upload workflow will return the attachment data, including the new file id. The caller can then POST to submit the online_upload assignment with these file ids.

Grade or comment on a submission SubmissionsApiController#update

PUT /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id

PUT /api/v1/sections/:section_id/assignments/:assignment_id/submissions/:user_id

Comment on and/or update the grading for a student's assignment submission. If any submission or rubric_assessment arguments are provided, the user must have permission to manage grades in the appropriate context (course or section).

Request Parameters:

  • comment[text_comment]
    String

    Add a textual comment to the submission.

  • comment[group_comment]
    Optional, Boolean

    Whether or not this comment should be sent to the entire group (defaults to false). Ignored if this is not a group assignment or if no text_comment is provided.

  • comment[media_comment_id]
    Integer

    Add an audio/video comment to the submission. Media comments can be added via this API, however, note that there is not yet an API to generate or list existing media comments, so this functionality is currently of limited use.

  • comment[media_comment_type]
    String, "audio"|"video"

    The type of media comment being added.

  • comment[file_ids][]
    Optional,Integer

    Attach files to this comment that were previously uploaded using the Submission Comment API's files action

  • submission[posted_grade]
    String

    Assign a score to the submission, updating both the "score" and "grade" fields on the submission record. This parameter can be passed in a few different formats:

    points

    A floating point or integral value, such as "13.5". The grade

    will be interpreted directly as the score of the assignment.
    Values above assignment.points_possible are allowed, for awarding
    extra credit.
    percentage

    A floating point value appended with a percent sign, such as

    "40%". The grade will be interpreted as a percentage score on the
    assignment, where 100% == assignment.points_possible. Values above 100%
    are allowed, for awarding extra credit.
    letter grade

    A letter grade, following the assignment's defined letter

    grading scheme. For example, "A-". The resulting score will be the high
    end of the defined range for the letter grade. For instance, if "B" is
    defined as 86% to 84%, a letter grade of "B" will be worth 86%. The
    letter grade will be rejected if the assignment does not have a defined
    letter grading scheme. For more fine-grained control of scores, pass in
    points or percentage rather than the letter grade.
    "pass/complete/fail/incomplete"

    A string value of "pass" or "complete"

    will give a score of 100%. "fail" or "incomplete" will give a score of
    0.

    Note that assignments with grading_type of "pass_fail" can only be assigned a score of 0 or assignment.points_possible, nothing inbetween. If a posted_grade in the "points" or "percentage" format is sent, the grade will only be accepted if the grade equals one of those two values.

  • rubric_assessment
    RubricAssessment

    Assign a rubric assessment to this assignment submission. The sub-parameters here depend on the rubric for the assignment. The general format is, for each row in the rubric:

    rubric_assessment[points]

    The points awarded for this row.

    rubric_assessment[comments]

    Comments to add for this row.

    For example, if the assignment rubric is (in JSON format):

    [
      {
        'id': 'crit1',
        'points': 10,
        'description': 'Criterion 1',
        'ratings':
        [
          { 'description': 'Good', 'points': 10 },
          { 'description': 'Poor', 'points': 3 }
        ]
      },
      {
        'id': 'crit2',
        'points': 5,
        'description': 'Criterion 2',
        'ratings':
        [
          { 'description': 'Complete', 'points': 5 },
          { 'description': 'Incomplete', 'points': 0 }
        ]
      }
    ]

    Then a possible set of values for rubric_assessment would be:

    rubric_assessment[crit1][points]=3&rubric_assessment[crit2][points]=5&rubric_assessment[crit2][comments]=Well%20Done.