Riferimenti

REST API

Carica file, crea collezioni e gestisci le condivisioni via HTTP. Tutte le risposte sono in formato JSON; per i caricamenti anonimi non è richiesta alcuna chiave API.

URL di basehttps://storage.to/api

33 endpoint · JSON

Come funzionano gli upload

La API di storage.to alimenta CLI, app desktop, caricatore web e qualsiasi client di terze parti che vuoi creare. Il flusso di caricamento è in tre passaggi:

01 · POST /upload/init

Inizializza

ci dici che vuoi caricare un file. Ti restituiamo uno o più URL presignati che puntano al nostro edge di storage.

02 · PUT {upload_url}

Carica

PUT i tuoi byte direttamente nell’URL(i) presigned. I byte non passano dai nostri server.

03 · POST /upload/confirm

Conferma

ci dici che il caricamento è terminato. Creiamo un record File e ti forniamo un URL condivisibile.

Tutti gli endpoint qui sotto sono relativi a questa base. Esempio: POST /upload/init significa POST https://storage.to/api/upload/init.

Autenticazione

I caricamenti anonimi funzionano senza autenticazione, ma con limiti stretti. Le chiamate senza chiave sono limitate a 50 file per 24 ore mobili per dispositivo o IP, oltre alle quote di banda qui sotto, e i file scadono dopo 3 giorni.

Autenticarsi con un account gratuito sblocca:

Nessun limite giornaliero di file
Nessuna quota di banda di caricamento
Caricamenti associati al tuo account (visibili su /dashboard)
Funzionalità premium (file permanenti, spazio maggiore)
Modifiche basate sulla proprietà (elimina, imposta password, cambia scadenza) senza dover corrispondere al visitor-token

Limiti a colpo d'occhio

Senza token (anonimo)

Token di account gratuito

Token di account a pagamento

File al giorno

50 / 24 ore

Illimitato

Banda di caricamento

100 GB / 24 ore (500 GB per IP)

Illimitato

Dimensione massima del file

25 GB

100 GB

Scadenza del file

3 giorni di default, fino a 7 con expiry_days

Mai (i file sono permanenti)

Spazio di archiviazione

Nessuno (i file scadono)

100 GB - 1 TB permanente, in base al piano

Vedi i piani →

Non ci sono quote mensili: tutti i limiti sono finestre mobili di 24 ore o limiti al minuto. Il piano gratuito non ha uno spazio di archiviazione fisso: ogni file scade da solo, quindi nulla si accumula contro una quota.

Per autenticarti, genera un token API personale dal tuo account e invialo come bearer token su ogni richiesta: Devi aver effettuato l’accesso. Il token completo viene mostrato solo una volta al momento della creazione, quindi copialo in un posto sicuro. Puoi revocare un token in qualsiasi momento dalla stessa pagina. Genera token API →

Authorization: Bearer <token>

Dimostrare la proprietà

Token proprietarioConsigliato

Ogni endpoint che crea risorse (/upload/init multipart, /upload/confirm, /file/reserve, /collection) restituisce un owner_token nella risposta. Il token è una prova firmata di proprietà legata a quella specifica risorsa, indipendente dal tuo IP o dal token del visitatore. I token durano quanto dura la risorsa, sono sicuri da mantenere e non scadono in modo indipendente. Un token smarrito significa perdere il controllo di quella risorsa (file/collezione/upload): trattali come password locali.

Authorization: Owner <token>
# oppure, insieme a una sessione Bearer
X-Owner-Token: <token>

Token visitatore

I client anonimi hanno bisogno di un modo per dimostrare la proprietà dei propri upload senza un account. Usiamo una visitor token: una stringa casuale che il client genera una volta e riutilizza. Inviatela con ogni richiesta: Sul web, il token viene salvato automaticamente nel cookie visitor_token. La CLI lo salva in ~/.config/storageto/token (vedi Documentazione CLI).

X-Visitor-Token: <random-string>

Per gli endpoint di mutazione (elimina, imposta password, cambia scadenza), la proprietà è confermata se oppure il token del visitatore corrisponde o la richiesta proviene dallo stesso IP che ha creato il file. Entrambi possono andare persi (cookie cancellati, cambi di rete). Da ora in poi, la prova preferita è token dell’owner.

Errori

Gli errori seguono una struttura coerente: { "success": false, "error": "…" }

200OK.

201Creato.

400Richiesta non valida (es. limite di dimensione della collezione superato).

401Password richiesta o non corretta.

403Non autorizzato (non sei il proprietario della risorsa).

404Risorsa non trovata o scaduta.

422Validazione non riuscita, oppure restrizione di piano/quota.

429Limite di rate o quota di upload superata.

500Errore del server. Controlla stato.

Limiti di velocità

Tutti i limiti di rate sono per IP. Una risposta 429 include gli header standard Retry-After, X-RateLimit-Limit e X-RateLimit-Remaining.

Avvio / conferma / annullamento upload60 / minuto

