Files API

An API for managing files and folders See the File Upload Documentation for details on the file upload workflow.

A File object looks like:

{
  
  "size": 4,
  
  "content-type": "text/plain",
  
  "url": "http://www.example.com/files/569/download?download_frd=1&verifier=c6HdZmxOZa0Fiin2cbvZeI8I5ry7yqD7RChQzb6P",
  
  "id": 569,
  
  "display_name": "file.txt",
  
  "created_at": "2012-07-06T14:58:50Z",
  
  "updated_at": "2012-07-06T14:58:50Z",
  
  "unlock_at": "",
  
  "locked": "false",
  
  "hidden": "false",
  
  "lock_at": "",
  
  "locked_for_user": "false",
  
  "lock_info": "",
  
  "lock_explanation": "This assignment is locked until September 1 at 12:00am",
  
  "hidden_for_user": "false",
  
  "thumbnail_url": "",
  
  //optional: url to the document preview (only included in submission endpoints)
  "preview_url": ""
}

A Folder object looks like:

{
  
  "context_type": "Course",
  
  "context_id": 1401,
  
  "files_count": 0,
  
  "position": 3,
  
  "updated_at": "2012-07-06T14:58:50Z",
  
  "folders_url": "https://www.example.com/api/v1/folders/2937/folders",
  
  "files_url": "https://www.example.com/api/v1/folders/2937/files",
  
  "full_name": "course files/11folder",
  
  "lock_at": "2012-07-06T14:58:50Z",
  
  "id": 2937,
  
  "folders_count": 0,
  
  "name": "11folder",
  
  "parent_folder_id": 2934,
  
  "created_at": "2012-07-06T14:58:50Z",
  
  "unlock_at": "",
  
  "hidden": "false",
  
  "hidden_for_user": "false",
  
  "locked": "true",
  
  "locked_for_user": "false"
}

An UsageRights object looks like:

{
  
  //Copyright line for the file
  "legal_copyright": "(C) 2014 Incom Corporation Ltd",
  
  //Justification for using the file in a Canvas course. Valid values are
  //'own_copyright', 'public_domain', 'used_by_permission', 'fair_use',
  //'creative_commons'
  "use_justification": "creative_commons",
  
  //License identifier for the file.
  "license": "cc_by_sa",
  
  //Readable license name
  "license_name": "CC Attribution Share-Alike",
  
  //Explanation of the action performed
  "message": "4 files updated",
  
  //List of ids of files that were updated
  "file_ids": "[1, 2, 3]"
}

A License object looks like:

{
  
  //a short string identifying the license
  "id": "cc_by_sa",
  
  //the name of the license
  "name": "CC Attribution ShareAlike",
  
  //a link to the license text
  "url": "http://creativecommons.org/licenses/by-sa/4.0"
}

Get quota information FilesController#api_quota

GET /api/v1/courses/:course_id/files/quota

GET /api/v1/groups/:group_id/files/quota

GET /api/v1/users/:user_id/files/quota

Returns the total and used storage quota for the course, group, or user.

Example Request:

curl 'https://<canvas>/api/v1/courses/1/files/quota' \
      -H 'Authorization: Bearer <token>'

Example Response:

{ "quota": 524288000, "quota_used": 402653184 }

List files FilesController#api_index

GET /api/v1/courses/:course_id/files

GET /api/v1/users/:user_id/files

GET /api/v1/groups/:group_id/files

GET /api/v1/folders/:id/files

Returns the paginated list of files for the folder or course.

Request Parameters:

  • content_types[]
    String

    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.).

  • search_term
    String

    The partial name of the files to match and return.

  • include[]
    "user"

    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)

  • sort
    String, "name"|"size"|"created_at"|"updated_at"|"content_type"|"user"

    Sort results by this field. Defaults to 'name'. Note that `sort=user` implies `include[]=user`.

  • order
    String, "asc"|"desc"

    The sorting order. Defaults to 'asc'.

Example Request:

curl 'https://<canvas>/api/v1/folders/<folder_id>/files?content_types[]=image&content_types[]=text/plain \
      -H 'Authorization: Bearer <token>'
Returns a list of Files

