REST API

Upload bestanden, maak collecties en beheer shares via HTTP. Alle antwoorden zijn JSON; voor anonieme uploads is geen API-sleutel vereist.

Introductie

De storage.to API vormt de basis voor onze CLI, desktopapp, web-uploader en elke third-party client die je wilt bouwen.

Het uploadproces bestaat uit drie stappen:

1. Init - laat ons weten dat je een bestand wilt uploaden. We retourneren één of meer presigned URL's die naar Cloudflare R2 wijzen.
2. Upload naar R2 - PUT je bytes direct naar de presigned URL(s). Bytes gaan niet via onze servers.
3. Bevestigen - laat ons weten dat de upload klaar is. We maken een File-record en geven je een deelbare URL.

Basis-URL

https://storage.to/api

Alle endpoints hieronder zijn relatief aan deze basis. Voorbeeld: POST /upload/init betekent POST https://storage.to/api/upload/init.

Authenticatie

Anonieme uploads werken zonder authenticatie, maar met strikte limieten. Aanroepen zonder sleutel zijn beperkt tot 50 bestanden per doorlopende 24 uur per apparaat of IP, plus de bandbreedtequota hieronder, en bestanden verlopen na 3 dagen.

Authenticeren met een gratis account ontgrendelt:

• Geen dagelijkse bestandslimiet
• Geen uploadbandbreedtequotum
• Uploads gekoppeld aan je account (zichtbaar op /dashboard)
• Premiumfuncties (permanente bestanden, meer opslag)
• Mutaties op basis van eigendom (verwijderen, wachtwoord instellen, vervaldatum wijzigen) zonder dat je de visitor-token match nodig hebt

Limieten in één oogopslag

Er zijn geen maandelijkse quota - alle limieten zijn voortschrijdende 24-uursvensters of limieten per minuut. Het gratis abonnement heeft geen vaste opslagruimte: elk bestand verloopt vanzelf, dus er stapelt zich niets op tegen een quotum.

Om te authenticeren, genereer je een persoonlijk API-token vanuit je account en stuur je dit als bearer token bij elke aanvraag:

Authorization: Bearer <token>

Genereer API-token

Je moet ingelogd zijn. Het volledige token wordt alleen één keer getoond bij het aanmaken, dus kopieer het naar een veilige plek. Je kunt een token op elk moment intrekken vanaf dezelfde pagina.

Bezoekerstoken

Anonieme clients hebben een manier nodig om eigenaarschap van hun eigen uploads te bewijzen zonder account. We gebruiken een visitor token - een willekeurige tekenreeks die de client één keer genereert en daarna hergebruikt. Stuur deze mee met elke request:

X-Visitor-Token: <random-string>

Op het web wordt de token automatisch opgeslagen in de visitor_token-cookie. De CLI slaat deze op op ~/.config/storageto/token (zie CLI-documentatie).

Voor mutatie-endpoints (verwijderen, wachtwoord instellen, vervaldatum wijzigen) wordt eigendom bevestigd als of de bezoeker-token overeenkomt met of het verzoek afkomstig is van hetzelfde IP dat het bestand heeft aangemaakt. Beide kunnen verloren gaan (cookies gewist, netwerkwijzigingen). De owner-token is het voorkeursbewijs voor de toekomst.

Eigenaars-token

Elk endpoint dat een resource aanmaakt (/upload/init multipart, /upload/confirm, /file/reserve, /collection) retourneert een owner_token in zijn antwoord. De token is een ondertekend bewijs van eigendom dat gekoppeld is aan die specifieke resource, onafhankelijk van je IP of bezoeker-token.

Bewaar de token samen met de resource-ID en stuur deze bij elke mutatie als:

Authorization: Owner <token>

Of, als je al Authorization: Bearer gebruikt voor een geauthenticeerde sessie, stuur het dan als:

X-Owner-Token: <token>

De server accepteert het owner-token als geldig bewijs van eigenaarschap naast de legacy visitor token + IP-fallback. Clients die het token hebben blijven werken na het wisselen van netwerk of het wissen van cookies, en clients die het token niet hebben werken nog steeds precies zoals voorheen.

Tokens bestaan zolang de resource bestaat, zijn veilig om op te slaan en verlopen niet onafhankelijk. Een verloren token betekent dat je de controle over die resource (bestand/collectie/upload) verliest — behandel ze als lokale wachtwoorden.

Fouten

Fouten volgen een consistent patroon:

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

Veelvoorkomende HTTP-statuscodes:

Snelheidslimieten

Alle snelheidslimieten zijn per IP. Een 429-antwoord bevat de standaard Retry-After-, X-RateLimit-Limit- en X-RateLimit-Remaining-headers.

Uploadquota: anonieme clients hebben twee limieten tegelijk actief — 100 GB / 24 u per visitor token en 500 GB / 24 u per IP (de IP-limiet vangt verkeer zonder token en gedeelde netwerken). Zodra één van beide wordt overschreden krijg je een 429 met details. Dit is alleen een upload-quota — downloads zijn onbeperkt en niet beperkt (geleverd via R2 signed URLs).

Upload

De uploadflow in drie stappen voor elk bestand, inclusief bestanden groter dan 5 GB (automatisch multipart). Als je alleen een snelle upload in screenshot-stijl nodig hebt, kijk dan in plaats daarvan naar ShareX.

Collecties

Een collectie groepeert meerdere bestanden onder één deelbare URL (/c/{id}). Tot 10.000 bestanden en 25 GB totaal.

Bestanden

Alle instellingen op bestandsniveau (wachtwoord, vervaldatum, max-downloads) spiegelen de collectie-endpoints. Alleen voor de eigenaar.

ShareX uploaden

One-shot upload-endpoint — stuur een multipart-bestand en je krijgt een deelbare URL terug. Geen gedoe met init/confirm. Ideaal voor screenshot-tools. Volledige setup-gids op /docs/sharex.

Desktop-authenticatie

Voor geauthenticeerde clients (bijv. de desktopapp) met een Sanctum-token.

Overig