Documentación de la API

Almacenamiento de archivos agentic-first para desarrolladores y agentes de IA

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

3 formas de integrarte: REST API (abajo), SDK tipado (npm i @easybits.cloud/sdk), o servidor MCP (100+ herramientas para agentes, 12 core por defecto).

Inicio rápido

Crea una cuenta en easybits.cloud
Ve al Dashboard de Desarrollador y crea una API key
Haz tu primera llamada:

Obtén tu API key. Por defecto cargan 12 herramientas core. Agrega --tools docs,slides,all para más. Ver tool groups.

Authentication

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

What your key grants access to

An EasyBits API key authenticates you as the owner of your account. It grants access to all your resources: files, websites, databases, webhooks, documents, presentations, and landings. Keep it secret — anyone with your key can read, modify, or delete your data.

Scopes

Each key is created with one or more scopes. Use the most restrictive scope your integration needs.

Scope	Allows
READ	List and get files, websites, documents, webhooks, and usage stats
WRITE	Create, upload, update, optimize, transform, and share files. Create websites, webhooks, databases, documents, and presentations
DELETE	Soft-delete and permanently remove files, websites, webhooks, and other resources
ADMIN	Full access including key management, provider configuration, sandbox/agent operations, and account-wide actions

Keys created from the Developer Dashboard default to READ + WRITE + DELETE. Use the API to create scoped keys programmatically.

Web clients (Claude.ai / Cowork): use OAuth 2.1 + Dynamic Client Registration instead of an API key. See the Claude Cowork section →

Ghosty Code

El runtime agéntico con EasyBits preinstalado. Cero configuración.

Ghosty Code v0.0.4+ ya trae EasyBits MCP HTTP preinstalado.

Solo necesitas tu API key. Nada que instalar, nada que configurar.

Conexión en 2 pasos

Configura tu API key: export EASYBITS_API_KEY=eb_sk_live_YOUR_KEY
Ejecuta: ghosty

EasyBits aparece como easybits en tu lista de MCPs con 100+ herramientas listas para usar.

¿Versión anterior o instalación manual?

Si usas Ghosty Code v0.0.3 o necesitas agregar EasyBits manualmente:

Qué incluye

⚡EasyBits MCP

100+ herramientas para archivos, documentos, DBs, sandboxes y más

🧠DeepSeek V4

Modelo principal con razonamiento profundo (thinking tokens)

🌐Búsqueda web

BrightData integrado para búsquedas y scraping

🔌MCP dinámico

Agrega y quita servidores MCP en runtime sin reiniciar

📦Sandboxes

Firecracker microVMs para ejecutar código y agentes aislados

🔄Auto-actualización

ghosty update para mantener todo al día

¿Ya usas Ghosty Code? Actualiza a v0.0.4+ con ghosty update y EasyBits aparece automáticamente.

¿No usas Ghosty Code? EasyBits funciona con Claude Cowork, Cursor, VS Code y cualquier cliente MCP. Ver todas las opciones de conexión.

Claude Cowork (OAuth)

For Claude.ai, Cowork, and other web-based MCP clients that can't store API keys.

EasyBits implements OAuth 2.1 with Dynamic Client Registration (RFC 7591) and PKCE S256. Web MCP clients discover, register, and authenticate automatically — no API key copying, no JSON configs.

Connect in 4 steps

In Cowork, open Settings → Connectors → Add custom connector
Paste the MCP URL: https://www.easybits.cloud/api/mcp
Click Connect — you'll be redirected to EasyBits to log in
Authorize the connector. You're done — the agent has access to your workspace

Tip: append ?tools=all to the URL to expose all 100+ tools instead of the 12-tool core group. See Tool Groups for other options.

How it works

EasyBits exposes the standard OAuth discovery endpoints so any spec-compliant MCP client connects without manual setup:

