REST API

Upload files, create collections, and manage shares over HTTP. All responses are JSON; no API key is required for anonymous uploads.

Introduction

The storage.to API powers our CLI, desktop app, web uploader, and any third-party client you want to build.

The upload flow is three steps:

1. Init - tell us you want to upload a file. We return one or more presigned URLs pointing at Cloudflare R2.
2. Upload to R2 - PUT your bytes directly to the presigned URL(s). Bytes don't pass through our servers.
3. Confirm - tell us the upload finished. We create a File record and hand you a shareable URL.

Base URL

https://storage.to/api

All endpoints below are relative to this base. Example: POST /upload/init means POST https://storage.to/api/upload/init.

Authentication

Anonymous uploads work without authentication, but with tight limits. Keyless callers are capped at 50 files per rolling 24 hours per device or IP, plus the bandwidth quotas below, and files expire after 3 days.

Authenticating with a free account unlocks:

• No daily file cap
• No upload bandwidth quota
• Uploads attached to your account (visible at /dashboard)
• Premium features (permanent files, larger storage)
• Ownership-based mutations (delete, set password, change expiry) without needing the visitor-token match

Limits at a glance

There are no monthly quotas - all limits are rolling 24-hour windows or per-minute rate limits. The free plan has no fixed storage pool: every file expires on its own, so nothing accumulates against a quota.

To authenticate, generate a personal API token from your account and send it as a bearer token on every request:

Authorization: Bearer <token>

Generate API token

You need to be signed in. The full token is shown only once at creation, so copy it somewhere safe. You can revoke a token at any time from the same page.

Visitor token

Anonymous clients need a way to prove ownership of their own uploads without an account. We use a visitor token - a random string the client generates once and reuses. Send it with every request:

X-Visitor-Token: <random-string>

On the web, the token is stored in the visitor_token cookie automatically. The CLI stores it at ~/.config/storageto/token (see CLI docs).

For mutation endpoints (delete, set password, change expiry), ownership is confirmed if either the visitor token matches or the request comes from the same IP that created the file. Both can be lost (cleared cookies, network changes). The owner token is the preferred proof going forward.

Owner token

Every resource-creating endpoint (/upload/init multipart, /upload/confirm, /file/reserve, /collection) returns an owner_token in its response. The token is a signed proof of ownership tied to that specific resource, independent of your IP or visitor token.

Store the token alongside the resource ID and send it on any mutation as:

Authorization: Owner <token>

Or, if you are already using Authorization: Bearer for an authenticated session, send it as:

X-Owner-Token: <token>

The server accepts the owner token as a valid ownership proof alongside the legacy visitor token + IP fallback - clients that hold the token keep working after switching networks or clearing cookies, and clients that do not still work exactly as before.

Tokens live as long as the resource does, are safe to persist, and do not expire independently. A lost token means losing control of that resource (file/collection/upload) - treat them like local passwords.

Errors

Errors follow a consistent shape:

{
  "success": false,
  "error": "Human-readable message"
}

Common HTTP status codes:

Rate limits

All rate limits are per-IP. A 429 response includes standard Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining headers.

Upload quota: anonymous clients have two ceilings running in parallel - 100 GB / 24 h per visitor token and 500 GB / 24 h per IP (the IP ceiling catches tokenless traffic and shared networks). When either is exceeded you'll get a 429 with details. This is an upload quota only - downloads are unlimited and unthrottled (served directly from R2 signed URLs).

Upload

The three-step upload flow for any file, including files over 5 GB (automatically multipart). If you only need a quick screenshot-style upload, see ShareX instead.

Collections

A collection groups multiple files under a single share URL (/c/{id}). Up to 10,000 files and 25 GB total.

Files

All file-level settings (password, expiry, max-downloads) mirror the collection endpoints. Owner-only.

ShareX upload

One-shot upload endpoint - send a multipart file, get a shareable URL back. No init/confirm dance. Ideal for screenshot tools. Full setup guide at /docs/sharex.

Desktop auth

For authenticated clients (e.g. the desktop app) holding a Sanctum token.

Misc