Referenz

REST-API

Dateien hochladen, Sammlungen erstellen und Freigaben per HTTP verwalten. Alle Antworten sind JSON; für anonyme Uploads ist kein API-Schlüssel erforderlich.

Basis-URLhttps://storage.to/api

33 Endpoints · JSON

So funktionieren Uploads

Die storage.to-API treibt unsere CLI, Desktop-App, Web-Uploader und alle Drittanbieter-Clients, die du bauen möchtest. Der Upload-Ablauf besteht aus drei Schritten:

01 · POST /upload/init

Initialisieren

Sag uns, dass du eine Datei hochladen möchtest. Wir geben dir eine oder mehrere vorab signierte URLs zurück, die auf unser Storage-Edge zeigen.

02 · PUT {upload_url}

Upload

PUT deine Bytes direkt in die vorab signierten URL(s). Die Bytes laufen nicht über unsere Server.

03 · POST /upload/confirm

Bestätigen

Sag uns, dass der Upload fertig ist. Wir erstellen einen File-Eintrag und geben dir eine teilbare URL.

Alle Endpoints unten sind relativ zu dieser Basis. Beispiel: POST /upload/init bedeutet POST https://storage.to/api/upload/init.

Authentifizierung

Anonyme Uploads funktionieren ohne Authentifizierung, aber mit engen Limits. Aufrufe ohne Schlüssel sind auf 50 Dateien pro rollierende 24 Stunden pro Gerät oder IP begrenzt, plus die Bandbreitenkontingente unten, und Dateien laufen nach 3 Tagen ab.

Die Authentifizierung mit einem kostenlosen Konto schaltet frei:

Kein tägliches Datei-Limit
Keine Upload-Bandbreitenbegrenzung
Uploads, die mit deinem Konto verknüpft sind (sichtbar unter /dashboard)
Premium-Funktionen (dauerhafte Dateien, mehr Speicherplatz)
Mutationen basierend auf Eigentum (löschen, Passwort setzen, Ablauf ändern), ohne dass der visitor-token-Abgleich nötig ist

Limits auf einen Blick

Ohne Token (anonym)

Token eines Gratis-Kontos

Token eines Bezahl-Kontos

Dateien pro Tag

50 / 24 Stunden

Unbegrenzt

Upload-Bandbreite

100 GB / 24 Stunden (500 GB pro IP)

Unbegrenzt

Maximale Dateigröße

25 GB

100 GB

Ablauf der Datei

Standardmäßig 3 Tage, bis zu 7 über expiry_days

Nie (Dateien bleiben dauerhaft)

Speicherplatz

Keiner (Dateien laufen ab)

100 GB - 1 TB dauerhaft, je nach Tarif

Preise ansehen →

Es gibt keine Monatskontingente - alle Limits sind rollierende 24-Stunden-Fenster oder Limits pro Minute. Der Gratis-Tarif hat keinen festen Speicherplatz: Jede Datei läuft von selbst ab, es sammelt sich also nichts gegen ein Kontingent an.

Um dich zu authentifizieren, erstelle in deinem Konto ein persönliches API-Token und sende es bei jeder Anfrage als Bearer-Token: Du musst angemeldet sein. Das vollständige Token wird nur einmal bei der Erstellung angezeigt — kopiere es an einen sicheren Ort. Du kannst ein Token jederzeit auf derselben Seite widerrufen. API-Token erstellen →

Authorization: Bearer <token>

Eigentümerschaft nachweisen

Owner-TokenEmpfohlen

Jeder Endpunkt zum Erstellen von Ressourcen (/upload/init multipart, /upload/confirm, /file/reserve, /collection) gibt in seiner Antwort ein owner_token zurück. Das Token ist ein signierter Nachweis der Inhaberschaft, der an diese spezielle Ressource gebunden ist—unabhängig von deiner IP oder deinem Visitor-Token. Tokens leben so lange wie die Ressource, sind sicher zum Speichern und laufen nicht unabhängig ab. Ein verlorenes Token bedeutet, die Kontrolle über diese Ressource (Datei/Sammlung/Upload) zu verlieren – behandle sie wie lokale Passwörter.

Authorization: Owner <token>
# oder, zusätzlich zu einer Bearer-Sitzung
X-Owner-Token: <token>

Besuchertoken