Completamento multipart500 / minuto

URL delle parti multipart120 / minuto

Avvio / conferma batch500 / minuto

Verifiche dello stato (file e collezione)120 / minuto

Impostazioni (password, scadenza, max-download)30 / minuto

Verifica password10 / minuto

Creazione collezione30 / minuto

Gestione (pronto, elimina)60 / minuto

Caricamento thumbnail120 / minuto

Upload con ShareX20 / giorno

Analytics dell’app / errori120 e 60 / minuto

Quota di upload: I client anonimi hanno due limiti in parallelo: 100 GB / 24 h per visitor token e 500 GB / 24 h per IP (il limite IP intercetta il traffico senza token e le reti condivise). Quando uno dei due viene superato riceverai un 429 con i dettagli. È solo una quota upload: i download sono illimitati e senza limitazioni.

Carica

8 endpoint

Il flusso di upload in tre passaggi per qualsiasi file, inclusi quelli oltre 5 GB (multipart in automatico). Se ti serve solo un upload rapido in stile screenshot, guarda invece ShareX.

POST/upload/init60/min

Avvia un upload. Per i file >50 MB la risposta è un upload multipart (campo type: "multipart"); altrimenti un singolo PUT presigned.

Corpo della richiesta

Campo	Tipo	Descrizione
`filename`	string · required	Nome file originale. Max 255 caratteri.
`content_type`	string · required	Tipo MIME.
`size`	integer · required	Dimensione del file in byte. 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/partsSolo proprietario120/min

Richiedi URL aggiuntivi per le parti di un upload multipart in corso. Usato quando /init ha restituito meno URL di quante parti hai (oppure sono scaduti).

Corpo della richiesta

Campo	Tipo	Descrizione
`upload_id`	string · required	L'`upload_id` da `/init`.
`part_numbers`	array<int> · required	Numeri delle parti per cui ottenere gli URL.

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-multipartSolo proprietario500/min

Completa un upload multipart una volta caricate tutte le parti.

Corpo della richiesta

Campo	Tipo	Descrizione
`upload_id`	string · required	L'`upload_id` da `/init`.
`parts`	array · required	Ogni voce: `{ partNumber, etag }` dalla risposta del caricamento della parte.

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/abortSolo proprietario60/min

Annulla un upload multipart e ripulisci eventuali dati parziali.

Corpo della richiesta

Campo	Tipo	Descrizione
`upload_id`	string · required	L'upload da annullare.

Request

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

POST/upload/confirm60/min

Conferma che l'upload è completato. È qui che creiamo il record File e restituiamo l'URL condivisibile.

Corpo della richiesta

Campo	Tipo	Descrizione
`filename`	string · required	Nome file originale.
`size`	integer · required	Dimensione del file in byte.
`content_type`	string · required	Tipo MIME.
`r2_key`	string · required	L'`r2_key` da `/init`.
`collection_id`	string · optional	Aggiungi a una raccolta.
`crc32`	integer · optional	Checksum CRC32 per la verifica dell'integrità.
`file_id`	string(9) · optional	Completa un ID file precedentemente riservato.

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

Riserva un ID file e un URL condivisibile prima che i byte siano pronti. Utile quando devi consegnare prima un link e completare l'upload dopo. La proprietà è legata al tuo token visitatore + IP. Completa l'upload più tardi con /upload/init + /upload/confirm, passando file_id per la conferma.

Corpo della richiesta

Campo	Tipo	Descrizione
`filename`	string · optional	Nome file segnaposto. Impostazione predefinita: `"Pending"`.
`content_type`	string · optional	Tipo MIME segnaposto.

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

Equivalente batch di /upload/init, ottimizzato per l'uploader web. Avvia fino a 250 file in un solo round-trip.

Usato internamente dall'uploader web. La maggior parte dei client dovrebbe preferire /upload/init per singolo file.

POST/upload/confirm-batch500/min

Equivalente batch di /upload/confirm. Conferma molti file in un solo round-trip.

Raccolte

9 endpoint

Una raccolta raggruppa più file sotto un unico URL di condivisione (/c/{id}). Fino a 10.000 file e 25 GB totali.

POST/collection30/min

Crea una nuova raccolta. Aggiungi i file in seguito passando collection_id su /upload/confirm.

Corpo della richiesta

Campo	Tipo	Descrizione
`expected_file_count`	integer · optional	Suggerimento per contrassegnare automaticamente la raccolta come pronta una volta che tutti i file previsti sono stati confermati.

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

Controlla lo stato di una raccolta. Contrassegna automaticamente la raccolta come pronta anche se tutti i file previsti sono stati confermati.

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}/readySolo proprietario60/min

Segna la collezione come pronta per il download. Di solito non serve: le collezioni diventano automaticamente pronte quando si raggiunge expected_file_count.

DELETE/collection/{id}Solo proprietario60/min

Elimina una raccolta e tutti i suoi file.

