Drive

General

💡 You can get your Data Key and your Project ID of your project in Builder. You need these to talk with the Deta Drive API.

Root URL

This URL is the base for all your HTTP requests:

https://drive.deta.sh/v1/{project_id}/{drive_name}

The drive_name is the name given to your drive. If you already have a Drive, then you can go ahead and provide it’s name here. Additionally, you could provide any name here when doing any PUT or POST request and our backend will automatically create a new drive for you if it does not exist. There is no limit on how many “Drives” you can create.

Auth

A Data Key must to be provided in the request headers as a value for the X-API-Key key for authentication. This is how we authorize your requests.

Example 'X-API-Key: a0abcyxz_aSecretValue'.

Data Keys were called Project Keys in earlier versions of Deta.

File Names And Directories

Each file needs a unique name which identifies the file. Directorial hierarchies are represented logically by the name of the file itself with the use of backslash /.

For example, if you want to store a file world.txt under the directory hello , the name of the file should be hello/world.txt.

The file name must not end with a /. This also means that you can not create an empty directory.

A directory ceases to exist if there are no more files in it.

Endpoints

Put File

POST /files?name={name}

Stores a smaller file in a single request. Use this endpoint if the file size is small enough to be sent in a single request. The file is overwritten if the file with given name already exists.

We do not accept payloads larger than 10 Mb on this endpoint. For larger uploads, use chunked uploads.

Headers	Required	Description
`Content-Type`	No	The content type of the file. If the content type is not specified, the file `name` is used to figure out the content type. Defaults to `application/octet-stream` if the content type can not be figured out.

Query Params	Required	Description
`name`	Yes	The `name` of the file. More here.

`201 Created`

Content-Type: application/json

{
    "name": "file name",
    "project_id": "deta project id",
    "drive_name": "deta drive_name"
}

Client Errors

400 Bad Request

Content-Type: "application/json"
{
    "errors": [
        // error messages
    ]
}

413 Payload Too Large

Content-Type: text/html
<h1> 413 - Request Entity Too Large </h1>

Initialize Chunked Upload

Initializes a chunked file upload. If the file is larger than 10 MB, use this endpoint to initialize a chunked file upload.

POST /uploads?name={name}

Params	Required	Description
`name`	Yes	The `name` of the file. More here.

`202 Accepted`

Content-Type: application/json

{
    "name": "file name",
    "upload_id": "a unique upload id"
    "project_id": "deta project id",
    "drive_name": "deta drive name"
}

Client Errors

400 Bad Request

Content-Type: application/json
{
    "errors": [
        // error messages
    ]
}

Upload Chunked Part

Uploads a chunked part.

POST /uploads/{upload_id}/parts?name={name}&part={part}

Each chunk must be at least 5 Mb and at most 10 Mb. The final chunk can be less than 5 Mb.

Params	Required	Description
`upload_id`	Yes	The `upload_id` received after initiating a chunked upload
`name`	Yes	The `name` of the file. More here.
`part`	Yes	The chunk part number, start with `1`

`200 Ok`

Content-Type: application/json

{
    "name": "file name",
    "upload_id": "a unique upload id"
    "part": 1, // upload part number
    "project_id": "deta project id",
    "drive_name": "deta drive name"
}

Client Errors

400 Bad Request

Content-Type: application/json
{
    "errors": [
        // error messages
    ]
}

404 Not Found

Content-Type: application/json
{
    "errors": [
        // error messages
    ]
}

413 Payload Too Large

Content-Type: text/html
<h1> 413 Request Entity Too Large </h1>

End Chunked Upload

End a chunked upload.

PATCH /uploads/{upload_id}?name={name}

Params	Required	Description
`upload_id`	Yes	The `upload_id` received after initiating a chunked upload
`name`	Yes	The `name` of the file. More here.

`200 Ok`

Content-Type: application/json

{
    "name": "file name",
    "upload_id": "a unique upload id"
    "project_id": "deta project id",
    "drive_name": "deta drive name"
}

Client Errors

400 Bad Request

Content-Type: application/json
{
    "errors": [
        // error messages
    ]
}

404 Not Found

Content-Type: application/json
{
    "errors": [
        // error messages
    ]
}

Abort Chunked Upload

Aboart a chunked upload.

DELETE /uploads/{upload_id}?name={name}

Params	Required	Description
`upload_id`	Yes	The `upload_id` received after initiating a chunked upload
`name`	Yes	The `name` of the file. More here.

`200 Ok`

Content-Type: application/json

{
    "name": "file name",
    "upload_id": "a unique upload id"
    "project_id": "deta project id",
    "drive_name": "deta drive name"
}

Client Errors

400 Bad Request

Content-Type: application/json
{
    "errors": [
        // error messages
    ]
}

404 Not Found

Content-Type: application/json
{
    "errors": [
        // error messages
    ]
}

Download File

Download a file from drive.

GET /files/download?name={name}

Params	Required	Description
`name`	Yes	The `name` of the file. More here.

`200 Ok`

Accept-Ranges: bytes
Content-Type: {content_type}
Content-Length: {content_length}
{Body}

Client Errors

400 Bad Request

Content-Type: application/json
{
    "errors": [
        // error messages
    ]
}

404 Not Found

Content-Type: application/json
{
    "errors": [
        // error messages
    ]
}

List Files

List file names from drive.

GET /files?limit={limit}&prefix={prefix}&last={last}

Params	Required	Description
`limit`	No	The `limit` of number of file names to get, defaults to `1000`
`prefix`	No	The `prefix` that each file name must have.
`last`	No	The `last` file name seen in a paginated response.

`200 Ok`

The response is paginated based on the limit provided in the request. By default, maximum 1000 file names are sent.

If the response is paginated, the response contains a paging object with size and last keys; size is the number of file names in the response, and last is the last file name seen in the response. The value of last should be used in subsequent requests to continue recieving further pages.

Content-Type: application/json

{
    "paging": {
        "size": 1000, // the number of file names in the response
        "last": "last file name in response"
    },
    "names": ["file1", "file2", ...]
}

Client Errors

400 Bad Request

Content-Type: application/json
{
    "errors": [
        // error messages
    ]
}

404 Not Found

Content-Type: application/json
{
    "errors": [
        // error messages
    ]
}

Delete Files

Delete files from drive.

DELETE /files

Content-Type: "application/json"
{
    "names": ["file_1", "file_2"]
}

Params	Required	Description
`names`	Yes	The `names` of the files to delete, maximum `1000` file names

`200 Ok`

Content-Type: application/json

{
    "deleted": ["file_1", "file_2", ...] // deleted file names
    "failed": {
        "file_3": "reason why file could not be deleted",
        "file_4": "reason why file could not be deleted",
        //...
    }
}

File names that did not exist will also be under deleted, failed will only contain names of files that existed but were not deleted for some reason

Base

FAQ