API docs by Redocly

Dropzone API (1.0.0)

Download OpenAPI specification:

Dropzones - the new cloud file management API

Dropzones provide a super simple and secure way to store files in the cloud from within your own app, website or service. No need to deal with complex file management systems, buckets or complicated APIs. Just create a dropzone, upload files and manage them with ease. Please note that by using this API you agree to the Terms of Service and Privacy Policy.

Are you a JS developer? Check out our JavaScript SDK.

Download public files

If a file or the dropzone it belongs to has been marked as public (i.e. "anyone" has "file.download" or "dropzone.download" permissions), it can be downloaded by anyone without authentication, using the following URL format:

https://www.collect-files.com/cdn/{fileId}/download

Schemas

DropzonePermissions

string (DropzonePermissions)
Enum: "dropzone.own" "dropzone.list" "dropzone.update" "dropzone.get" "dropzone.zip" "dropzone.grant" "dropzone.upload" "dropzone.download"
"dropzone.own"

FilePermissions

string (FilePermissions)
Enum: "file.own" "file.get" "file.grant" "file.upload.confirm" "file.delete" "file.download"
"file.own"

DropzoneResponse

status
string
object
{
  • "status": "success",
  • "data": {
    }
}

FileItem

_id
string

The ID of the file.

size
integer

The size of the file in bytes.

type
string

The MIME type of the file.

name
string

The name of the file.

object
{
  • "_id": "string",
  • "size": 0,
  • "type": "string",
  • "name": "string",
  • "meta": {
    }
}

FailedFile

name
string

The name of the file that failed to upload.

error
string

The error message explaining why the file failed to upload.

{
  • "name": "string",
  • "error": "string"
}

API Keys

Create a new API key

Creates a new API key for the user. The API key will be used to authenticate requests to the Dropzone API. The used API key for this request must have the permission apikey.create and is intended for developers to create new API keys for their users. You can get an API key with apikey.create permission right here.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get the current API key

Retrieves the details of the current API key being used for authentication.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Transfer gbmonths to another API key

Transfers GB-Months from the used API key to another API key. The targeted API key must have the permission apikey.own, the API used for authentication of this request must have the permission apikey.create.

Authorizations:
ApiKeyAuth
path Parameters
publicId
required
string

The public ID of the API key to transfer GB-Months to.

Request Body schema: application/json
required
gbMonths
number >= 0.01

The amount of GB-Months to transfer. Must be greater than 0.

Responses

Request samples