Anonyme Clients brauchen eine Möglichkeit, die Inhaberschaft ihrer eigenen Uploads ohne Konto nachzuweisen. Wir verwenden ein visitor-token – eine zufällige Zeichenkette, die der Client einmal erzeugt und danach wiederverwendet. Mit jeder Anfrage senden: Im Web wird das Token automatisch im visitor_token-cookie gespeichert. Die CLI speichert es unter ~/.config/storageto/token (siehe CLI-Dokumentation).

X-Visitor-Token: <random-string>

Bei Mutation-Endpunkten (löschen, Passwort setzen, Ablauf ändern) ist die Inhaberschaft bestätigt, wenn entweder das Visitor-Token übereinstimmt oder die Anfrage von derselben IP kommt, die die Datei erstellt hat. Beides kann verloren gehen (gelöschte Cookies, Netzwerkwechsel). Das Owner-Token ist der bevorzugte Nachweis für die Zukunft.

Fehler

Fehler folgen einem einheitlichen Schema: { "success": false, "error": "…" }

200OK.

201Erstellt.

400Ungültige Anfrage (z. B. Größenlimit der Sammlung überschritten).

401Passwort erforderlich oder falsch.

403Nicht autorisiert (nicht der Besitzer der Ressource).

404Ressource nicht gefunden oder abgelaufen.

422Validierung fehlgeschlagen oder Einschränkung durch Tarif/Kontingent.

429Ratelimit oder Upload-Kontingent erreicht.

500Serverfehler. Prüfe Status.

Ratenbegrenzungen

Alle Ratelimits gelten pro IP. Eine 429-Antwort enthält die Standard-Header Retry-After, X-RateLimit-Limit und X-RateLimit-Remaining.

Upload initialisieren / bestätigen / abbrechen60 / Minute

Multipart-Abschluss500 / Minute

Multipart-Teil-URLs120 / Minute

Batch-Initialisierung / -Bestätigung500 / Minute

Statusabfragen (Datei & Sammlung)120 / Minute

Einstellungen (Passwort, Ablauf, max. Downloads)30 / Minute

Passwortüberprüfung10 / Minute

Sammlung erstellen30 / Minute

Verwalten (bereit, löschen)60 / Minute

Thumbnail-Upload120 / Minute

ShareX-Upload20 / Tag

App-Analytics / Fehler120 und 60 / Minute

Upload-Kontingent: Anonyme Clients haben zwei parallele Limits – 100 GB / 24 h pro visitor-token und 500 GB / 24 h pro IP (das IP-Limit fängt tokenlosen Traffic und geteilte Netzwerke ab). Wenn eines davon überschritten wird, bekommst du einen 429 mit Details. Das ist nur ein Upload-Limit – Downloads sind unbegrenzt und ohne Drosselung.

Upload

8 Endpoints

Der Drei-Schritte-Upload-Flow für jede Datei—inklusive Dateien über 5 GB (automatisch multipart). Wenn du nur einen schnellen Upload im Screenshot-Stil brauchst, schau stattdessen bei ShareX vorbei.

POST/upload/init60/min

Starte einen Upload. Bei Dateien >50 MB ist die Antwort ein Multipart-Upload (Feld type: "multipart"); ansonsten ein einzelnes presigned PUT.

Request-Body

Feld	Typ	Beschreibung
`filename`	string · required	Ursprünglicher Dateiname. Max. 255 Zeichen.
`content_type`	string · required	MIME-Typ.
`size`	integer · required	Dateigröße in Bytes. Min. 1.

Request

curl -X POST https://storage.to/api/upload/init \
  -H "Content-Type: application/json" \
  -H "X-Visitor-Token: abc123" \
  -d '{
    "filename": "report.pdf",
    "content_type": "application/pdf",
    "size": 2202009
  }'

Response · single upload

{
  "success": true,
  "type": "single",
  "upload_url": "https://r2.cloudflarestorage.com/...signed...",
  "headers": { "Host": ["..."] },
  "r2_key": "uuid-abc123"
}

Response · multipart

{
  "success": true,
  "type": "multipart",
  "upload_id": "01HXYZ...",
  "r2_key": "uuid-abc123",
  "part_size": 33554432,
  "total_parts": 4,
  "initial_urls": {
    "1": "https://...",
    "2": "https://..."
  },
  "owner_token": "owner_v1_..."
}

POST/upload/partsNur Eigentümer120/min

Fordert zusätzliche Part-URLs für einen laufenden Multipart-Upload an. Wird verwendet, wenn /init weniger URLs zurückgegeben hat als du Parts hast (oder sie abgelaufen sind).