POST/collection/{id}/passwordSolo proprietario30/min

Imposta una password sulla raccolta. Richiede 4–100 caratteri.

Corpo della richiesta

Campo	Tipo	Descrizione
`password`	string · required	4–100 caratteri.

Request

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

DELETE/collection/{id}/passwordSolo proprietario30/min

Rimuovi la password da una raccolta.

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

Verifica una password. Restituisce 200 in caso di successo, 401 se la password è errata.

Corpo della richiesta

Campo	Tipo	Descrizione
`password`	string · required

POST/collection/{id}/expirySolo proprietarioPermanente: a pagamento30/min

Cambia la scadenza di una raccolta.

Corpo della richiesta

Campo	Tipo	Descrizione
`days`	integer · optional	Da 1 a 7 giorni da adesso, ma mai oltre 7 giorni dal caricamento (o la scadenza attuale, se successiva). Ometti o `null` per permanente (solo premium).

POST/collection/{id}/max-downloadsSolo proprietario30/min

Imposta un limite di download (burn-after-N-downloads). La raccolta viene eliminata automaticamente quando viene raggiunto il limite.

Corpo della richiesta

Campo	Tipo	Descrizione
`max_downloads`	integer · optional	1–1000. Deve superare il numero di download attuale. `null` per rimuovere il limite.

File

8 endpoint

Tutte le impostazioni a livello file (password, scadenza, max-downloads) rispecchiano gli endpoint della raccolta. Solo il proprietario.

GET/file/{id}/status120/min

Controlla se un file è ancora in attesa del caricamento.

Response

{ "pending": false }

DELETE/file/{id}Solo proprietario60/min

Elimina un file immediatamente.

POST/file/{id}/thumbnailSolo proprietario120/min

Carica un'immagine thumbnail per un file video o immagine (usata nella pagina di download). Max 2 MB.

Corpo della richiesta

Campo	Tipo	Descrizione
`thumbnail`	image · required	Upload multipart. Max 2 MB.

Response

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

POST/file/{id}/passwordSolo proprietario30/min

Imposta una password su un file. Richiede 4–100 caratteri.

DELETE/file/{id}/passwordSolo proprietario30/min

Rimuovi la password di un file.

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

Verifica la password di un file.

POST/file/{id}/expirySolo proprietarioPermanente: a pagamento30/min

Cambia la scadenza di un file.

Corpo della richiesta

Campo	Tipo	Descrizione
`days`	integer · optional	Da 1 a 7 giorni da adesso, ma mai oltre 7 giorni dal caricamento (o la scadenza attuale, se successiva). Ometti o `null` per permanente (solo premium).

POST/file/{id}/max-downloadsSolo proprietario30/min

Limita il numero totale di download di un file. Si elimina automaticamente quando viene raggiunto il limite.

Upload con ShareX

1 endpoint

Endpoint di upload one-shot: invia un file multipart e ricevi un URL condivisibile. Niente passaggi di init/conferma. Ideale per strumenti di screenshot. Guida completa alla configurazione su /docs/sharex.

POST/sharex/upload20/day

Carica direttamente un'immagine o un file (form multipart, campo 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"
}

Autenticazione desktop

2 endpoint

Per i client autenticati, come l'app desktop, che hanno un token Bearer.

GET/userToken Bearer

Restituisci l’utente autenticato.

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/logoutToken Bearer

Revoca il token di accesso corrente.

Varie

5 endpoint

Stato, quote e telemetria dei client.

GET/health

Controllo di disponibilità. Restituisce 200 con { "status": "ok" } quando il worker API è attivo.

Response

{ "status": "ok" }

GET/activity

Flusso live delle attività per il globo della home. Memorizzato nella cache ai margini della rete.

GET/bandwidth/status60/min

Utilizzo attuale della quota di upload per il chiamante: usato dalla CLI e dall’app desktop per mostrare la capacità residua. La struttura della risposta cambia per gli utenti autenticati. Nonostante il nome dell’URL, tiene traccia solo dei byte upload; i download non vengono conteggiati.

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

Invia un evento di utilizzo dalla CLI o dall’app desktop.

Corpo della richiesta

Campo	Tipo	Descrizione
`app`	string · required	`desktop`, `cli` o `web`.
`version`	string · optional	Versione del client.
`event`	string · required	Nome dell’evento, ad es. `upload_complete`.
`context`	object · optional	Metadati extra.

POST/app-errors60/min

Invia una segnalazione di errore dalla CLI o dall’app desktop. Deduplicata lato server: massimo 10 dello stesso errore per ora.

Corpo della richiesta

Campo	Tipo	Descrizione
`app`	string · required	`desktop`, `cli` o `web`.
`type`	string · required	Classe/tipo di errore.
`message`	string · required	Messaggio di errore.
`stack`	string · optional	Stack trace.
`version`, `os`, `os_version`, `arch`, `context`	various · optional	Metadati diagnostici.

← Precedente

ShareX

Tipi di file accettati