API reference

• •Base URL. Your backend origin, with every route under /api. On a self-hosted instance this is whatever you set as BACKEND_URL.
• •Content type. Request and response bodies are JSON, except chunk transfers, which send and receive raw bytes. JSON request bodies are capped at 1 MB.
• •Errors. Non-2xx responses return { "error": "message" } with a matching HTTP status.
• •Rate limits. Requests are rate-limited per IP. Auth and public (share / send / pad) routes have their own tighter limits; the SSE and WebSocket endpoints are exempt.

Authenticate by sending a JSON Web Token in the Authorization header. Logging in returns an access token (and a refresh token); send the access token on every protected request.

Authorization: Bearer <access-token>

When an account has two-factor enabled, login returns a 2FA challenge instead of tokens; complete it with POST /api/auth/2fa/verify. Access tokens are short-lived. Use POST /api/auth/refresh to mint a new one.

Files and folders carry only encrypted metadata. Folders can be nested, renamed, moved, and given their own password; deletes are soft (Trash) until purged. File names and folder names are ciphertext on the server.

Uploads are client-side encrypted and chunked. Initialise a session, push each encrypted chunk (or upload it directly to the platform via a presigned URL where supported), then complete the session. Sessions are resumable: query status and re-send only the chunks that are missing.

Downloads fetch metadata, then pull chunks by index. The client verifies each chunk, reassembles, decrypts with your passphrase-derived key, and decompresses, all locally.

Share links expose a single file to anyone with the token, optionally guarded by a password and bounded by an expiry or download limit. The public read routes are unauthenticated and rate-limited; a share password is supplied via the X-Share-Password header.

A folder link publishes a set of files behind a single public token. The link key is generated on the client and lives only in the URL fragment, it is never sent to the server, and each file’s content key is re-wrapped under it, so the public routes only ever return opaque ciphertext. A link can carry a password (sent in the X-Share-Password header), an expiry, and a download cap. The public read routes are unauthenticated and rate-limited.

A shared vault (a “space”) lets several accounts share files under role-based access. The space has its own random key that the client seals to each member’s public key (see User keys below), and every shared file’s content key is re-wrapped under the space key. The server only ever stores these opaque grants, it can add, remove, and rotate them but never open them. Owners and admins manage members; only the owner can rotate the key or delete the space. Adding or removing files is limited to editors and admins.

To seal a space key to another account, every user gets an X25519 keypair generated on the client. The private key is wrapped under your passphrase-derived key and stored only as ciphertext the server can’t read; the public key and a short fingerprint are stored in the clear so others can seal grants to you. These routes never return anyone else’s private key.

Send lets anyone upload an encrypted file without an account and hand over a token; Pad stores a one-time encrypted note. Both are unauthenticated and rate-limited by IP.

A timed vault groups files under a name and a countdown. The expiry is a label, not a delete trigger, deleting a vault never deletes the files it references. The expiry must be at least an hour out.

Snapshots capture a point-in-time manifest of your file list; the integrity monitor records each file’s SHA-256 and size so a later check can flag a hash that changed. Both are metadata-only, no file contents are stored or restored. See Snapshots & integrity.

Offline pins mark files to keep available on a device; the encrypted clipboard syncs small snippets between your own devices. Clipboard items are encrypted on the client (the server stores only ciphertext, capped at 512 KB per item) and a push notifies your other devices over the event stream.

Sync folders are a per-device registry of local folders the desktop client keeps in sync. The server stores only the configuration and the stats a client reports back, the actual file syncing happens on your machine.

Real-time progress (uploads, syncs) streams over Server-Sent Events. Because EventSource cannot set headers, first trade your access token for a single-use ticket, then open the stream with it. The ticket is valid for 30 seconds, so the token itself never appears in a URL or a proxy log.

POST /api/sse/ticket            -> {"ticket": "..."}
GET  /api/events?ticket=<ticket>

The stream carries upload and sync progress plus a clipboard event, emitted to your other connections when a new clipboard item is pushed. It closes when the access token it was opened with expires, or as soon as your sessions are revoked, so reconnect with a fresh ticket. Each account can hold a limited number of open streams. A separate WebSocket endpoint, GET /api/transfer/ws, backs live device-to-device transfer. Both long-lived endpoints bypass the per-request rate limiter.

These routes report account limits, connected storage, and instance settings. Most are read-only for normal users; writing config requires admin.

Admin routes require an account with the admin role. They cover user management, quotas and plans, global tokens, and audit data.

Looking to run your own instance? See Self-hosting and Architecture.