API Documentation

Agentic-first file storage for AI agents and developers

Base URL: https://www.easybits.cloud/api/v2

3 ways to integrate: REST API (below), typed SDK (npm i @easybits.cloud/sdk), or MCP server (30+ tools for AI agents).

Quick Start

  1. Create an account at easybits.cloud
  2. Go to Developer Dashboard and create an API key
  3. Make your first request:

Authentication

All API requests require a Bearer token in the Authorization header.

Scopes: API keys can have READ, WRITE, DELETE, or ADMIN scopes. Operations require the appropriate scope.

SDK

The typed SDK wraps the entire REST API. Install and use it in any Node.js/Bun/Deno project.

Installbash

All Methods

Files

MethodDescription
listFiles(params?)List files (paginated)
getFile(fileId)Get file + download URL
uploadFile(params)Create file + get upload URL
updateFile(fileId, params)Update name, access, metadata, status
deleteFile(fileId)Soft-delete (7-day retention)
restoreFile(fileId)Restore from trash
listDeletedFiles(params?)List trash with days until purge
searchFiles(query)AI-powered natural language search
duplicateFile(fileId, name?)Copy file (new storage object)
listPermissions(fileId)List sharing permissions

Bulk Operations

MethodDescription
bulkUploadFiles(items)Upload up to 20 files at once
bulkDeleteFiles(fileIds)Delete up to 100 files at once

Images

MethodDescription
optimizeImage(params)Convert to WebP/AVIF
transformImage(params)Resize, rotate, flip, convert, grayscale

Sharing

MethodDescription
shareFile(params)Share with another user by email
generateShareToken(fileId, expiresIn?)Temporary download URL
listShareTokens(params?)List tokens (paginated)

Webhooks

MethodDescription
listWebhooks()List configured webhooks
createWebhook(params)Create webhook (returns secret once)
getWebhook(webhookId)Get webhook details
updateWebhook(webhookId, params)Update URL, events, or status
deleteWebhook(webhookId)Delete permanently

Websites

MethodDescription
listWebsites()List static websites
createWebsite(name)Create website, get id + URL
getWebsite(websiteId)Get website details
updateWebsite(websiteId, params)Update name/status
deleteWebsite(websiteId)Delete website + files

Deploy files by uploading with fileName: "sites/{websiteId}/path" — see Websites section for full example.

Account

MethodDescription
getUsageStats()Storage, file counts, plan info
listProviders()Storage providers
listKeys()API keys

Error Handling

SDKtypescript

Files

GET/files

List your files (paginated)

Query Parameters
assetIdstringFilter by asset ID
limitnumberMax results (default 50, max 100)
cursorstringPagination cursor
statusstringSet to 'DELETED' to list deleted files
Response
SDK
GET/files/:fileId

Get file details with a temporary download URL

Response
SDK
POST/files

Create a file record and get a presigned upload URL

Request Body (JSON)
fileNamestringRequired
contentTypestringMIME type (required)
sizenumberFile size in bytes (required, 1B–5GB)
accessstring'public' or 'private' (default)
regionstring'LATAM', 'US', or 'EU'
Response
SDK

Upload bytes via PUT to putUrl, then PATCH the file status to 'DONE'.

PATCH/files/:fileId

Update file name, access level, metadata, or status

Request Body (JSON)
namestringNew file name
accessstring'public' or 'private'
metadataobjectKey-value pairs (merged, max 10KB)
statusstringOnly 'DONE' (from PENDING)
SDK
DELETE/files/:fileId

Soft-delete a file (7-day retention)

Response
SDK
POST/files/:fileId/restore

Restore a soft-deleted file

Response
SDK
GET/files/search?q=...

AI-powered natural language file search (requires AI key)

Query Parameters
qstringNatural language query (required)
Response
SDK
POST/files/:fileId/duplicate

Create a copy of an existing file (new storage object)

Request Body (JSON)
namestringName for the copy (optional, defaults to 'Copy of ...')
Response
SDK
GET/files/:fileId/permissions

List sharing permissions for a file

Response
SDK

Bulk Operations

POST/files/bulk-upload

Create multiple file records and get presigned upload URLs (max 20)

