openapi: 3.2.0 info: title: Canvas LMS REST Files 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: Files x-resource: files externalDocs: url: https://canvas.instructure.com/doc/api/files.html paths: /v1/courses/{course_id}/files: get: tags: - Files operationId: list_files_courses summary: List files description: Returns the paginated list of files for the folder or course. parameters: - name: course_id in: path schema: type: string required: true description: ID - name: content_types in: query schema: type: array items: type: string required: false description: 'Filter results by content-type. You can specify type/subtype pairs (e.g., ''image/jpeg''), or simply types (e.g., ''image'', which will match ''image/gif'', ''image/jpeg'', etc.).' - name: exclude_content_types in: query schema: type: array items: type: string required: false description: 'Exclude given content-types from your results. You can specify type/subtype pairs (e.g., ''image/jpeg''), or simply types (e.g., ''image'', which will match ''image/gif'', ''image/jpeg'', etc.).' - name: search_term in: query schema: type: string required: false description: The partial name of the files to match and return. - name: include in: query schema: type: array items: type: string enum: - user required: false description: 'Array of additional information to include. "user":: the user who uploaded the file or last edited its content "usage_rights":: copyright and license information for the file (see UsageRights)' - name: only in: query schema: type: array items: type: array items: {} required: false description: 'Array of information to restrict to. Overrides include[] "names":: only returns file name information' - name: sort in: query schema: type: string enum: - name - size - created_at - updated_at - content_type - user required: false description: Sort results by this field. Defaults to 'name'. Note that `sort=user` implies `include[]=user`. - name: order in: query schema: type: string enum: - asc - desc required: false description: The sorting order. Defaults to 'asc'. responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/File__files' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/courses/{course_id}/files/quota: get: tags: - Files operationId: get_quota_information_courses summary: Get quota information description: Returns the total and used storage quota for the course, group, or user. parameters: - name: course_id in: path schema: type: string required: true description: ID responses: '200': description: Success, no content returned externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/groups/{group_id}/files/quota: get: tags: - Files operationId: get_quota_information_groups summary: Get quota information description: Returns the total and used storage quota for the course, group, or user. parameters: - name: group_id in: path schema: type: string required: true description: ID responses: '200': description: Success, no content returned externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/users/{user_id}/files/quota: get: tags: - Files operationId: get_quota_information_users summary: Get quota information description: Returns the total and used storage quota for the course, group, or user. parameters: - name: user_id in: path schema: type: string required: true description: ID responses: '200': description: Success, no content returned externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/users/{user_id}/files: get: tags: - Files operationId: list_files_users summary: List files description: Returns the paginated list of files for the folder or course. parameters: - name: user_id in: path schema: type: string required: true description: ID - name: content_types in: query schema: type: array items: type: string required: false description: 'Filter results by content-type. You can specify type/subtype pairs (e.g., ''image/jpeg''), or simply types (e.g., ''image'', which will match ''image/gif'', ''image/jpeg'', etc.).' - name: exclude_content_types in: query schema: type: array items: type: string required: false description: 'Exclude given content-types from your results. You can specify type/subtype pairs (e.g., ''image/jpeg''), or simply types (e.g., ''image'', which will match ''image/gif'', ''image/jpeg'', etc.).' - name: search_term in: query schema: type: string required: false description: The partial name of the files to match and return. - name: include in: query schema: type: array items: type: string enum: - user required: false description: 'Array of additional information to include. "user":: the user who uploaded the file or last edited its content "usage_rights":: copyright and license information for the file (see UsageRights)' - name: only in: query schema: type: array items: type: array items: {} required: false description: 'Array of information to restrict to. Overrides include[] "names":: only returns file name information' - name: sort in: query schema: type: string enum: - name - size - created_at - updated_at - content_type - user required: false description: Sort results by this field. Defaults to 'name'. Note that `sort=user` implies `include[]=user`. - name: order in: query schema: type: string enum: - asc - desc required: false description: The sorting order. Defaults to 'asc'. responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/File__files' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/groups/{group_id}/files: get: tags: - Files operationId: list_files_groups summary: List files description: Returns the paginated list of files for the folder or course. parameters: - name: group_id in: path schema: type: string required: true description: ID - name: content_types in: query schema: type: array items: type: string required: false description: 'Filter results by content-type. You can specify type/subtype pairs (e.g., ''image/jpeg''), or simply types (e.g., ''image'', which will match ''image/gif'', ''image/jpeg'', etc.).' - name: exclude_content_types in: query schema: type: array items: type: string required: false description: 'Exclude given content-types from your results. You can specify type/subtype pairs (e.g., ''image/jpeg''), or simply types (e.g., ''image'', which will match ''image/gif'', ''image/jpeg'', etc.).' - name: search_term in: query schema: type: string required: false description: The partial name of the files to match and return. - name: include in: query schema: type: array items: type: string enum: - user required: false description: 'Array of additional information to include. "user":: the user who uploaded the file or last edited its content "usage_rights":: copyright and license information for the file (see UsageRights)' - name: only in: query schema: type: array items: type: array items: {} required: false description: 'Array of information to restrict to. Overrides include[] "names":: only returns file name information' - name: sort in: query schema: type: string enum: - name - size - created_at - updated_at - content_type - user required: false description: Sort results by this field. Defaults to 'name'. Note that `sort=user` implies `include[]=user`. - name: order in: query schema: type: string enum: - asc - desc required: false description: The sorting order. Defaults to 'asc'. responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/File__files' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/folders/{id}/files: get: tags: - Files operationId: list_files_folders summary: List files description: Returns the paginated list of files for the folder or course. parameters: - name: id in: path schema: type: string required: true description: ID - name: content_types in: query schema: type: array items: type: string required: false description: 'Filter results by content-type. You can specify type/subtype pairs (e.g., ''image/jpeg''), or simply types (e.g., ''image'', which will match ''image/gif'', ''image/jpeg'', etc.).' - name: exclude_content_types in: query schema: type: array items: type: string required: false description: 'Exclude given content-types from your results. You can specify type/subtype pairs (e.g., ''image/jpeg''), or simply types (e.g., ''image'', which will match ''image/gif'', ''image/jpeg'', etc.).' - name: search_term in: query schema: type: string required: false description: The partial name of the files to match and return. - name: include in: query schema: type: array items: type: string enum: - user required: false description: 'Array of additional information to include. "user":: the user who uploaded the file or last edited its content "usage_rights":: copyright and license information for the file (see UsageRights)' - name: only in: query schema: type: array items: type: array items: {} required: false description: 'Array of information to restrict to. Overrides include[] "names":: only returns file name information' - name: sort in: query schema: type: string enum: - name - size - created_at - updated_at - content_type - user required: false description: Sort results by this field. Defaults to 'name'. Note that `sort=user` implies `include[]=user`. - name: order in: query schema: type: string enum: - asc - desc required: false description: The sorting order. Defaults to 'asc'. responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/File__files' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/files/{id}/public_url: get: tags: - Files operationId: get_public_inline_preview_url summary: Get public inline preview url description: Determine the URL that should be used for inline preview of the file. parameters: - name: id in: path schema: type: string required: true description: ID - name: submission_id in: query schema: type: integer format: int64 required: false description: 'The id of the submission the file is associated with. Provide this argument to gain access to a file that has been submitted to an assignment (Canvas will verify that the file belongs to the submission and the calling user has rights to view the submission).' responses: '200': description: Success, no content returned externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/files/{id}: get: tags: - Files operationId: get_file_files summary: Get file description: Returns the standard attachment json object parameters: - name: id in: path schema: type: string required: true description: ID - name: include in: query schema: type: array items: type: string enum: - user required: false description: 'Array of additional information to include. "user":: the user who uploaded the file or last edited its content "usage_rights":: copyright and license information for the file (see UsageRights)' - name: replacement_chain_context_type in: query schema: type: string required: false description: '[DEPRECATED] When a user replaces a file during upload, Canvas keeps track of the "replacement chain." Include this parameter if you wish Canvas to follow the replacement chain if the requested file was deleted and replaced by another. Must be set to ''course'' or ''account''. The "replacement_chain_context_id" parameter must also be included.' - name: replacement_chain_context_id in: query schema: type: integer format: int64 required: false description: '[DEPRECATED] When a user replaces a file during upload, Canvas keeps track of the "replacement chain." Include this parameter if you wish Canvas to follow the replacement chain if the requested file was deleted and replaced by another. Indicates the context ID Canvas should use when following the "replacement chain." The "replacement_chain_context_type" parameter must also be included.' responses: '200': description: Success content: application/json: schema: type: string format: binary externalDocs: url: https://canvas.instructure.com/doc/api/files.html put: tags: - Files operationId: update_file summary: Update file description: Update some settings on the specified file parameters: - name: id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: The new display name of the file, with a limit of 255 characters. parent_folder_id: type: string description: 'The id of the folder to move this file into. The new folder must be in the same context as the original parent folder. If the file is in a context without folders this does not apply.' on_duplicate: type: string enum: - overwrite - rename description: 'If the file is moved to a folder containing a file with the same name, or renamed to a name matching an existing file, the API call will fail unless this parameter is supplied. "overwrite":: Replace the existing file with the same name "rename":: Add a qualifier to make the new filename unique' lock_at: type: string format: date-time description: The datetime to lock the file at unlock_at: type: string format: date-time description: The datetime to unlock the file at locked: type: boolean description: Flag the file as locked hidden: type: boolean description: Flag the file as hidden visibility_level: type: string description: Configure which roles can access this file application/x-www-form-urlencoded: schema: type: object properties: name: type: string description: The new display name of the file, with a limit of 255 characters. parent_folder_id: type: string description: 'The id of the folder to move this file into. The new folder must be in the same context as the original parent folder. If the file is in a context without folders this does not apply.' on_duplicate: type: string enum: - overwrite - rename description: 'If the file is moved to a folder containing a file with the same name, or renamed to a name matching an existing file, the API call will fail unless this parameter is supplied. "overwrite":: Replace the existing file with the same name "rename":: Add a qualifier to make the new filename unique' lock_at: type: string format: date-time description: The datetime to lock the file at unlock_at: type: string format: date-time description: The datetime to unlock the file at locked: type: boolean description: Flag the file as locked hidden: type: boolean description: Flag the file as hidden visibility_level: type: string description: Configure which roles can access this file responses: '200': description: Success content: application/json: schema: type: string format: binary externalDocs: url: https://canvas.instructure.com/doc/api/files.html delete: tags: - Files operationId: delete_file summary: Delete file description: 'Remove the specified file. Unlike most other DELETE endpoints, using this endpoint will result in comprehensive, irretrievable destruction of the file. It should be used with the `replace` parameter set to true in cases where the file preview also needs to be destroyed (such as to remove files that violate privacy laws).' parameters: - name: id in: path schema: type: string required: true description: ID - name: replace in: query schema: type: boolean required: false description: 'This action is irreversible. If replace is set to true the file contents will be replaced with a generic "file has been removed" file. This also destroys any previews that have been generated for the file. Must have manage files and become other users permissions' responses: '200': description: Success content: application/json: schema: type: string format: binary externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/courses/{course_id}/files/{id}: get: tags: - Files operationId: get_file_courses summary: Get file description: Returns the standard attachment json object parameters: - name: course_id in: path schema: type: string required: true description: ID - name: id in: path schema: type: string required: true description: ID - name: include in: query schema: type: array items: type: string enum: - user required: false description: 'Array of additional information to include. "user":: the user who uploaded the file or last edited its content "usage_rights":: copyright and license information for the file (see UsageRights)' - name: replacement_chain_context_type in: query schema: type: string required: false description: '[DEPRECATED] When a user replaces a file during upload, Canvas keeps track of the "replacement chain." Include this parameter if you wish Canvas to follow the replacement chain if the requested file was deleted and replaced by another. Must be set to ''course'' or ''account''. The "replacement_chain_context_id" parameter must also be included.' - name: replacement_chain_context_id in: query schema: type: integer format: int64 required: false description: '[DEPRECATED] When a user replaces a file during upload, Canvas keeps track of the "replacement chain." Include this parameter if you wish Canvas to follow the replacement chain if the requested file was deleted and replaced by another. Indicates the context ID Canvas should use when following the "replacement chain." The "replacement_chain_context_type" parameter must also be included.' responses: '200': description: Success content: application/json: schema: type: string format: binary externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/groups/{group_id}/files/{id}: get: tags: - Files operationId: get_file_groups summary: Get file description: Returns the standard attachment json object parameters: - name: group_id in: path schema: type: string required: true description: ID - name: id in: path schema: type: string required: true description: ID - name: include in: query schema: type: array items: type: string enum: - user required: false description: 'Array of additional information to include. "user":: the user who uploaded the file or last edited its content "usage_rights":: copyright and license information for the file (see UsageRights)' - name: replacement_chain_context_type in: query schema: type: string required: false description: '[DEPRECATED] When a user replaces a file during upload, Canvas keeps track of the "replacement chain." Include this parameter if you wish Canvas to follow the replacement chain if the requested file was deleted and replaced by another. Must be set to ''course'' or ''account''. The "replacement_chain_context_id" parameter must also be included.' - name: replacement_chain_context_id in: query schema: type: integer format: int64 required: false description: '[DEPRECATED] When a user replaces a file during upload, Canvas keeps track of the "replacement chain." Include this parameter if you wish Canvas to follow the replacement chain if the requested file was deleted and replaced by another. Indicates the context ID Canvas should use when following the "replacement chain." The "replacement_chain_context_type" parameter must also be included.' responses: '200': description: Success content: application/json: schema: type: string format: binary externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/users/{user_id}/files/{id}: get: tags: - Files operationId: get_file_users summary: Get file description: Returns the standard attachment json object parameters: - name: user_id in: path schema: type: string required: true description: ID - name: id in: path schema: type: string required: true description: ID - name: include in: query schema: type: array items: type: string enum: - user required: false description: 'Array of additional information to include. "user":: the user who uploaded the file or last edited its content "usage_rights":: copyright and license information for the file (see UsageRights)' - name: replacement_chain_context_type in: query schema: type: string required: false description: '[DEPRECATED] When a user replaces a file during upload, Canvas keeps track of the "replacement chain." Include this parameter if you wish Canvas to follow the replacement chain if the requested file was deleted and replaced by another. Must be set to ''course'' or ''account''. The "replacement_chain_context_id" parameter must also be included.' - name: replacement_chain_context_id in: query schema: type: integer format: int64 required: false description: '[DEPRECATED] When a user replaces a file during upload, Canvas keeps track of the "replacement chain." Include this parameter if you wish Canvas to follow the replacement chain if the requested file was deleted and replaced by another. Indicates the context ID Canvas should use when following the "replacement chain." The "replacement_chain_context_type" parameter must also be included.' responses: '200': description: Success content: application/json: schema: type: string format: binary externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/courses/{course_id}/files/file_ref/{migration_id}: get: tags: - Files operationId: translate_file_reference summary: Translate file reference description: Get information about a file from a course copy file reference parameters: - name: course_id in: path schema: type: string required: true description: ID - name: migration_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: string format: binary externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/files/{id}/icon_metadata: get: tags: - Files operationId: get_icon_metadata summary: Get icon metadata description: Returns the icon maker file attachment metadata parameters: - name: id in: path schema: type: string required: true description: ID responses: '200': description: Success, no content returned externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/files/{id}/reset_verifier: post: tags: - Files operationId: reset_link_verifier summary: Reset link verifier description: 'Resets the link verifier. Any existing links to the file using the previous hard-coded "verifier" parameter will no longer automatically grant access. Must have manage files and become other users permissions' parameters: - name: id in: path schema: type: string required: true description: ID deprecated: true responses: '200': description: Success content: application/json: schema: type: string format: binary externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/files/update_word_count: post: tags: - Files operationId: update_word_count summary: Update word count description: 'Update the word count for a submission''s attachment. This endpoint is designed to be called by external document viewers (like DocViewer) to report word counts back to Canvas.' requestBody: required: false content: application/json: schema: type: object properties: attachment_jwt: type: string description: JWT token containing the id of the attachment word_count: type: integer format: int64 description: The word count to set on the attachment. required: - attachment_jwt - word_count application/x-www-form-urlencoded: schema: type: object properties: attachment_jwt: type: string description: JWT token containing the id of the attachment word_count: type: integer format: int64 description: The word count to set on the attachment. required: - attachment_jwt - word_count responses: '200': description: Success, no content returned externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/folders/{id}/folders: get: tags: - Files operationId: list_folders summary: List folders description: Returns the paginated list of folders in the folder. parameters: - name: id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/courses/{course_id}/folders: get: tags: - Files operationId: list_all_folders_courses summary: List all folders description: 'Returns the paginated list of all folders for the given context. This will be returned as a flat list containing all subfolders as well.' parameters: - name: course_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html post: tags: - Files operationId: create_folder_courses summary: Create folder description: Creates a folder in the specified context parameters: - name: course_id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: The name of the folder parent_folder_id: type: string description: The id of the folder to store the new folder in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used. parent_folder_path: type: string description: The path of the folder to store the new folder in. The path separator is the forward slash `/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder required: - name application/x-www-form-urlencoded: schema: type: object properties: name: type: string description: The name of the folder parent_folder_id: type: string description: The id of the folder to store the new folder in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used. parent_folder_path: type: string description: The path of the folder to store the new folder in. The path separator is the forward slash `/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder required: - name responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/users/{user_id}/folders: get: tags: - Files operationId: list_all_folders_users summary: List all folders description: 'Returns the paginated list of all folders for the given context. This will be returned as a flat list containing all subfolders as well.' parameters: - name: user_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html post: tags: - Files operationId: create_folder_users summary: Create folder description: Creates a folder in the specified context parameters: - name: user_id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: The name of the folder parent_folder_id: type: string description: The id of the folder to store the new folder in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used. parent_folder_path: type: string description: The path of the folder to store the new folder in. The path separator is the forward slash `/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder required: - name application/x-www-form-urlencoded: schema: type: object properties: name: type: string description: The name of the folder parent_folder_id: type: string description: The id of the folder to store the new folder in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used. parent_folder_path: type: string description: The path of the folder to store the new folder in. The path separator is the forward slash `/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder required: - name responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/groups/{group_id}/folders: get: tags: - Files operationId: list_all_folders_groups summary: List all folders description: 'Returns the paginated list of all folders for the given context. This will be returned as a flat list containing all subfolders as well.' parameters: - name: group_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html post: tags: - Files operationId: create_folder_groups summary: Create folder description: Creates a folder in the specified context parameters: - name: group_id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: The name of the folder parent_folder_id: type: string description: The id of the folder to store the new folder in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used. parent_folder_path: type: string description: The path of the folder to store the new folder in. The path separator is the forward slash `/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder required: - name application/x-www-form-urlencoded: schema: type: object properties: name: type: string description: The name of the folder parent_folder_id: type: string description: The id of the folder to store the new folder in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used. parent_folder_path: type: string description: The path of the folder to store the new folder in. The path separator is the forward slash `/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder required: - name responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/courses/{course_id}/folders/by_path/*full_path: get: tags: - Files operationId: resolve_path_courses_full_path summary: Resolve path description: 'Given the full path to a folder, returns a list of all Folders in the path hierarchy, starting at the root folder, and ending at the requested folder. The given path is relative to the context''s root folder and does not include the root folder''s name (e.g., "course files"). If an empty path is given, the context''s root folder alone is returned. Otherwise, if no folder exists with the given full path, a Not Found error is returned.' parameters: - name: course_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/courses/{course_id}/folders/by_path: get: tags: - Files operationId: resolve_path_courses summary: Resolve path description: 'Given the full path to a folder, returns a list of all Folders in the path hierarchy, starting at the root folder, and ending at the requested folder. The given path is relative to the context''s root folder and does not include the root folder''s name (e.g., "course files"). If an empty path is given, the context''s root folder alone is returned. Otherwise, if no folder exists with the given full path, a Not Found error is returned.' parameters: - name: course_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/users/{user_id}/folders/by_path/*full_path: get: tags: - Files operationId: resolve_path_users_full_path summary: Resolve path description: 'Given the full path to a folder, returns a list of all Folders in the path hierarchy, starting at the root folder, and ending at the requested folder. The given path is relative to the context''s root folder and does not include the root folder''s name (e.g., "course files"). If an empty path is given, the context''s root folder alone is returned. Otherwise, if no folder exists with the given full path, a Not Found error is returned.' parameters: - name: user_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/users/{user_id}/folders/by_path: get: tags: - Files operationId: resolve_path_users summary: Resolve path description: 'Given the full path to a folder, returns a list of all Folders in the path hierarchy, starting at the root folder, and ending at the requested folder. The given path is relative to the context''s root folder and does not include the root folder''s name (e.g., "course files"). If an empty path is given, the context''s root folder alone is returned. Otherwise, if no folder exists with the given full path, a Not Found error is returned.' parameters: - name: user_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/groups/{group_id}/folders/by_path/*full_path: get: tags: - Files operationId: resolve_path_groups_full_path summary: Resolve path description: 'Given the full path to a folder, returns a list of all Folders in the path hierarchy, starting at the root folder, and ending at the requested folder. The given path is relative to the context''s root folder and does not include the root folder''s name (e.g., "course files"). If an empty path is given, the context''s root folder alone is returned. Otherwise, if no folder exists with the given full path, a Not Found error is returned.' parameters: - name: group_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/groups/{group_id}/folders/by_path: get: tags: - Files operationId: resolve_path_groups summary: Resolve path description: 'Given the full path to a folder, returns a list of all Folders in the path hierarchy, starting at the root folder, and ending at the requested folder. The given path is relative to the context''s root folder and does not include the root folder''s name (e.g., "course files"). If an empty path is given, the context''s root folder alone is returned. Otherwise, if no folder exists with the given full path, a Not Found error is returned.' parameters: - name: group_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/courses/{course_id}/folders/{id}: get: tags: - Files operationId: get_folder_courses summary: Get folder description: 'Returns the details for a folder You can get the root folder from a context by using ''root'' as the :id. For example, you could get the root folder for a course like:' parameters: - name: course_id in: path schema: type: string required: true description: ID - name: id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/users/{user_id}/folders/{id}: get: tags: - Files operationId: get_folder_users summary: Get folder description: 'Returns the details for a folder You can get the root folder from a context by using ''root'' as the :id. For example, you could get the root folder for a course like:' parameters: - name: user_id in: path schema: type: string required: true description: ID - name: id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/groups/{group_id}/folders/{id}: get: tags: - Files operationId: get_folder_groups summary: Get folder description: 'Returns the details for a folder You can get the root folder from a context by using ''root'' as the :id. For example, you could get the root folder for a course like:' parameters: - name: group_id in: path schema: type: string required: true description: ID - name: id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/folders/{id}: get: tags: - Files operationId: get_folder_folders summary: Get folder description: 'Returns the details for a folder You can get the root folder from a context by using ''root'' as the :id. For example, you could get the root folder for a course like:' parameters: - name: id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html put: tags: - Files operationId: update_folder summary: Update folder description: Updates a folder parameters: - name: id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: The new name of the folder parent_folder_id: type: string description: The id of the folder to move this folder into. The new folder must be in the same context as the original parent folder. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder application/x-www-form-urlencoded: schema: type: object properties: name: type: string description: The new name of the folder parent_folder_id: type: string description: The id of the folder to move this folder into. The new folder must be in the same context as the original parent folder. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html delete: tags: - Files operationId: delete_folder summary: Delete folder description: 'Remove the specified folder. You can only delete empty folders unless you set the ''force'' flag' parameters: - name: id in: path schema: type: string required: true description: ID - name: force in: query schema: type: boolean required: false description: Set to 'true' to allow deleting a non-empty folder responses: '200': description: Success, no content returned externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/folders/{folder_id}/folders: post: tags: - Files operationId: create_folder_folders summary: Create folder description: Creates a folder in the specified context parameters: - name: folder_id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: The name of the folder parent_folder_id: type: string description: The id of the folder to store the new folder in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used. parent_folder_path: type: string description: The path of the folder to store the new folder in. The path separator is the forward slash `/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder required: - name application/x-www-form-urlencoded: schema: type: object properties: name: type: string description: The name of the folder parent_folder_id: type: string description: The id of the folder to store the new folder in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used. parent_folder_path: type: string description: The path of the folder to store the new folder in. The path separator is the forward slash `/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder required: - name responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/accounts/{account_id}/folders: post: tags: - Files operationId: create_folder_accounts summary: Create folder description: Creates a folder in the specified context parameters: - name: account_id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: The name of the folder parent_folder_id: type: string description: The id of the folder to store the new folder in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used. parent_folder_path: type: string description: The path of the folder to store the new folder in. The path separator is the forward slash `/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder required: - name application/x-www-form-urlencoded: schema: type: object properties: name: type: string description: The name of the folder parent_folder_id: type: string description: The id of the folder to store the new folder in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used. parent_folder_path: type: string description: The path of the folder to store the new folder in. The path separator is the forward slash `/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used. lock_at: type: string format: date-time description: The datetime to lock the folder at unlock_at: type: string format: date-time description: The datetime to unlock the folder at locked: type: boolean description: Flag the folder as locked hidden: type: boolean description: Flag the folder as hidden position: type: integer format: int64 description: Set an explicit sort position for the folder required: - name responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/folders/{folder_id}/files: post: tags: - Files operationId: upload_file_files summary: Upload a file description: 'Upload a file to a folder. This API endpoint is the first step in uploading a file. See the {file:file.file_uploads.html File Upload Documentation} for details on the file upload workflow. Only those with the "Manage Files" permission on a course or group can upload files to a folder in that course or group.' parameters: - name: folder_id in: path schema: type: string required: true description: ID responses: '200': description: Success, no content returned externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/folders/{dest_folder_id}/copy_file: post: tags: - Files operationId: copy_file summary: Copy a file description: 'Copy a file from elsewhere in Canvas into a folder. Copying a file across contexts (between courses and users) is permitted, but the source and destination must belong to the same institution.' parameters: - name: dest_folder_id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: source_file_id: type: string description: The id of the source file on_duplicate: type: string enum: - overwrite - rename description: 'What to do if a file with the same name already exists at the destination. If such a file exists and this parameter is not given, the call will fail. "overwrite":: Replace an existing file with the same name "rename":: Add a qualifier to make the new filename unique' required: - source_file_id application/x-www-form-urlencoded: schema: type: object properties: source_file_id: type: string description: The id of the source file on_duplicate: type: string enum: - overwrite - rename description: 'What to do if a file with the same name already exists at the destination. If such a file exists and this parameter is not given, the call will fail. "overwrite":: Replace an existing file with the same name "rename":: Add a qualifier to make the new filename unique' required: - source_file_id responses: '200': description: Success content: application/json: schema: type: string format: binary externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/folders/{dest_folder_id}/copy_folder: post: tags: - Files operationId: copy_folder summary: Copy a folder description: 'Copy a folder (and its contents) from elsewhere in Canvas into a folder. Copying a folder across contexts (between courses and users) is permitted, but the source and destination must belong to the same institution. If the source and destination folders are in the same context, the source folder may not contain the destination folder. A folder will be renamed at its destination if another folder with the same name already exists.' parameters: - name: dest_folder_id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: source_folder_id: type: string description: The id of the source folder required: - source_folder_id application/x-www-form-urlencoded: schema: type: object properties: source_folder_id: type: string description: The id of the source folder required: - source_folder_id responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/courses/{course_id}/folders/media: get: tags: - Files operationId: get_uploaded_media_folder_for_user_courses summary: Get uploaded media folder for user description: 'Returns the details for a designated upload folder that the user has rights to upload to, and creates it if it doesn''t exist. If the current user does not have the permissions to manage files in the course or group, the folder will belong to the current user directly.' parameters: - name: course_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/groups/{group_id}/folders/media: get: tags: - Files operationId: get_uploaded_media_folder_for_user_groups summary: Get uploaded media folder for user description: 'Returns the details for a designated upload folder that the user has rights to upload to, and creates it if it doesn''t exist. If the current user does not have the permissions to manage files in the course or group, the folder will belong to the current user directly.' parameters: - name: group_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Folder' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/courses/{course_id}/usage_rights: put: tags: - Files operationId: set_usage_rights_courses summary: Set usage rights description: Sets copyright and license information for one or more files parameters: - name: course_id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: file_ids: type: array items: type: string description: List of ids of files to set usage rights for. folder_ids: type: array items: type: string description: 'List of ids of folders to search for files to set usage rights for. Note that new files uploaded to these folders do not automatically inherit these rights.' publish: type: boolean description: Whether the file(s) or folder(s) should be published on save, provided that usage rights have been specified (set to `true` to publish on save). usage_rights[use_justification]: type: string enum: - own_copyright - used_by_permission - fair_use - public_domain - creative_commons description: The intellectual property justification for using the files in Canvas usage_rights[legal_copyright]: type: string description: The legal copyright line for the files usage_rights[license]: type: string description: The license that applies to the files. See the {api:UsageRightsController#licenses List licenses endpoint} for the supported license types. required: - file_ids - usage_rights[use_justification] application/x-www-form-urlencoded: schema: type: object properties: file_ids: type: array items: type: string description: List of ids of files to set usage rights for. folder_ids: type: array items: type: string description: 'List of ids of folders to search for files to set usage rights for. Note that new files uploaded to these folders do not automatically inherit these rights.' publish: type: boolean description: Whether the file(s) or folder(s) should be published on save, provided that usage rights have been specified (set to `true` to publish on save). usage_rights[use_justification]: type: string enum: - own_copyright - used_by_permission - fair_use - public_domain - creative_commons description: The intellectual property justification for using the files in Canvas usage_rights[legal_copyright]: type: string description: The legal copyright line for the files usage_rights[license]: type: string description: The license that applies to the files. See the {api:UsageRightsController#licenses List licenses endpoint} for the supported license types. required: - file_ids - usage_rights[use_justification] responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UsageRights' externalDocs: url: https://canvas.instructure.com/doc/api/files.html delete: tags: - Files operationId: remove_usage_rights_courses summary: Remove usage rights description: Removes copyright and license information associated with one or more files parameters: - name: course_id in: path schema: type: string required: true description: ID - name: file_ids in: query schema: type: array items: type: string required: true description: List of ids of files to remove associated usage rights from. - name: folder_ids in: query schema: type: array items: type: string required: false description: List of ids of folders. Usage rights will be removed from all files in these folders. responses: '200': description: Success, no content returned externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/groups/{group_id}/usage_rights: put: tags: - Files operationId: set_usage_rights_groups summary: Set usage rights description: Sets copyright and license information for one or more files parameters: - name: group_id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: file_ids: type: array items: type: string description: List of ids of files to set usage rights for. folder_ids: type: array items: type: string description: 'List of ids of folders to search for files to set usage rights for. Note that new files uploaded to these folders do not automatically inherit these rights.' publish: type: boolean description: Whether the file(s) or folder(s) should be published on save, provided that usage rights have been specified (set to `true` to publish on save). usage_rights[use_justification]: type: string enum: - own_copyright - used_by_permission - fair_use - public_domain - creative_commons description: The intellectual property justification for using the files in Canvas usage_rights[legal_copyright]: type: string description: The legal copyright line for the files usage_rights[license]: type: string description: The license that applies to the files. See the {api:UsageRightsController#licenses List licenses endpoint} for the supported license types. required: - file_ids - usage_rights[use_justification] application/x-www-form-urlencoded: schema: type: object properties: file_ids: type: array items: type: string description: List of ids of files to set usage rights for. folder_ids: type: array items: type: string description: 'List of ids of folders to search for files to set usage rights for. Note that new files uploaded to these folders do not automatically inherit these rights.' publish: type: boolean description: Whether the file(s) or folder(s) should be published on save, provided that usage rights have been specified (set to `true` to publish on save). usage_rights[use_justification]: type: string enum: - own_copyright - used_by_permission - fair_use - public_domain - creative_commons description: The intellectual property justification for using the files in Canvas usage_rights[legal_copyright]: type: string description: The legal copyright line for the files usage_rights[license]: type: string description: The license that applies to the files. See the {api:UsageRightsController#licenses List licenses endpoint} for the supported license types. required: - file_ids - usage_rights[use_justification] responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UsageRights' externalDocs: url: https://canvas.instructure.com/doc/api/files.html delete: tags: - Files operationId: remove_usage_rights_groups summary: Remove usage rights description: Removes copyright and license information associated with one or more files parameters: - name: group_id in: path schema: type: string required: true description: ID - name: file_ids in: query schema: type: array items: type: string required: true description: List of ids of files to remove associated usage rights from. - name: folder_ids in: query schema: type: array items: type: string required: false description: List of ids of folders. Usage rights will be removed from all files in these folders. responses: '200': description: Success, no content returned externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/users/{user_id}/usage_rights: put: tags: - Files operationId: set_usage_rights_users summary: Set usage rights description: Sets copyright and license information for one or more files parameters: - name: user_id in: path schema: type: string required: true description: ID requestBody: required: false content: application/json: schema: type: object properties: file_ids: type: array items: type: string description: List of ids of files to set usage rights for. folder_ids: type: array items: type: string description: 'List of ids of folders to search for files to set usage rights for. Note that new files uploaded to these folders do not automatically inherit these rights.' publish: type: boolean description: Whether the file(s) or folder(s) should be published on save, provided that usage rights have been specified (set to `true` to publish on save). usage_rights[use_justification]: type: string enum: - own_copyright - used_by_permission - fair_use - public_domain - creative_commons description: The intellectual property justification for using the files in Canvas usage_rights[legal_copyright]: type: string description: The legal copyright line for the files usage_rights[license]: type: string description: The license that applies to the files. See the {api:UsageRightsController#licenses List licenses endpoint} for the supported license types. required: - file_ids - usage_rights[use_justification] application/x-www-form-urlencoded: schema: type: object properties: file_ids: type: array items: type: string description: List of ids of files to set usage rights for. folder_ids: type: array items: type: string description: 'List of ids of folders to search for files to set usage rights for. Note that new files uploaded to these folders do not automatically inherit these rights.' publish: type: boolean description: Whether the file(s) or folder(s) should be published on save, provided that usage rights have been specified (set to `true` to publish on save). usage_rights[use_justification]: type: string enum: - own_copyright - used_by_permission - fair_use - public_domain - creative_commons description: The intellectual property justification for using the files in Canvas usage_rights[legal_copyright]: type: string description: The legal copyright line for the files usage_rights[license]: type: string description: The license that applies to the files. See the {api:UsageRightsController#licenses List licenses endpoint} for the supported license types. required: - file_ids - usage_rights[use_justification] responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UsageRights' externalDocs: url: https://canvas.instructure.com/doc/api/files.html delete: tags: - Files operationId: remove_usage_rights_users summary: Remove usage rights description: Removes copyright and license information associated with one or more files parameters: - name: user_id in: path schema: type: string required: true description: ID - name: file_ids in: query schema: type: array items: type: string required: true description: List of ids of files to remove associated usage rights from. - name: folder_ids in: query schema: type: array items: type: string required: false description: List of ids of folders. Usage rights will be removed from all files in these folders. responses: '200': description: Success, no content returned externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/courses/{course_id}/content_licenses: get: tags: - Files operationId: list_licenses_courses summary: List licenses description: A paginated list of licenses that can be applied parameters: - name: course_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/License' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/groups/{group_id}/content_licenses: get: tags: - Files operationId: list_licenses_groups summary: List licenses description: A paginated list of licenses that can be applied parameters: - name: group_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/License' externalDocs: url: https://canvas.instructure.com/doc/api/files.html /v1/users/{user_id}/content_licenses: get: tags: - Files operationId: list_licenses_users summary: List licenses description: A paginated list of licenses that can be applied parameters: - name: user_id in: path schema: type: string required: true description: ID responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/License' externalDocs: url: https://canvas.instructure.com/doc/api/files.html components: schemas: File__files: type: object properties: id: type: integer example: 569 folder_id: type: integer example: 4207 display_name: type: string example: file.txt filename: type: string example: file.txt content-type: type: string example: text/plain url: type: string example: http://www.example.com/files/569/download?download_frd=1 size: type: integer example: 43451 description: file size in bytes created_at: type: string format: date-time example: '2012-07-06T14:58:50Z' updated_at: type: string format: date-time example: '2012-07-06T14:58:50Z' unlock_at: type: string format: date-time example: '2012-07-07T14:58:50Z' locked: type: boolean example: false hidden: type: boolean example: false lock_at: type: string format: date-time example: '2012-07-20T14:58:50Z' hidden_for_user: type: boolean example: false visibility_level: type: string example: course description: Changes who can access the file. Valid options are 'inherit' (the default), 'course', 'institution', and 'public'. Only valid in course endpoints. thumbnail_url: type: string modified_at: type: string format: date-time example: '2012-07-06T14:58:50Z' mime_class: type: string example: html description: simplified content-type mapping media_entry_id: type: string example: m-3z31gfpPf129dD3sSDF85SwSDFnwe description: identifier for file in third-party transcoding service locked_for_user: type: boolean example: false lock_info: type: string lock_explanation: type: string example: This assignment is locked until September 1 at 12:00am preview_url: type: string description: 'optional: url to the document preview. This url is specific to the user making the api call. Only included in submission endpoints.' UsageRights: type: object properties: legal_copyright: type: string example: (C) 2014 Incom Corporation Ltd description: Copyright line for the file use_justification: type: string example: creative_commons description: Justification for using the file in a Canvas course. Valid values are 'own_copyright', 'public_domain', 'used_by_permission', 'fair_use', 'creative_commons' license: type: string example: cc_by_sa description: License identifier for the file. license_name: type: string example: CC Attribution Share-Alike description: Readable license name message: type: string example: 4 files updated description: Explanation of the action performed file_ids: type: array items: type: integer example: - 1 - 2 - 3 description: List of ids of files that were updated description: Describes the copyright and license information for a File Folder: type: object properties: context_type: type: string example: Course context_id: type: integer example: 1401 files_count: type: integer example: 0 position: type: integer example: 3 updated_at: type: string format: date-time example: '2012-07-06T14:58:50Z' folders_url: type: string example: https://www.example.com/api/v1/folders/2937/folders files_url: type: string example: https://www.example.com/api/v1/folders/2937/files full_name: type: string example: course files/11folder lock_at: type: string format: date-time example: '2012-07-06T14:58:50Z' id: type: integer example: 2937 folders_count: type: integer example: 0 name: type: string example: 11folder parent_folder_id: type: integer example: 2934 created_at: type: string format: date-time example: '2012-07-06T14:58:50Z' unlock_at: type: string format: date-time hidden: type: boolean example: false hidden_for_user: type: boolean example: false locked: type: boolean example: true locked_for_user: type: boolean example: false for_submissions: type: boolean example: false description: If true, indicates this is a read-only folder containing files submitted to assignments License: type: object properties: id: type: string example: cc_by_sa description: a short string identifying the license name: type: string example: CC Attribution ShareAlike description: the name of the license url: type: string example: http://creativecommons.org/licenses/by-sa/4.0 description: a link to the license text securitySchemes: bearerAuth: type: http scheme: bearer description: 'Canvas OAuth2 access token sent as "Authorization: Bearer ". See https://canvas.instructure.com/doc/api/file.oauth.html' oauth2: type: oauth2 description: Canvas OAuth2. See https://canvas.instructure.com/doc/api/file.oauth.html and https://canvas.instructure.com/doc/api/file.oauth_endpoints.html flows: authorizationCode: authorizationUrl: https://canvas.instructure.com/login/oauth2/auth tokenUrl: https://canvas.instructure.com/login/oauth2/token refreshUrl: https://canvas.instructure.com/login/oauth2/token scopes: {} externalDocs: description: Canvas LMS REST API Documentation url: https://canvas.instructure.com/doc/api/ x-generated-from: https://canvas.instructure.com/doc/api/api-docs.json x-provenance: method: derived derived_by: API Evangelist enrichment pipeline (Swagger 1.2 -> OpenAPI 3.1 conversion) source: openapi/_original/swagger-1.2/*.json (144 verbatim first-party Swagger 1.2 documents) source_url: https://canvas.instructure.com/doc/api/api-docs.json fetched: '2026-09-05' http_status: 200