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\u0026verifier=c6HdZmxOZa0Fiin2cbvZeI8I5ry7yqD7RChQzb6P",
  "id":569,
  "display_name":"file.txt",
  "created_at':"2012-07-06T14:58:50Z",
  "updated_at':"2012-07-06T14:58:50Z",
  "unlock_at':null,
  "locked':false,
  "hidden':false,
  "lock_at':null,
  "locked_for_user":false,
  "lock_info":{
    "asset_string":"file_569",
    "unlock_at":"2013-01-01T00:00:00-06:00",
    "lock_at":"2013-02-01T00:00:00-06:00",
    "context_module":{ ... },
    "manually_locked":true
  },
  "lock_explanation":"This assignment is locked until September 1 at 12:00am",
  "hidden_for_user":false,
  "thumbnail_url":null
}

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":null,
  "id":2937,
  "folders_count":0,
  "name":"11folder",
  "parent_folder_id":2934,
  "created_at":"2012-07-06T14:58:50Z",
  "unlock_at":null
  "hidden":null
  "hidden_for_user":false,
  "locked":true,
  "locked_for_user":false
}

List files FilesController#api_index

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

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

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

Request Parameters:

  • content_types[]
    optional

    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

    (optional) The partial name of the files to match and return.

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 file FilesController#api_show

GET /api/v1/files/:id

Returns the standard attachment json object

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

    The new display name of the file

  • parent_folder_id

    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.

  • lock_at

    The datetime to lock the file at

  • unlock_at

    The datetime to unlock the file at

  • locked

    Flag the file as locked

  • hidden

    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

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

    The new name of the folder

  • parent_folder_id

    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

    The datetime to lock the folder at

  • unlock_at

    The datetime to unlock the folder at

  • locked

    Flag the folder as locked

  • hidden

    Flag the folder as hidden

  • position

    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

    The name of the folder

  • parent_folder_id

    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

    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

    The datetime to lock the folder at

  • unlock_at

    The datetime to unlock the folder at

  • locked

    Flag the folder as locked

  • hidden

    Flag the folder as hidden

  • position

    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

    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.