ASDinCloudDocs

The file object

View as Markdown

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.
GET/api/v1/files

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

Retrieve a file

View as Markdown
GET/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.

Create a file

View as Markdown
POST/api/v1/files

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

Create a folder

View as Markdown
POST/api/v1/files

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

Create multiple files

View as Markdown
POST/api/v1/files

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

Update a file

View as Markdown
PATCH / PUT / POST/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.

Delete a file

View as Markdown
DELETE/api/v1/files/{id}
POST/api/v1/files/{id}/delete

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

List folders

View as Markdown
GET/api/v1/files/folders

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

Download a file

View as Markdown
GET/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.

Move files or folders

View as Markdown
POST/api/v1/files/move

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

Delete multiple files or folders

View as Markdown
POST/api/v1/files/delete-multiple

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