Endpoint	Spec	Purpose
/.well-known/oauth-protected-resource	RFC 9728	Tells clients which Authorization Server protects /api/mcp
/.well-known/oauth-authorization-server	RFC 8414	Advertises authorize, token, and registration endpoints
/oauth/register	RFC 7591	Dynamic Client Registration — client_id + secret issued on POST
/oauth/authorize	OAuth 2.1	User consent + code issuance (PKCE S256 required)
/oauth/token	OAuth 2.1	Exchanges code + verifier for a 1-hour JWT access token

Handshake flow

Flowtypescript

Notes

Access tokens are HS256 JWTs, valid for 1 hour. No refresh token — reauthorize is a single click when you already have a session.
Auto-approval: once logged in, the authorize screen redirects back immediately. The user already expressed consent by initiating the flow from the connector.
Additive: API key Bearer auth keeps working unchanged. The handler tries JWT verification first and silently falls through to API key validation.
PKCE S256 is mandatory. Plain and no-PKCE flows are rejected.
Scope: a single mcp scope — the authorized session has full access to the MCP handler.

Deep dive in the OAuth 2.1 + DCR blog post.

SDK

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

Installbash

All Methods

Files

Method	Description
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

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

Images

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

Sharing

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

Webhooks

Method	Description
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

Method	Description
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

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

Error Handling

SDKtypescript

Files

GET/files

List your files (paginated)

Query Parameters

assetId	string	Filter by asset ID
limit	number	Max results (default 50, max 100)
cursor	string	Pagination cursor
status	string	Set 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)

fileName	string	Required
contentType	string	MIME type (required)
size	number	File size in bytes (required, 1B–5GB)
access	string	'public' or 'private' (default)
region	string	'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)

name	string	New file name
access	string	'public' or 'private'
metadata	object	Key-value pairs (merged, max 10KB)
status	string	Only '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

string

Natural language query (required)

Response

SDK

POST/files/:fileId/duplicate

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

Request Body (JSON)

name

string

Name 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)

items

array

Array 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)

fileIds

string[]

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)

format	string	'webp' (default) or 'avif'
quality	number	1–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)

width	number	Target width in px
height	number	Target height in px
fit	string	'cover', 'contain', 'fill', 'inside', 'outside'
format	string	'webp', 'avif', 'png', 'jpeg'
quality	number	1–100
rotate	number	Degrees
flip	boolean	Vertical flip
grayscale	boolean	Convert to grayscale

Response

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)

url	string	HTTPS URL to receive POST notifications (required)
events	string[]	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)

url	string	New HTTPS URL
events	string[]	New events list
status	string	'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:

Create a website — you get an id and a URL like https://my-site.easybits.cloud
Upload files with fileName set to sites/{websiteId}/path (e.g. sites/{id}/index.html)
PUT the bytes to each putUrl, then set status to DONE
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)

name

string

Website name (required)

Response

SDK

GET/websites/:websiteId

Get website details

SDK

PATCH/websites/:websiteId

Update website name or status

Request Body (JSON)

name	string	New name
status	string	e.g. 'DEPLOYED'

SDK

DELETE/websites/:websiteId

Delete website and soft-delete all its files

SDK

Documents

AI-generated professional documents (reports, brochures, catalogs, proposals, CVs) with parallel page generation, design directions, and semantic color themes.

GET/documents

List all your documents

Response

SDK

GET/documents/:id

Get a document with full page/section data

Response

SDK

POST/documents

Create a new document

Request Body (JSON)

name	string	Document name (required)
prompt	string	Description for AI generation
theme	string	Theme: minimal, calido, oceano, noche, bosque, rosa
customColors	object	Custom palette: { primary, secondary, accent, surface }

Response

SDK

PATCH/documents/:id

Update document metadata (name, theme, colors). Use page tools for content changes.

Request Body (JSON)

name	string	New name
prompt	string	Updated prompt
theme	string	Theme name
customColors	object	Custom color palette

SDK

DELETE/documents/:id

Delete a document

SDK

POST/documents/:id/deploy

Publish as a live website at slug.easybits.cloud

Response

SDK

POST/documents/:id/unpublish

Remove the live website and revert to draft

SDK

Page Management (MCP)

These tools are available via MCP for surgical page-level editing.

get_page_htmlMCP

documentId, pageId

