Files Resource

GET /files

List files by ID or file name.

Request Parameters
name type description default constraints multivalued
count query The maximum number of results to return. 100 int no
file_name query List files matching this file name pattern. The first characted in the pattern cannot be * or ?.     no
first query The first index to return (for paging). 0 int no
id query A file ID to search for. Can be specified multiple times (id=0909938984230942380432&id=971239483127492384732914     yes
library query Limit the search to files in library folder. A library folder is one that requires unique file names. false boolean no
parent_binder_paths query Whether to include the parent folder path with each result. false boolean no
Response Body
media type data type description
application/json SearchResultList (JSON) A SearchResultList of FileProperties objects.
application/xml searchResultList (XML)

DELETE /files/{id}

Delete the specified file.

Request Parameters
name type description default constraints
id path The ID of the file.    
purge query Whether to purge the file (delete permanently) or move to the trash. Only applies to files in personal storage. Files in external storage are always purged. false boolean
version query Only delete the file if the current version matches this value.   int
Response Codes
code condition
204 The file is deleted successfully.
404 (FILE_NOT_FOUND) No file exists with the specified ID.
409 (FILE_VERSION_CONFLICT) The current file version does not match the last_version value.

GET /files/{id}

Download the specified file.

Request Parameters
name type description
id path The file to download.
Response Codes
code condition
404 (FILE_NOT_FOUND) No file exists with the specified ID.
Response Body
media type data type description
application/json object (JSON) The content of the file.
application/xml anyType (XML)

POST /files/{id}

Upload a new version of a file. The request Content-Type can be anything except x-www-form-urlencoded. Supports multipart/form-data posts (see here). If another Content-Type is specified (application/octet-stream, for example), the raw bytes of the request body are read and stored as the file content.

You must specify either force_overwrite or last_version.

Request Parameters
name type description default constraints
id path The ID of the file to update.    
data_name query Reserved.    
force_overwrite query Overwrite the current version of the file, regardless of the current file version. false boolean
last_major_version query Reserved.   int
last_minor_version query Reserved.   int
last_version query Only update the file if the current version matches this value.   int
md5 query The MD5 checksum of the file. If specified, the REST interface returns an error if the MD5 checksum of the uploaded content does not match the expected value.    
mod_date query The desired last modified time for the file.    
Response Codes
code condition
404 (FILE_NOT_FOUND) No file exists with the specified ID.
409 (FILE_VERSION_CONFLICT) The current file version does not match the last_version value.
Response Body
media type data type description
application/json FileProperties (JSON) The updated FileProperties resource.
application/xml fileProperties (XML)

GET /files/{id}/access

Get the access that the authenticated user has to the specified file.

Request Parameters
name type description
id path The ID of the file.
Response Body
media type data type description
application/json Access (JSON) An Access resource.
application/xml access (XML)

GET /files/{id}/metadata

Get the file metadata.

Request Parameters
name type description
id path The ID of the file.
Response Body
media type data type description
application/json FileProperties (JSON) The FileProperties resource.
application/xml fileProperties (XML)

POST /files/{id}/metadata

Request that the server synchronize the metadata of the specified file. This means the server will check the file content in the file's storage area and update the metadata if it is out of date.

The Content-Type must be application/x-www-form-urlencoded. The value of the file_name form parameter in the request body should be a UTF-8 string that has been URL encoded.

Request Parameters
name type description default constraints
description_format form text  
synchronize form If true, the file metadata will be synced with the file in the storage area.   boolean
id path The ID of the file.    
Response Body
media type data type description
application/json FileProperties (JSON) The updated FileProperties resource.
application/xml fileProperties (XML)

POST /files/{id}/name

Rename the specified file. The Content-Type must be application/x-www-form-urlencoded. The value of the file_name form parameter in the request body should be a UTF-8 string that has been URL encoded.

Request Parameters
name type description
name form The new name of the file.
id path The ID of the file.
Response Codes
code condition
404 (FILE_NOT_FOUND) No file exists with the specified ID.
409 (FILE_EXISTS) A file with the specified name already exists.
Response Body
media type data type description
application/json FileProperties (JSON) The updated FileProperties resource.
application/xml fileProperties (XML)

POST /files/{id}/parent_folder

Move the specified file to another folder. The Content-Type must be application/x-www-form-urlencoded. The value of the file_name form parameter in the request body should be a UTF-8 string that has been URL encoded.

Request Parameters
name type description constraints
folder_id form The ID of the target folder. long
name form The new name of the file (optional).  
id path The ID of the file.  
Response Codes
code condition
404 (FILE_NOT_FOUND) No file exists with the specified ID.
409 (FILE_EXISTS) A file with the same name already exists in the target folder.
Response Body
media type data type description
application/json FileProperties (JSON) The updated FileProperties resource.
application/xml fileProperties (XML)

GET /files/{id}/scaled

Download a scaled image of the specified file.

Request Parameters
name type description
id path The ID of the file.
Response Codes
code condition
404 (FILE_NOT_FOUND) No file exists with the specified ID.
Response Body
media type data type
application/json object (JSON)
application/xml anyType (XML)

GET /files/{id}/thumbnail

Download a square thumbnail image of the specified file.

Request Parameters
name type description
id path The ID of the file.
Response Codes
code condition
404 (FILE_NOT_FOUND) No file exists with the specified ID.
Response Body
media type data type
application/json object (JSON)
application/xml anyType (XML)