Request Body (JSON)
itemsarrayArray of { fileName, contentType, size, access? }
Response
SDK

Each file must be uploaded via PUT to its putUrl, then status set to DONE.

POST/files/bulk-delete

Soft-delete multiple files at once (max 100)

Request Body (JSON)
fileIdsstring[]Array of file IDs to delete
Response
SDK

Images

POST/files/:fileId/optimize

Convert image to WebP or AVIF (creates a new file)

Request Body (JSON)
formatstring'webp' (default) or 'avif'
qualitynumber1–100 (default: 80 webp, 50 avif)
Response
SDK
POST/files/:fileId/transform

Resize, crop, rotate, flip, or convert an image (creates a new file)

Request Body (JSON)
widthnumberTarget width in px
heightnumberTarget height in px
fitstring'cover', 'contain', 'fill', 'inside', 'outside'
formatstring'webp', 'avif', 'png', 'jpeg'
qualitynumber1–100
rotatenumberDegrees
flipbooleanVertical flip
grayscalebooleanConvert to grayscale
Response
SDK

Sharing

POST/files/:fileId/share

Share a file with another user by email

Request Body (JSON)
targetEmailstringRecipient email (required)
canReadbooleanDefault: true
canWritebooleanDefault: false
canDeletebooleanDefault: false
SDK
POST/files/:fileId/share-token

Generate a temporary download URL

Request Body (JSON)
expiresInnumberSeconds (60–604800, default 3600)
Response
SDK
GET/share-tokens

List share tokens (paginated)

Query Parameters
fileIdstringFilter by file
limitnumberMax results
cursorstringPagination cursor
SDK

Webhooks

Receive real-time POST notifications when events occur. Payloads are signed with HMAC SHA-256 via the X-Easybits-Signature header. Webhooks auto-pause after 5 consecutive delivery failures.

Events: file.created, file.updated, file.deleted, file.restored, website.created, website.deleted
GET/webhooks

List your configured webhooks

Response
SDK
POST/webhooks

Create a webhook. The secret is only returned on creation — save it.

Request Body (JSON)
urlstringHTTPS URL to receive POST notifications (required)
eventsstring[]Events to subscribe to (required)
Response
SDK

Max 10 webhooks per account. URL must use HTTPS.

GET/webhooks/:webhookId

Get webhook details (excluding secret)

SDK
PATCH/webhooks/:webhookId

Update webhook URL, events, or status

Request Body (JSON)
urlstringNew HTTPS URL
eventsstring[]New events list
statusstring'ACTIVE' or 'PAUSED'. Reactivating resets fail counter.
SDK
DELETE/webhooks/:webhookId

Permanently delete a webhook

Response
SDK

Verifying Signatures

Node.jsjavascript

Payload Format

JSONjson

Websites

How website deploys work:
  1. Create a website — you get an id and a URL like https://my-site.easybits.cloud
  2. Upload files with fileName set to sites/{websiteId}/path (e.g. sites/{id}/index.html)
  3. PUT the bytes to each putUrl, then set status to DONE
  4. Your site is live — SPA fallback to index.html is built-in

Deploy Example

SDKtypescript

Endpoints

GET/websites

List your static websites

SDK
POST/websites

Create a new website

Request Body (JSON)
namestringWebsite name (required)
Response
SDK
GET/websites/:websiteId

Get website details

SDK
PATCH/websites/:websiteId

Update website name or status

Request Body (JSON)
namestringNew name
statusstringe.g. 'DEPLOYED'
SDK
DELETE/websites/:websiteId

Delete website and soft-delete all its files

SDK

Account & Usage

GET/usage

Get account usage statistics: storage, file counts, plan info

Response
SDK
GET/providers

List your configured storage providers

Response
SDK
GET/keys

List your API keys (session auth only)

SDK

Errors & Rate Limits

StatusMeaning
400Bad request (invalid params)
401Unauthorized (missing/invalid API key)
403Forbidden (insufficient scope)
404Resource not found
429Rate limited (too many requests)
500Server error

All error responses include a JSON body: {"error": "message"}

Rate limits vary by plan. Free tier: 100 requests/minute. Pro: 1,000/minute. Business: 10,000/minute.