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": ""
}

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"
}

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/folders/:id/files

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

Request Parameters:

  • content_types[]
    Optional, 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
    Optional, String

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

  • 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

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