Get quota information FilesController#public_url

GET /api/v1/files/:id/public_url

Determine the URL that should be used for inline preview of the file.

Example Request:

curl 'https://<canvas>/api/v1/files/1/public_url' \
      -H 'Authorization: Bearer <token>'

Example Response:

{ "public_url": "https://example-bucket.s3.amazonaws.com/example-namespace/attachments/1/example-filename?AWSAccessKeyId=example-key&Expires=1400000000&Signature=example-signature" }

Get file FilesController#api_show

GET /api/v1/files/:id

Returns the standard attachment json object

Request Parameters:

  • include[]
    "user"

    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)

Example Request:

curl 'https://<canvas>/api/v1/files/<file_id>' \
      -H 'Authorization: Bearer <token>'
Returns a File

Update file FilesController#api_update

PUT /api/v1/files/:id

Update some settings on the specified file

Request Parameters:

  • name
    String

    The new display name of the file

  • parent_folder_id
    String

    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
    Optional, String, "overwrite"|"rename"

    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
    DateTime

    The datetime to lock the file at

  • unlock_at
    DateTime

    The datetime to unlock the file at

  • locked
    Boolean

    Flag the file as locked

  • hidden
    Boolean

    Flag the file as hidden

Example Request:

curl -XPUT 'https://<canvas>/api/v1/files/<file_id>' \
     -F 'name=<new_name>' \
     -F 'locked=true' \
     -H 'Authorization: Bearer <token>'
Returns a File

Delete file FilesController#destroy

DELETE /api/v1/files/:id

Remove the specified file

curl -XDELETE 'https://<canvas>/api/v1/files/<file_id>' \
     -H 'Authorization: Bearer <token>'

List folders FoldersController#api_index

GET /api/v1/folders/:id/folders

Returns the paginated list of folders in the folder.

Example Request:

curl 'https://<canvas>/api/v1/folders/<folder_id>/folders' \
     -H 'Authorization: Bearer <token>'
Returns a list of Folders

List all folders FoldersController#list_all_folders

GET /api/v1/courses/:course_id/folders

GET /api/v1/users/:user_id/folders

GET /api/v1/groups/:group_id/folders

Returns the paginated list of all folders for the given context. This will be returned as a flat list containing all subfolders as well.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/folders' \
     -H 'Authorization: Bearer <token>'
Returns a list of Folders

Resolve path FoldersController#resolve_path