Content type
application/json
{
  • "gbMonths": 0.1
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Dropzones

Create a new dropzone

Creates a new dropzone with the specified parameters. The API key will be set as the owner of the dropzone and will be charged for the storage size and duration of the dropzone. The dropzone will be created with the specified size in GB and duration in days.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
gb
number [ 0.1 .. 4 ]

The storage size in GB.

days
number [ 30 .. 365 ]

The number of days the dropzone will be active.

name
string [ 1 .. 256 ] characters

The name of the dropzone. If not provided, a random name will be generated. If provided and the api key already owns an existing dropzone with the same name, the dropzone will be fetched, and we'll try to update it with the new parameters. If the dropzone with the same name does not exist, a new dropzone will be created with the specified parameters.

Responses

Request samples

Content type
application/json
{
  • "gb": 1,
  • "days": 90,
  • "name": "My Dropzone"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update a dropzone.

Updates the specified dropzone with new parameters. The used API key must be the owner of the dropzone and will be charged for the storage size and duration of the dropzone.

If the new size or duration is greater than the current size or duration, the dropzone will be extended accordingly. This operation consumes exactly the new amount of GB-Months you want to extend the dropzone with.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
gb
number [ 0.1 .. 4 ]

The new storage size in GB. Must be greater than the current size.

days
number [ 30 .. 365 ]

The number of days the dropzone will be active. Must be greater than the current duration.

Responses

Request samples

Content type
application/json
{
  • "gb": 1,
  • "days": 90
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get dropzone details.

Retrieves details of a specific dropzone. The used API key must at least have the permission dropzone.get to access this endpoint.

Authorizations:
ApiKeyAuth
path Parameters
dropzoneId
required
string

The ID of the dropzone to retrieve.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get dropzone permissions

Retrieves the permissions of the specified dropzone. The used API key must have the permission dropzone.get to access this endpoint. This endpoint is useful to check which permissions are available for the dropzone.

path Parameters
dropzoneId
required
string

The ID of the dropzone to retrieve permissions for.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Grant permissions to a dropzone

Grants permissions to the specified dropzone. The used API key must have the permission dropzone.grant to access this endpoint. This endpoint is useful to grant permissions to other users or API keys for the dropzone.

Authorizations:
ApiKeyAuth
path Parameters
dropzoneId
required
string

The ID of the dropzone to grant permissions for.

Request Body schema: application/json
required
apiKey
string

The Id or "anyone" to grant permissions to.

permissions
Array of strings (DropzonePermissions)
Items Enum: "dropzone.own" "dropzone.list" "dropzone.update" "dropzone.get" "dropzone.zip" "dropzone.grant" "dropzone.upload" "dropzone.download"

The list of permissions to grant to the user.

Responses

Request samples

Content type
application/json
{
  • "apiKey": "string",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Revoke permissions from a dropzone

Revokes permissions from the specified dropzone. The used API key must have the permission dropzone.grant to access this endpoint. This endpoint is useful to revoke permissions from other users or API keys for the dropzone.

Only exception is: if the dropzone is public ("anyone" has "dropzone.own" permission), then permissions cannot be revoked.

Authorizations:
ApiKeyAuth
path Parameters
dropzoneId
required
string

The ID of the dropzone to revoke permissions from.

Request Body schema: application/json
required
publicId
string

The public ID of the apikey or "anyone" to revoke permissions from.

permissions
Array of strings

The list of permissions to revoke from the user.

Responses

Request samples

Content type
application/json
{
  • "publicId": "string",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Permissions

Get dropzone permissions

Retrieves the permissions of the specified dropzone. The used API key must have the permission dropzone.get to access this endpoint. This endpoint is useful to check which permissions are available for the dropzone.

path Parameters
dropzoneId
required
string

The ID of the dropzone to retrieve permissions for.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Grant permissions to a dropzone

Grants permissions to the specified dropzone. The used API key must have the permission dropzone.grant to access this endpoint. This endpoint is useful to grant permissions to other users or API keys for the dropzone.

Authorizations:
ApiKeyAuth
path Parameters
dropzoneId
required
string

The ID of the dropzone to grant permissions for.

Request Body schema: application/json
required
apiKey
string

The Id or "anyone" to grant permissions to.

permissions
Array of strings (DropzonePermissions)
Items Enum: "dropzone.own" "dropzone.list" "dropzone.update" "dropzone.get" "dropzone.zip" "dropzone.grant" "dropzone.upload" "dropzone.download"

The list of permissions to grant to the user.

Responses

Request samples

Content type
application/json
{
  • "apiKey": "string",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Revoke permissions from a dropzone

Revokes permissions from the specified dropzone. The used API key must have the permission dropzone.grant to access this endpoint. This endpoint is useful to revoke permissions from other users or API keys for the dropzone.

Only exception is: if the dropzone is public ("anyone" has "dropzone.own" permission), then permissions cannot be revoked.

Authorizations:
ApiKeyAuth
path Parameters
dropzoneId
required
string

The ID of the dropzone to revoke permissions from.

Request Body schema: application/json
required
publicId
string

The public ID of the apikey or "anyone" to revoke permissions from.

permissions
Array of strings

The list of permissions to revoke from the user.

Responses

Request samples

Content type
application/json
{
  • "publicId": "string",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Get file permissions

Retrieves the permissions of the specified file. The used API key must have the permission file.get to access this endpoint. This endpoint is useful to check which permissions are available for the file.

path Parameters
fileId
required
string

The ID of the file to retrieve permissions for.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Grant permissions to a file

Grants permissions to the specified file. The used API key must have the permission file.grant to access this endpoint. This endpoint is useful to grant permissions to other users or API keys for the file.

Authorizations:
ApiKeyAuth
path Parameters
fileId
required
string

The ID of the file to grant permissions for.

Request Body schema: application/json
required
publicId
string

The public ID of the apikey or "anyone" to grant permissions to.

permissions
Array of strings (FilePermissions)
Items Enum: "file.own" "file.get" "file.grant" "file.upload.confirm" "file.delete" "file.download"

The list of permissions to grant to the user.

Responses

Request samples

Content type
application/json
{
  • "publicId": "string",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Revoke permissions from a file

Revokes permissions from the specified file. The used API key must have the permission file.grant to access this endpoint. This endpoint is useful to revoke permissions from other users or API keys for the file.

Only exception is: if the file is public ("anyone" has "file.own" permission), then permissions cannot be revoked.

Authorizations:
ApiKeyAuth
path Parameters
fileId
required
string

The ID of the file to revoke permissions from.

Request Body schema: application/json
required
publicId
string

The public ID of the apikey or "anyone" to revoke permissions from.

permissions
Array of strings

The list of permissions to revoke from the user.

Responses

Request samples

Content type
application/json
{
  • "publicId": "string",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Files

Get file permissions

Retrieves the permissions of the specified file. The used API key must have the permission file.get to access this endpoint. This endpoint is useful to check which permissions are available for the file.

path Parameters
fileId
required
string

The ID of the file to retrieve permissions for.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Grant permissions to a file

Grants permissions to the specified file. The used API key must have the permission file.grant to access this endpoint. This endpoint is useful to grant permissions to other users or API keys for the file.

Authorizations:
ApiKeyAuth
path Parameters
fileId
required
string

The ID of the file to grant permissions for.

Request Body schema: application/json
required
publicId
string

The public ID of the apikey or "anyone" to grant permissions to.

permissions
Array of strings (FilePermissions)
Items Enum: "file.own" "file.get" "file.grant" "file.upload.confirm" "file.delete" "file.download"

The list of permissions to grant to the user.

Responses

Request samples

Content type
application/json
{
  • "publicId": "string",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Revoke permissions from a file

Revokes permissions from the specified file. The used API key must have the permission file.grant to access this endpoint. This endpoint is useful to revoke permissions from other users or API keys for the file.

Only exception is: if the file is public ("anyone" has "file.own" permission), then permissions cannot be revoked.

Authorizations:
ApiKeyAuth
path Parameters
fileId
required
string

The ID of the file to revoke permissions from.

Request Body schema: application/json
required
publicId
string

The public ID of the apikey or "anyone" to revoke permissions from.

permissions
Array of strings

The list of permissions to revoke from the user.

Responses

Request samples

Content type
application/json
{
  • "publicId": "string",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

List all my files

Retrieves a list of files in the dropzone.

Authorizations:
ApiKeyAuth
path Parameters
dropzoneId
required
string

The ID of the dropzone to retrieve files from.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Request an upload URL

Returns a signed S3 URL and fileId for direct upload to S3 for the given file metadata. This will already consume the storage quota of the dropzone, so ensure that the dropzone has enough space available. The file will not be immediately available in the dropzone until the upload is confirmed.

Authorizations:
ApiKeyAuth
path Parameters
dropzoneId
required
string

The ID of the dropzone to upload files to. This is required to ensure that the file is uploaded to the correct dropzone and that the storage quota is correctly applied.

Request Body schema: application/json
name
required
string non-empty

The name of the file to be uploaded.

type
required
string non-empty

The MIME type of the file. This must not be an empty string.

size
required
integer >= 0

The size of the file in bytes.

Responses

Request samples

Content type
application/json
{
  • "name": "example-file.txt",
  • "type": "text/plain",
  • "size": 123456
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Confirm a file upload

Confirms that a file has been uploaded to S3 and finalizes the file in the system. No request body is required.

Authorizations:
ApiKeyAuth
path Parameters
fileId
required
string

The ID of the file to confirm.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "size": 0,
  • "type": "string",
  • "name": "string",
  • "meta": {
    }
}

Get file details

Retrieves details of a specific file.

Authorizations:
ApiKeyAuth
path Parameters
fileId
required
string

The ID of the file.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "size": 0,
  • "type": "string",
  • "name": "string",
  • "meta": {
    }
}

Delete a file

Deletes a specific file from the specified dropzone.

Authorizations:
ApiKeyAuth
path Parameters
fileId
required
string

The ID of the file.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "File deleted successfully."
}

Download a file

Downloads a specific file. You must either have the permission file.download or dropzone.download to access this endpoint. If you have the dropzone.download permission for the dropzone, the file is contained in, you can download any file from the dropzone, regardless of the file's owner. Or you need the indivitiual file's permission file.download to download the file.

If the file has been marked as public ("anyone" has permission "file.download"), it can be downloaded by anyone without authentication.

Authorizations:
ApiKeyAuthNone
path Parameters
fileId
required
string

The ID of the file.

Responses

Response samples

Content type
application/json
{
  • "status": "error",
  • "message": "Missing dropzoneId or fileId."
}