Files
View as MarkdownFiles and folders form the workspace's shared file library.
On this page
- The file object
- List filesGET
/api/v1/files - Retrieve a fileGET
/api/v1/files/{id} - Create a filePOST
/api/v1/files - Create a folderPOST
/api/v1/files - Create multiple filesPOST
/api/v1/files - Update a filePATCH / PUT / POST
/api/v1/files/{id} - Delete a fileDELETE
/api/v1/files/{id}POST/api/v1/files/{id}/delete - List foldersGET
/api/v1/files/folders - Download a fileGET
/api/v1/files/download/{id} - Move files or foldersPOST
/api/v1/files/move - Delete multiple files or foldersPOST
/api/v1/files/delete-multiple
Files and folders form the workspace's shared file library.
Attributes
idinteger- Identifier assigned by the API.
sport_idinteger or null- Sport context recorded for the file, when available.
parent_idinteger or null- Parent folder ID, or null for the root.
is_folderboolean- Whether this record represents a folder.
namestring- Original filename or folder name, up to 160 characters.
friendly_namestring or null- Optional display name, up to 160 characters. Use null to clear it.
descriptionstring or null- Description, up to 160 characters.
urlstring or null- URL of an already-uploaded file.
mime_typestring or null- Media type of the file.
sizeinteger or null- File size in bytes.
viewsinteger- Number of views recorded for the file.
tscinteger or null- Creation time as Unix seconds.
tsuinteger or null- Last update time as Unix seconds.
/api/v1/filesLists file records in the workspace.
Permissions
Send your API key in X-API-Key. Required permissions are Files → Read.
Query parameters
folder_idinteger- List the current folder. Omit it for the root.
qstring- Search filenames and display names throughout the library. Alias search[value].
all_filesinteger- Use 1 for a flat list containing files only.
imagesinteger- Use 1 to return image files and folders.
lengthinteger- Number of records to return.
startinteger- Zero-based offset.
drawstring- Optional request marker echoed in the response.
sortstring- Sort by id, name, friendly_name, mime_type, size, views, tsc, or tsu. Prefix the field name with a minus sign for descending order.
orderstring- Direction for unprefixed sort fields. Use asc or desc.
Returns
Returns the current folder listing, pagination counts, and a breadcrumb path from the root.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
422- The folder ID is invalid or the folder does not exist.
/api/v1/files/{id}Returns one file by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Files → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the file.
Returns
The file is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/filesCreates a file.
Permissions
Send your API key in X-API-Key. Required permissions are Files → Write.
Headers
X-Sport-Idinteger- Sport context to associate with the new file.
Body parameters
namestringRequired- Original filename or folder name, up to 160 characters.
urlstringRequired- URL of an already-uploaded file.
parent_idinteger or null- ID of the parent folder. Use null for the root. Alias folder_id on creation.
friendly_namestring or null- Optional display name, up to 160 characters. Use null to clear it.
descriptionstring or null- Description, up to 160 characters.
mime_typestring or null- Media type of the file.
sizeinteger or null- File size in bytes.
Returns
The created file is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
409- The file is still processing.
422- One or more fields failed validation.
500- The file could not be registered.
/api/v1/filesCreates a folder in the workspace library.
Permissions
Send your API key in X-API-Key. Required permissions are Files → Write.
Body parameters
namestringRequired- Original filename or folder name, up to 160 characters.
is_folderbooleanRequired- Set to true to create a folder.
parent_idinteger or null- ID of the parent folder. Use null for the root. Alias folder_id on creation.
Returns
Returns the created folder in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
422- One or more fields failed validation.
/api/v1/filesRegisters multiple already-uploaded files in a single folder.
Permissions
Send your API key in X-API-Key. Required permissions are Files → Write.
Body parameters
parent_idinteger or null- ID of the parent folder. Use null for the root. Alias folder_id on creation.
files_dataarray of objectsRequired- Each file needs a name and URL. A file can include uploadcare_response with optional upload metadata such as size and mimeType.
Returns
Returns the created files in data and the number created.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- Some files failed. Others may have been created.
422- One or more fields failed validation.
/api/v1/files/{id}Updates a file by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Files → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the file.
Body parameters
namestring- Original filename or folder name, up to 160 characters.
friendly_namestring or null- Optional display name, up to 160 characters. Use null to clear it.
descriptionstring or null- Description, up to 160 characters.
Use Move files or folders to change the parent folder.
Returns
Returns a successful update response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
400- The display name must be a string.
409- The item is managed in company settings.
422- One or more fields failed validation.
/api/v1/files/{id}/api/v1/files/{id}/deleteRemoves a file in the selected sport.
Permissions
Send your API key in X-API-Key. Required permissions are Files → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the file.
Returns
Returns a successful removal response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
400- The file could not be removed.
409- The item is managed in company settings.
/api/v1/files/foldersLists the available folders in name order.
Permissions
Send your API key in X-API-Key. Required permissions are Files → Read.
Returns
Returns an array of folder records and their parent IDs in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
/api/v1/files/download/{id}Redirects to the downloadable file.
Permissions
Send your API key in X-API-Key. Required permissions are Files → Read.
Path parameters
idintegerRequired- ID of the file.
Fetch the file from the returned URL separately. The API key is only needed for the ASDinCloud request.
Returns
Returns the file URL in the Location header.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The record has no downloadable file.
404- The requested record was not found.
/api/v1/files/moveMoves files or folders to another folder or to the library root.
Permissions
Send your API key in X-API-Key. Required permissions are Files → Write.
Body parameters
idsarray of integersRequired- IDs of files or folders.
folder_idinteger or nullRequired- ID of the destination folder. Use null for the root.
Returns
Returns confirmation that the items were moved.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
422- An item or destination is invalid, or the move would create a folder cycle.
/api/v1/files/delete-multipleRemoves files or empty folders by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Files → Write.
Body parameters
idsarray of integersRequired- IDs of files or folders.
Returns
Returns the deleted count. A 207 Multi-Status response includes failed counts, errors, and IDs that were not found.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- Provide one or more valid IDs.
404- The requested record was not found.
409- A folder is nonempty or an item is managed in company settings.
500- The batch could not be completed.