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,
"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/folders/:id/files
Returns the paginated list of files for the folder.
Example Request:
curl 'https://<canvas>/api/v1/folders/<folder_id>/files' \
-H 'Authorization: Bearer <token>'
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>'
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>'
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>'
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>'
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>'
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>'
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.