Request-Body

Feld	Typ	Beschreibung
`upload_id`	string · required	Die `upload_id` von `/init`.
`part_numbers`	array<int> · required	Part-Nummern, für die URLs abgerufen werden sollen.

Request

curl -X POST https://storage.to/api/upload/parts \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "01HXYZ...",
    "part_numbers": [3, 4]
  }'

Response

{
  "success": true,
  "part_urls": [
    { "partNumber": 3, "url": "https://..." },
    { "partNumber": 4, "url": "https://..." }
  ]
}

POST/upload/complete-multipartNur Eigentümer500/min

Schließt einen Multipart-Upload ab, sobald alle Parts hochgeladen sind.

Request-Body

Feld	Typ	Beschreibung
`upload_id`	string · required	Die `upload_id` von `/init`.
`parts`	array · required	Jeder Eintrag: `{ partNumber, etag }` aus der Antwort des Part-Uploads.

Request

curl -X POST https://storage.to/api/upload/complete-multipart \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "01HXYZ...",
    "parts": [
      { "partNumber": 1, "etag": "\"abc...\"" },
      { "partNumber": 2, "etag": "\"def...\"" }
    ]
  }'

Response

{ "success": true }

POST/upload/abortNur Eigentümer60/min

Bricht einen Multipart-Upload ab und räumt alle unvollständigen Daten auf.

Request-Body

Feld	Typ	Beschreibung
`upload_id`	string · required	Der Upload, der abgebrochen werden soll.

Request

curl -X POST https://storage.to/api/upload/abort \
  -H "Content-Type: application/json" \
  -d '{ "upload_id": "01HXYZ..." }'

POST/upload/confirm60/min

Bestätige, dass der Upload abgeschlossen ist. In diesem Schritt erstellen wir den File-Eintrag und geben die freigabefähige URL zurück.

Request-Body

Feld	Typ	Beschreibung
`filename`	string · required	Ursprünglicher Dateiname.
`size`	integer · required	Dateigröße in Bytes.
`content_type`	string · required	MIME-Typ.
`r2_key`	string · required	Die `r2_key` von `/init`.
`collection_id`	string · optional	An eine Sammlung anhängen.
`crc32`	integer · optional	CRC32-Checksumme zur Integritätsprüfung.
`file_id`	string(9) · optional	Erfülle eine zuvor reserviert-Datei-ID.

Request

curl -X POST https://storage.to/api/upload/confirm \
  -H "Content-Type: application/json" \
  -H "X-Visitor-Token: abc123" \
  -d '{
    "filename": "report.pdf",
    "size": 2202009,
    "content_type": "application/pdf",
    "r2_key": "uuid-abc123"
  }'

Response

{
  "success": true,
  "file": {
    "id": "FQxyz1234",
    "url": "https://storage.to/FQxyz1234",
    "filename": "report.pdf",
    "size": 2202009,
    "human_size": "2.1 MB",
    "expires_at": "2026-04-15T12:00:00Z"
  },
  "owner_token": "owner_v1_..."
}

POST/file/reserve60/min

Reserviere eine Date-ID und eine freigabefähige URL vor die Bytes bereit sind. Praktisch, wenn du zuerst einen Link weitergeben und den Upload danach erfüllen musst. Die Berechtigung ist an dein Visitor-Token + deine IP gebunden. Schließe den Upload später mit /upload/init + /upload/confirm ab und übergib dabei file_id zur Bestätigung.

Request-Body

Feld	Typ	Beschreibung
`filename`	string · optional	Platzhalter-Dateiname. Standard: `"Pending"`.
`content_type`	string · optional	Platzhalter-MIME-Typ.

Request

curl -X POST https://storage.to/api/file/reserve \
  -H "X-Visitor-Token: abc123"

Response

{
  "success": true,
  "file": {
    "id": "FQxyz1234",
    "url": "https://storage.to/FQxyz1234",
    "expires_at": "2026-04-12T18:00:00Z"
  },
  "owner_token": "owner_v1_..."
}

POST/upload/init-batch500/min

Batch-Äquivalent von /upload/init, optimiert für den Web-Uploader. Startet bis zu 250 Dateien in einem einzigen Round-Trip.

Wird intern vom Web-Uploader verwendet. Die meisten Clients sollten lieber single-file /upload/init verwenden.

POST/upload/confirm-batch500/min