Get the HTML and metadata of a single page.

set_page_htmlMCP

documentId, pageId, html

Update a single page's full HTML. Preferred over update_document for content edits.

get_section_htmlMCP

documentId, pageId, cssSelector

Get the outerHTML of a specific element within a page by CSS selector.

set_section_htmlMCP

documentId, pageId, cssSelector, html

Replace a specific element within a page. Enables surgical edits.

add_pageMCP

documentId, html?, afterPageIndex?, label?

Add a new page. Optionally provide HTML and insertion position.

delete_pageMCP

documentId, pageId

Remove a page. Cannot delete the last remaining page.

reorder_pagesMCP

documentId, pageIds

Reorder all pages. pageIds must contain every page ID exactly once.

get_page_screenshotMCP

documentId, pageIndex?

Take a screenshot of a page. Returns a PNG image (letter-sized). Prefer this tool to verify edits visually.

AI Generation (MCP)

generate_documentMCP

documentId, prompt, skipCover?

Generate all pages with AI via streaming. Use skipCover: true to add pages without regenerating the cover.

refine_document_sectionMCP

documentId, sectionId, instruction

Surgical AI changes to a specific page. Use get_page_html to see the result.

regenerate_document_pageMCP

documentId, sectionId

Completely redesign a page while keeping the same content intent.

enhance_document_promptMCP

name, prompt?, action?

Auto-generate a description from the title or improve an existing prompt.

get_document_directionsMCP

prompt, pageCount?, sourceContent?

Get 4 design directions (fonts, colors, mood). Pass one to generate_document.

clone_documentMCP

documentId, name?

Duplicate a document with all its pages.

Workflow

1. enhance_document_prompt — auto-generate a description

2. get_document_directions — get 4 design directions

3. create_document — create the document

4. generate_document — AI generates all pages

5. get_page_screenshot — verify pages visually

6. refine_document_section — tweak individual pages

7. deploy_document — publish at slug.easybits.cloud

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

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

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

Rate limits: 100 requests per 15 minutes for all plans.

Agentes & Sandboxes

MicroVMs Firecracker para correr agentes y código aislado. Crea sandboxes, ejecuta comandos, expón puertos, y despliega agentes persistentes — todo desde el SDK, REST API o herramientas MCP.

22 herramientas MCP en el grupo sandbox. Agrega --tools sandbox para habilitarlas. Ver tool groups.

Templates

Cada sandbox se crea desde un template. Estos son los disponibles:

Template	Tipo	Descripción
code-interpreter	sandbox	Python con kernel Jupyter persistente. Variables, imports y gráficas sobreviven entre celdas
python / node / bun	sandbox	Runtimes base. Cada `sandbox_run_code` ejecuta un proceso fresco
ubuntu	sandbox	Linux completo. Ideal para instalar paquetes, compilar, o correr servidores
rust-ghosty	agente	Ghosty: cerebro CodeWhale/Rust DeepSeek-first con canales web SSE y WhatsApp
claude-code	agente	Claude Agent SDK loop. Modelo Sonnet 4.6, billing por token
computer-ghosty	agente	Computer-use con escritorio Linux XFCE + terminal noVNC público
ghostyclaw / openclaw	agente	Daemons always-on para WhatsApp, Slack, Telegram

Flujo básico: sandbox efímero

Crea un sandbox, ejecuta código, expón un puerto, destrúyelo. Ideal para ejecución aislada.

Exponer un puerto (URL pública)

Arranca un servidor dentro del sandbox y obtén una URL HTTPS pública al instante.

SDKtypescript

Kernel persistente (code-interpreter)

El template code-interpreter mantiene un kernel Jupyter con estado entre celdas. Variables, imports y gráficas (matplotlib) sobreviven.

SDKtypescript

Agentes persistentes (agent_create)

Crea agentes de larga duración con un endpoint HTTP público. Ideal para chatbots embebidos, asistentes en WhatsApp, o dashboards.

SDKtypescript

Agent Run (one-shot)

Dispara un agente Claude para una tarea, espera el resultado, y destruye el sandbox. Ideal para CI/CD, procesamiento por lotes, o tareas puntuales.

