File Management

Manage your files and buckets programmatically. List, retrieve, update, delete, copy, and move files using our RESTful API.

Authentication

Authenticate your requests using API keys.

All requests to the File Management API require the Authorization header with a Bearer token containing your API key.

API Key (Required)

Full access to file management operations. Keep secret.

Authorization: Bearer sk_...
Security Note

API keys provide full access to your buckets and files. Never expose them in client-side code or public repositories. Always use environment variables or secure secret management systems.

List Buckets

Retrieve all buckets accessible by your API key.

GET/buckets

Returns a list of all buckets that your API key has access to, including usage statistics and pricing plan information.

Headers

Authorizationstringrequired

Must be a valid API Key (sk_...)

Get Bucket

Retrieve details for a specific bucket.

GET/buckets/{bucket_name}

Returns detailed information about a specific bucket, including usage statistics and pricing plan details.

Headers

Authorizationstringrequired

Must be a valid API Key (sk_...)

List Files

List files in a bucket with optional filtering and pagination.

GET/files

Returns a paginated list of files in the specified bucket. Supports filtering by path prefix and pagination.

Headers

Authorizationstringrequired

Must be a valid API Key (sk_...)

Body Parameters

bucketstringrequired

The bucket name to list files from (query parameter)

pathstring

Path prefix to filter files (query parameter)

limitnumber

Maximum number of files to return (default: 100, query parameter)

offsetnumber

Number of files to skip for pagination (default: 0, query parameter)

Get File

Retrieve details for a specific file by ID.

GET/files/{file_id}

Returns detailed information about a specific file, including its URL, metadata, and visibility settings.

Headers

Authorizationstringrequired

Must be a valid API Key (sk_...)

Update File

Update file properties: rename, move, or change visibility.

PATCH/files/{file_id}

Updates a file's name, path (move), or visibility. You can update one or more properties at once.

Headers

Authorizationstringrequired

Must be a valid API Key (sk_...)

Content-Typestringrequired

application/json

Body Parameters

namestring

New file name (rename operation)

pathstring

New file path (move operation)

visibilitystring

New visibility: PUBLIC or PRIVATE

Delete File

Permanently delete a file from storage.

DELETE/files/{file_id}

Permanently deletes a file from both the database and storage. This action cannot be undone.

Headers

Authorizationstringrequired

Must be a valid API Key (sk_...)

Copy Files

Copy one or more files to a new location, optionally across buckets.

POST/files/copy

Copies file(s) from a source bucket to a target bucket. Supports copying a single file by path or multiple files by ID. For single file copy, use source_path. For multiple files, use file_ids array.

Headers

Authorizationstringrequired

Must be a valid API Key (sk_...)

Content-Typestringrequired

application/json

Body Parameters

source_bucketstringrequired

Source bucket name

target_bucketstringrequired

Target bucket name

target_pathstringrequired

Target path for the copied file(s)

source_pathstring

Source file path (for single file copy)

file_idsstring[]

Array of file IDs to copy (for multiple file copy)

Move Files

Move one or more files to a different path within the same bucket.

PATCH/files/move

Moves one or more files to a new path within the same bucket. Files are moved by their IDs, and the target path should be a directory path where the files will be placed.

Headers

Authorizationstringrequired

Must be a valid API Key (sk_...)

Content-Typestringrequired

application/json

Body Parameters

bucketstringrequired

Bucket name containing the files to move

file_idsstring[]required

Array of file IDs to move

target_pathstringrequired

Target directory path where files will be moved