Batch-Äquivalent von /upload/confirm. Bestätigt viele Dateien in einem einzigen Round-Trip.

Sammlungen

9 Endpoints

Eine Sammlung gruppiert mehrere Dateien unter einer einzigen Freigabe-URL (/c/{id}). Bis zu 10.000 Dateien und insgesamt 25 GB.

POST/collection30/min

Erstelle eine neue Sammlung. Hänge Dateien danach an, indem du collection_id an /upload/confirm übergibst.

Request-Body

Feld	Typ	Beschreibung
`expected_file_count`	integer · optional	Hinweis für die automatische Markierung der Sammlung als bereit, sobald alle erwarteten Dateien bestätigt wurden.

Request

curl -X POST https://storage.to/api/collection \
  -H "Content-Type: application/json" \
  -H "X-Visitor-Token: abc123" \
  -d '{ "expected_file_count": 3 }'

Response

{
  "success": true,
  "collection": {
    "id": "ABC123xyz",
    "url": "https://storage.to/c/ABC123xyz",
    "expires_at": "2026-04-15T12:00:00Z"
  },
  "owner_token": "owner_v1_..."
}

GET/collection/{id}/status120/min

Frage den Status einer Sammlung ab. Markiert die Sammlung außerdem automatisch als bereit, wenn alle erwarteten Dateien bestätigt wurden.

Request

curl https://storage.to/api/collection/ABC123xyz/status

Response

{
  "success": true,
  "files": [
    /* file objects: id, url, filename, size, ... */
  ],
  "is_uploading": false,
  "file_count": 3,
  "expected_file_count": 3,
  "total_size": 6291456,
  "human_total_size": "6 MB"
}

POST/collection/{id}/readyNur Eigentümer60/min

Markiere die Sammlung als bereit zum Download. Normalerweise nicht nötig – Sammlungen werden automatisch bereit, sobald expected_file_count erreicht ist.

DELETE/collection/{id}Nur Eigentümer60/min

Lösche eine Sammlung und alle ihre Dateien.

POST/collection/{id}/passwordNur Eigentümer30/min

Setze ein Passwort für die Sammlung. Erfordert 4–100 Zeichen.

Request-Body

Feld	Typ	Beschreibung
`password`	string · required	4–100 Zeichen.

Request

curl -X POST https://storage.to/api/collection/ABC123xyz/password \
  -H "X-Visitor-Token: abc123" \
  -d '{ "password": "hunter22" }'

DELETE/collection/{id}/passwordNur Eigentümer30/min

Entferne das Passwort aus der Sammlung.

POST/collection/{id}/verify-password10/min

Prüfe ein Passwort. Gibt 200 bei Erfolg zurück, 401 bei falschem Passwort.

Request-Body

Feld	Typ	Beschreibung
`password`	string · required

POST/collection/{id}/expiryNur EigentümerDauerhaft: kostenpflichtig30/min

Ändere die Ablaufzeit einer Sammlung.

Request-Body

Feld	Typ	Beschreibung
`days`	integer · optional	In 1–7 Tagen, aber nie später als 7 Tage nach dem Upload (oder dem aktuellen Ablaufdatum, falls später). Weglassen oder `null` für dauerhaft (nur Premium).

POST/collection/{id}/max-downloadsNur Eigentümer30/min

Setze ein Download-Limit (burn-after-N-downloads). Die Sammlung wird automatisch gelöscht, sobald es erreicht ist.

Request-Body

Feld	Typ	Beschreibung
`max_downloads`	integer · optional	1–1000. Muss den aktuellen Download-Zähler übersteigen. `null`, um das Limit zu entfernen.

Dateien

8 Endpoints

Alle Einstellungen auf Dateiebene (Passwort, Ablauf, max-downloads) spiegeln die Collection-Endpunkte wider. Nur für den Owner.

GET/file/{id}/status120/min

Prüfe, ob eine Datei noch auf ihren Upload wartet.

Response

{ "pending": false }

DELETE/file/{id}Nur Eigentümer60/min

Lösche eine Datei sofort.

POST/file/{id}/thumbnailNur Eigentümer120/min

Lade ein Vorschaubild für eine Video- oder Bilddatei hoch (wird auf der Download-Seite verwendet). Max. 2 MB.

Request-Body

Feld	Typ	Beschreibung
`thumbnail`	image · required	Multipart-Upload. Max. 2 MB.

Response

{
  "success": true,
  "thumbnail_url": "https://..."
}