SDKtypescript

Herramientas MCP del grupo sandbox

sandbox_createMCP

template, timeoutSeconds

Crear un sandbox nuevo

sandbox_listMCP

—

Listar sandboxes activos

sandbox_statusMCP

sandboxId

Estado del sandbox (running/stopped/error)

sandbox_destroyMCP

sandboxId

Destruir y liberar recursos

sandbox_extendMCP

sandboxId, extendSeconds

Extender TTL del sandbox

sandbox_suspendMCP

sandboxId

Snapshot a disco y liberar CPU

sandbox_resumeMCP

sandboxId

Restaurar desde snapshot

sandbox_execMCP

sandboxId, command

Ejecutar comando (sync, 60s timeout)

sandbox_exec_backgroundMCP

sandboxId, command

Ejecutar comando en background

sandbox_exec_statusMCP

sandboxId, execId

Consultar estado de ejecución background

sandbox_run_codeMCP

sandboxId, code, lang

Ejecutar Python/Node/Bash inline

sandbox_run_cellMCP

sandboxId, code

Ejecutar celda en kernel Jupyter persistente

sandbox_files_writeMCP

sandboxId, path, content

Escribir archivo en el sandbox

sandbox_files_readMCP

sandboxId, path

Leer archivo del sandbox

sandbox_files_listMCP

sandboxId, path

Listar directorio

sandbox_expose_portMCP

sandboxId, port

Exponer puerto como URL pública HTTPS

agent_createMCP

template

Crear agente persistente (endpoint HTTP)

agent_listMCP

—

Listar agentes persistentes

agent_messageMCP

agentId, content

Enviar mensaje a un agente

agent_runMCP

prompt, model?

Agente Claude one-shot (async)

agent_run_statusMCP

jobId

Consultar estado de agent_run

templates_listMCP

tier?

Listar templates disponibles

Rate limits: 10 spawns/min (sandbox_create, agent_create, agent_run). 120 operaciones/min para el resto. Sandboxes se auto-destruyen al TTL (default 5 min, max 60 min).

Tool Groups

Por defecto el servidor MCP carga 12 herramientas core para minimizar el uso de tokens. Habilita grupos adicionales para desbloquear más capacidades.

Grupo	Herramientas	Descripción
core	12	Archivos, DB, documentos, cotizaciones, estadísticas (default)
sandbox	22	MicroVMs Firecracker: crear, ejecutar, exponer puertos, agentes persistentes y one-shot
files	~37	Todas las ops de archivos: bulk, sharing, permisos, webhooks, imágenes, AI keys
docs	~33	Documentos: generación AI, refine, screenshots, structured docs
sites	~8	Sitios web: CRUD, upload, deploy
brand	~8	Brand kits, plantillas, temas
all	~104	Todo (incluye slides y agentes)

targetEmail	string	Recipient email (required)
canRead	boolean	Default: true
canWrite	boolean	Default: false
canDelete	boolean	Default: false

fileId	string	Filter by file
limit	number	Max results
cursor	string	Pagination cursor

Documentación de la API

Inicio rápido

Authentication

What your key grants access to

Scopes

Ghosty Code

Conexión en 2 pasos

¿Versión anterior o instalación manual?

Qué incluye

Claude Cowork (OAuth)

Connect in 4 steps

How it works

Handshake flow

Notes

SDK

All Methods

Files

Bulk Operations

Images

Sharing

Webhooks

Websites

Account

Error Handling

Files

Bulk Operations

Images

Sharing

Webhooks

Verifying Signatures

Payload Format

Websites

Deploy Example

Endpoints

Documents

Page Management (MCP)

AI Generation (MCP)

Workflow

Account & Usage

Errors & Rate Limits

Agentes & Sandboxes

Templates

Flujo básico: sandbox efímero

Exponer un puerto (URL pública)

Kernel persistente (code-interpreter)

Agentes persistentes (agent_create)

Agent Run (one-shot)

Herramientas MCP del grupo sandbox

Tool Groups

Uso