GET /api/v1/courses/:course_id/folders/by_path/*full_path

GET /api/v1/courses/:course_id/folders/by_path

GET /api/v1/users/:user_id/folders/by_path/*full_path

GET /api/v1/users/:user_id/folders/by_path

GET /api/v1/groups/:group_id/folders/by_path/*full_path

GET /api/v1/groups/:group_id/folders/by_path

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.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/folders/by_path/foo/bar/baz' \
     -H 'Authorization: Bearer <token>'
Returns a list of Folders

Get folder FoldersController#show

GET /api/v1/courses/:course_id/folders/:id

GET /api/v1/users/:user_id/folders/:id

GET /api/v1/groups/:group_id/folders/:id

GET /api/v1/folders/:id

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:

Example Request:

curl 'https://<canvas>/api/v1/courses/1337/folders/root' \
     -H 'Authorization: Bearer <token>'

curl 'https://<canvas>/api/v1/folders/<folder_id>' \
     -H 'Authorization: Bearer <token>'
Returns a Folder

Update folder FoldersController#update

PUT /api/v1/folders/:id

Updates a folder

Request Parameters:

  • name
    String

    The new name of the folder

  • parent_folder_id
    String

    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
    DateTime

    The datetime to lock the folder at

  • unlock_at
    DateTime

    The datetime to unlock the folder at

  • locked
    Boolean

    Flag the folder as locked

  • hidden
    Boolean

    Flag the folder as hidden

  • position
    Integer

    Set an explicit sort position for the folder

Example Request:

curl -XPUT 'https://<canvas>/api/v1/folders/<folder_id>' \
     -F 'name=<new_name>' \
     -F 'locked=true' \
     -H 'Authorization: Bearer <token>'
Returns a Folder

Create folder FoldersController#create

POST /api/v1/courses/:course_id/folders

POST /api/v1/users/:user_id/folders

POST /api/v1/groups/:group_id/folders

POST /api/v1/folders/:folder_id/folders

Creates a folder in the specified context

Request Parameters:

  • name
    Required, String

    The name of the folder

  • parent_folder_id
    String

    The id of the folder to store the file in. 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
    String

    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
    DateTime

    The datetime to lock the folder at

  • unlock_at
    DateTime

    The datetime to unlock the folder at

  • locked
    Boolean

    Flag the folder as locked

  • hidden
    Boolean

    Flag the folder as hidden

  • position
    Integer

    Set an explicit sort position for the folder

Example Request:

curl 'https://<canvas>/api/v1/folders/<folder_id>/folders' \
     -F 'name=<new_name>' \
     -F 'locked=true' \
     -H 'Authorization: Bearer <token>'

curl 'https://<canvas>/api/v1/courses/<course_id>/folders' \
     -F 'name=<new_name>' \
     -F 'locked=true' \
     -H 'Authorization: Bearer <token>'
Returns a Folder

Delete folder FoldersController#api_destroy

DELETE /api/v1/folders/:id

Remove the specified folder. You can only delete empty folders unless you set the 'force' flag

Request Parameters:

  • force
    Boolean

    Set to 'true' to allow deleting a non-empty folder

Example Request:

curl -XDELETE 'https://<canvas>/api/v1/folders/<folder_id>' \
     -H 'Authorization: Bearer <token>'

Upload a file FoldersController#create_file

POST /api/v1/folders/:folder_id/files

Upload a file to a folder.

This API endpoint is the first step in uploading a file. See the 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.

Copy a file FoldersController#copy_file

POST /api/v1/folders/:dest_folder_id/copy_file

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.

Request Parameters:

  • source_file_id
    Required, String

    The id of the source file

  • on_duplicate
    Optional, String, "overwrite"|"rename"

    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

Example Request:

curl 'https://<canvas>/api/v1/folders/123/copy_file' \
     -H 'Authorization: Bearer <token>'
     -F 'source_file_id=456'
Returns a File

Copy a folder FoldersController#copy_folder

POST /api/v1/folders/:dest_folder_id/copy_folder

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.

Request Parameters:

  • source_folder_id
    Required, String

    The id of the source folder

Example Request:

curl 'https://<canvas>/api/v1/folders/123/copy_folder' \
     -H 'Authorization: Bearer <token>'
     -F 'source_file_id=789'
Returns a Folder

Set usage rights UsageRightsController#set_usage_rights

PUT /api/v1/courses/:course_id/usage_rights

PUT /api/v1/groups/:group_id/usage_rights

PUT /api/v1/users/:user_id/usage_rights

Sets copyright and license information for one or more files

Request Parameters:

  • file_ids[]
    Required

    List of ids of files to set usage rights for.

  • folder_ids[]
    Optional

    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
    Optional, Boolean

    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]
    Required, String, "own_copyright"|"used_by_permission"|"fair_use"|"public_domain"|"creative_commons"

    The intellectual property justification for using the files in Canvas

  • usage_rights[legal_copyright]
    Optional, String

    The legal copyright line for the files

  • usage_rights[license]
    Optional, String

    The license that applies to the files. See the List licenses endpoint for the supported license types.

Returns a UsageRights

Remove usage rights UsageRightsController#remove_usage_rights

DELETE /api/v1/courses/:course_id/usage_rights

DELETE /api/v1/groups/:group_id/usage_rights

DELETE /api/v1/users/:user_id/usage_rights

Removes copyright and license information associated with one or more files

Request Parameters:

  • file_ids[]
    Required

    List of ids of files to remove associated usage rights from.

  • folder_ids[]
    Optional

    List of ids of folders. Usage rights will be removed from all files in these folders.

List licenses UsageRightsController#licenses

GET /api/v1/courses/:course_id/content_licenses

GET /api/v1/groups/:group_id/content_licenses

GET /api/v1/users/:user_id/content_licenses

Lists licenses that can be applied

Returns a list of Licenses