POST/file/{id}/passwordNur Eigentümer30/min

Setze ein Passwort für eine Datei. Erfordert 4–100 Zeichen.

DELETE/file/{id}/passwordNur Eigentümer30/min

Entferne das Passwort einer Datei.

POST/file/{id}/verify-password10/min

Überprüfe das Passwort einer Datei.

POST/file/{id}/expiryNur EigentümerDauerhaft: kostenpflichtig30/min

Ändere die Ablaufzeit einer Datei.

Request-Body

Feld	Typ	Beschreibung
`days`	integer · optional	In 1–7 Tagen, aber nie später als 7 Tage nach dem Upload (oder dem aktuellen Ablaufdatum, falls später). Weglassen oder `null` für dauerhaft (nur Premium).

POST/file/{id}/max-downloadsNur Eigentümer30/min

Begrenze die Gesamtzahl der Downloads einer Datei. Wird automatisch gelöscht, wenn das Limit erreicht ist.

ShareX-Upload

1 Endpoint

One-Shot-Upload-Endpunkt – sende eine Multipart-Datei und erhalte eine teilbare URL zurück. Kein Init/Confirm-Tanz. Ideal für Screenshot-Tools. Vollständige Anleitung unter /docs/sharex.

POST/sharex/upload20/day

Lade ein Bild oder eine Datei direkt hoch (multipart-Formular, Feld file). Max. 25 MB.

Request

curl -X POST https://storage.to/api/sharex/upload \
  -F "file=@screenshot.png"

Response

{
  "success": true,
  "url": "https://storage.to/FQxyz1234",
  "filename": "screenshot.png",
  "expires_at": "2026-04-15T12:00:00Z"
}

Desktop-Authentifizierung

2 Endpoints

Für angemeldete Clients wie die Desktop-App, die ein Bearer-Token besitzen.

GET/userBearer-Token

Gibt den authentifizierten Benutzer zurück.

Request

curl https://storage.to/api/user \
  -H "Authorization: Bearer <token>"

Response

{
  "id": 42,
  "name": "Ada",
  "email": "ada@example.com",
  "is_premium": true
}

POST/auth/logoutBearer-Token

Widerruft das aktuelle Zugriffstoken.

Verschiedenes

5 Endpoints

Status, Kontingente und Client-Telemetrie.

GET/health

Liveness-Check. Gibt 200 mit { "status": "ok" } zurück, wenn der API-Worker läuft.

Response

{ "status": "ok" }

GET/activity

Live-Aktivitätsstream für den Globus auf der Startseite. Im Edge-Cache gespeichert.

GET/bandwidth/status60/min

Aktuelle Upload-Kontingentnutzung für den Aufrufer – genutzt von der CLI und der Desktop-App, um die verbleibende Kapazität anzuzeigen. Das Antwortformat unterscheidet sich für authentifizierte Nutzer. Trotz des URL-Namens werden hier nur Upload-Bytes erfasst; Downloads werden nicht mitgezählt.

Response · anonymous

{
  "success": true,
  "authenticated": false,
  "has_token": true,
  "limit_bytes": 107374182400,
  "limit_gb": 100,
  "used_bytes": 12345678,
  "used_gb": 0.01,
  "remaining_bytes": 107361836722,
  "remaining_gb": 99.99,
  "window_hours": 24
}

Response · authenticated

{
  "success": true,
  "authenticated": true,
  "plan": "premium"
}

POST/app-analytics120/min

Sende ein Nutzungsereignis über die CLI oder die Desktop-App.

Request-Body

Feld	Typ	Beschreibung
`app`	string · required	`desktop`, `cli` oder `web`.
`version`	string · optional	Client-Version.
`event`	string · required	Ereignisname, z. B. `upload_complete`.
`context`	object · optional	Zusätzliche Metadaten.

POST/app-errors60/min

Sende einen Fehlerbericht aus der CLI oder der Desktop-App. Serverseitig dedupliziert – maximal 10 vom gleichen Fehler pro Stunde.

Request-Body

Feld	Typ	Beschreibung
`app`	string · required	`desktop`, `cli` oder `web`.
`type`	string · required	Fehlerklasse/-typ.
`message`	string · required	Fehlermeldung.
`stack`	string · optional	Stacktrace.
`version`, `os`, `os_version`, `arch`, `context`	various · optional	Diagnose-Metadaten.

← Zurück

ShareX

Weiter →

Akzeptierte Dateitypen