Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Canvas LMS REST Submissions API
version: v1
summary: The complete Canvas LMS REST API, converted from the Swagger 1.2 documents Instructure publishes under https://canvas.instructure.com/doc/api/.
description: The Canvas LMS REST API covers courses, assignments, quizzes, grades, users, enrollments, accounts, files, modules, rubrics, submissions, SIS imports, LTI, analytics and account administration.
contact:
name: Instructure Canvas
url: https://canvas.instructure.com/doc/api/
license:
name: AGPL-3.0
url: https://github.com/instructure/canvas-lms/blob/master/LICENSE
servers:
- url: https://canvas.instructure.com/api
description: Instructure-hosted Canvas (canvas.instructure.com)
- url: https://{canvas_host}/api
description: Any Canvas instance; Canvas is multi-tenant and self-hostable, so the host is the institution's Canvas domain.
variables:
canvas_host:
default: canvas.instructure.com
description: Your institution's Canvas hostname, e.g. school.instructure.com
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Submissions
x-resource: submissions
externalDocs:
url: https://canvas.instructure.com/doc/api/submissions.html
paths:
/v1/courses/{course_id}/assignments/{assignment_id}/submissions:
post:
tags:
- Submissions
operationId: submit_assignment_courses
summary: Submit an assignment
description: 'Make a submission for an assignment. You must be actively enrolled as a student in
the course/section to do this. Concluded and pending enrollments are not permitted.
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 or through the {api:SubmissionsApiController#create_file file upload API}. However, there is no API yet for listing the user and group files.
* 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.'
parameters:
- name: course_id
in: path
schema:
type: string
required: true
description: ID
- name: assignment_id
in: path
schema:
type: string
required: true
description: ID
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
comment[text_comment]:
type: string
description: Include a textual comment with the submission.
submission[group_comment]:
type: boolean
description: '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.'
submission[submission_type]:
type: string
enum:
- online_text_entry
- online_url
- online_upload
- media_recording
- basic_lti_launch
- student_annotation
description: '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[submission_type]+ must be
set to "online_url", otherwise the +submission[url]+ parameter will be
ignored.
"basic_lti_launch" requires the assignment submission_type "online" or "external_tool"'
submission[body]:
type: string
description: '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]:
type: string
description: '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" or "basic_lti_launch".'
submission[file_ids]:
type: array
items:
type: integer
description: '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 {api:SubmissionsApiController#create_file Upload a file API}.
Requires a submission_type of "online_upload".'
submission[media_comment_id]:
type: string
description: '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]:
type: string
enum:
- audio
- video
description: The type of media comment being submitted.
submission[user_id]:
type: integer
format: int64
description: Submit on behalf of the given user. Requires grading permission.
submission[annotatable_attachment_id]:
type: integer
format: int64
description: 'The Attachment ID of the document being annotated. This should match
the annotatable_attachment_id on the assignment.
Requires a submission_type of "student_annotation".'
submission[submitted_at]:
type: string
format: date-time
description: Choose the time the submission is listed as submitted at. Requires grading permission.
required:
- submission[submission_type]
application/x-www-form-urlencoded:
schema:
type: object
properties:
comment[text_comment]:
type: string
description: Include a textual comment with the submission.
submission[group_comment]:
type: boolean
description: '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.'
submission[submission_type]:
type: string
enum:
- online_text_entry
- online_url
- online_upload
- media_recording
- basic_lti_launch
- student_annotation
description: '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[submission_type]+ must be
set to "online_url", otherwise the +submission[url]+ parameter will be
ignored.
"basic_lti_launch" requires the assignment submission_type "online" or "external_tool"'
submission[body]:
type: string
description: '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]:
type: string
description: '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" or "basic_lti_launch".'
submission[file_ids]:
type: array
items:
type: integer
description: '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 {api:SubmissionsApiController#create_file Upload a file API}.
Requires a submission_type of "online_upload".'
submission[media_comment_id]:
type: string
description: '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]:
type: string
enum:
- audio
- video
description: The type of media comment being submitted.
submission[user_id]:
type: integer
format: int64
description: Submit on behalf of the given user. Requires grading permission.
submission[annotatable_attachment_id]:
type: integer
format: int64
description: 'The Attachment ID of the document being annotated. This should match
the annotatable_attachment_id on the assignment.
Requires a submission_type of "student_annotation".'
submission[submitted_at]:
type: string
format: date-time
description: Choose the time the submission is listed as submitted at. Requires grading permission.
required:
- submission[submission_type]
responses:
'200':
description: Success, no content returned
externalDocs:
url: https://canvas.instructure.com/doc/api/submissions.html
get:
tags:
- Submissions
operationId: list_assignment_submissions_courses
summary: List assignment submissions
description: A paginated list of all existing submissions for an assignment.
parameters:
- name: course_id
in: path
schema:
type: string
required: true
description: ID
- name: assignment_id
in: path
schema:
type: string
required: true
description: ID
- name: include
in: query
schema:
type: array
items:
type: string
enum:
- submission_history
- submission_comments
- submission_html_comments
- rubric_assessment
- assignment
- visibility
- course
- user
- group
- read_status
- student_entered_score
required: false
description: Associations to include with the group. "group" will add group_id and group_name.
- name: grouped
in: query
schema:
type: boolean
required: false
description: If this argument is true, the response will be grouped by student groups.
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Submission__submissions'
externalDocs:
url: https://canvas.instructure.com/doc/api/submissions.html
/v1/sections/{section_id}/assignments/{assignment_id}/submissions:
post:
tags:
- Submissions
operationId: submit_assignment_sections
summary: Submit an assignment
description: 'Make a submission for an assignment. You must be actively enrolled as a student in
the course/section to do this. Concluded and pending enrollments are not permitted.
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 or through the {api:SubmissionsApiController#create_file file upload API}. However, there is no API yet for listing the user and group files.
* 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.'
parameters:
- name: section_id
in: path
schema:
type: string
required: true
description: ID
- name: assignment_id
in: path
schema:
type: string
required: true
description: ID
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
comment[text_comment]:
type: string
description: Include a textual comment with the submission.
submission[group_comment]:
type: boolean
description: '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.'
submission[submission_type]:
type: string
enum:
- online_text_entry
- online_url
- online_upload
- media_recording
- basic_lti_launch
- student_annotation
description: '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[submission_type]+ must be
set to "online_url", otherwise the +submission[url]+ parameter will be
ignored.
"basic_lti_launch" requires the assignment submission_type "online" or "external_tool"'
submission[body]:
type: string
description: '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]:
type: string
description: '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" or "basic_lti_launch".'
submission[file_ids]:
type: array
items:
type: integer
description: '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 {api:SubmissionsApiController#create_file Upload a file API}.
Requires a submission_type of "online_upload".'
submission[media_comment_id]:
type: string
description: '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]:
type: string
enum:
- audio
- video
description: The type of media comment being submitted.
submission[user_id]:
type: integer
format: int64
description: Submit on behalf of the given user. Requires grading permission.
submission[annotatable_attachment_id]:
type: integer
format: int64
description: 'The Attachment ID of the document being annotated. This should match
the annotatable_attachment_id on the assignment.
Requires a submission_type of "student_annotation".'
submission[submitted_at]:
type: string
format: date-time
description: Choose the time the submission is listed as submitted at. Requires grading permission.
required:
- submission[submission_type]
application/x-www-form-urlencoded:
schema:
type: object
properties:
comment[text_comment]:
type: string
description: Include a textual comment with the submission.
submission[group_comment]:
type: boolean
description: '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.'
submission[submission_type]:
type: string
enum:
- online_text_entry
- online_url
- online_upload
- media_recording
- basic_lti_launch
- student_annotation
description: '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[submission_type]+ must be
set to "online_url", otherwise the +submission[url]+ parameter will be
ignored.
"basic_lti_launch" requires the assignment submission_type "online" or "external_tool"'
submission[body]:
type: string
description: '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]:
type: string
description: '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" or "basic_lti_launch".'
submission[file_ids]:
type: array
items:
type: integer
description: '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 {api:SubmissionsApiController#create_file Upload a file API}.
Requires a submission_type of "online_upload".'
submission[media_comment_id]:
type: string
description: '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]:
type: string
enum:
- audio
- video
description: The type of media comment being submitted.
submission[user_id]:
type: integer
format: int64
description: Submit on behalf of the given user. Requires grading permission.
submission[annotatable_attachment_id]:
type: integer
format: int64
description: 'The Attachment ID of the document being annotated. This should match
the annotatable_attachment_id on the assignment.
Requires a submission_type of "student_annotation".'
submission[submitted_at]:
type: string
format: date-time
description: Choose the time the submission is listed as submitted at. Requires grading permission.
required:
- submission[submission_type]
responses:
'200':
description: Success, no content returned
externalDocs:
url: https://canvas.instructure.com/doc/api/submissions.html
get:
tags:
- Submissions
operationId: list_assignment_submissions_sections
summary: List assignment submissions
description: A paginated list of all existing submissions for an assignment.
parameters:
- name: section_id
in: path
schema:
type: string
required: true
description: ID
- name: assignment_id
in: path
schema:
type: string
required: true
description: ID
- name: include
in: query
schema:
type: array
items:
type: string
enum:
- submission_history
- submission_comments
- submission_html_comments
- rubric_assessment
- assignment
- visibility
- course
- user
- group
- read_status
- student_entered_score
required: false
description: Associations to include with the group. "group" will add group_id and group_name.
- name: grouped
in: query
schema:
type: boolean
required: false
description: If this argument is true, the response will be grouped by student groups.
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Submission__submissions'
externalDocs:
url: https://canvas.instructure.com/doc/api/submissions.html
/v1/courses/{course_id}/students/submissions:
get:
tags:
- Submissions
operationId: list_submissions_for_multiple_assignments_courses
summary: List submissions for multiple assignments
description: A paginated list of all existing submissions for a given set of students and assignments.
parameters:
- name: course_id
in: path
schema:
type: string
required: true
description: ID
- name: student_ids
in: query
schema:
type: array
items:
type: string
required: false
description: '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.'
- name: assignment_ids
in: query
schema:
type: array
items:
type: string
required: false
description: 'List of assignments to return submissions for. If none are given,
submissions for all assignments are returned.'
- name: grouped
in: query
schema:
type: boolean
required: false
description: 'If this argument is present, the response will be grouped by student,
rather than a flat array of submissions.'
- name: post_to_sis
in: query
schema:
type: boolean
required: false
description: 'If this argument is set to true, the response will only include
submissions for assignments that have the post_to_sis flag set to true and
user enrollments that were added through sis.'
- name: submitted_since
in: query
schema:
type: string
format: date-time
required: false
description: 'If this argument is set, the response will only include submissions that
were submitted after the specified date_time. This will exclude
submissions that do not have a submitted_at which will exclude unsubmitted
submissions.
The value must be formatted as ISO 8601 YYYY-MM-DDTHH:MM:SSZ.'
- name: graded_since
in: query
schema:
type: string
format: date-time
required: false
description: 'If this argument is set, the response will only include submissions that
were graded after the specified date_time. This will exclude
submissions that have not been graded.
The value must be formatted as ISO 8601 YYYY-MM-DDTHH:MM:SSZ.'
- name: grading_period_id
in: query
schema:
type: integer
format: int64
required: false
description: 'The id of the grading period in which submissions are being requested
(Requires grading periods to exist on the account)'
- name: workflow_state
in: query
schema:
type: string
enum:
- submitted
- unsubmitted
- graded
- pending_review
required: false
description: The current status of the submission
- name: enrollment_state
in: query
schema:
type: string
enum:
- active
- concluded
required: false
description: 'The current state of the enrollments. If omitted will include all
enrollments that are not deleted.'
- name: state_based_on_date
in: query
schema:
type: boolean
required: false
description: 'If omitted it is set to true. When set to false it will ignore the effective
state of the student enrollments and use the workflow_state for the
enrollments. The argument is ignored unless enrollment_state argument is
also passed.'
- name: order
in: query
schema:
type: string
enum:
- id
- graded_at
required: false
description: 'The order submissions will be returned in. Defaults to "id". Doesn''t
affect results for "grouped" mode.'
- name: order_direction
in: query
schema:
type: string
enum:
- ascending
- descending
required: false
description: 'Determines whether ordered results are returned in ascending or descending
order. Defaults to "ascending". Doesn''t affect results for "grouped" mode.'
- name: include
in: query
schema:
type: array
items:
type: string
enum:
- submission_history
- submission_comments
- submission_html_comments
- rubric_assessment
- assignment
- total_scores
- visibility
- course
- user
- sub_assignment_submissions
- peer_review_submissions
- student_entered_score
required: false
description: 'Associations to include with the group. `total_scores` requires the
`grouped` argument.'
responses:
'200':
description: Success, no content returned
externalDocs:
url: https://canvas.instructure.com/doc/api/submissions.html
/v1/sections/{section_id}/students/submissions:
get:
tags:
- Submissions
operationId: list_submissions_for_multiple_assignments_sections
summary: List submissions for multiple assignments
description: A paginated list of all existing submissions for a given set of students and assignments.
parameters:
- name: section_id
in: path
schema:
type: string
required: true
description: ID
- name: student_ids
in: query
schema:
type: array
items:
type: string
required: false
description: '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.'
- name: assignment_ids
in: query
schema:
type: array
items:
type: string
required: false
description: 'List of assignments to return submissions for. If none are given,
submissions for all assignments are returned.'
- name: grouped
in: query
schema:
type: boolean
required: false
description: 'If this argument is present, the response will be grouped by student,
rather than a flat array of submissions.'
- name: post_to_sis
in: query
schema:
type: boolean
required: false
description: 'If this argument is set to true, the response will only include
submissions for assignments that hav
# --- truncated at 32 KB (164 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/canvas/refs/heads/main/openapi/canvas-submissions-api-openapi.yml