Referans

REST API

HTTP üzerinden dosya yükleyin, koleksiyonlar oluşturun ve paylaşımları yönetin. Tüm yanıtlar JSON’dur; anonim yüklemeler için API anahtarı gerekmez.

Temel URLhttps://storage.to/api

33 uç nokta · JSON

Yüklemeler nasıl çalışır

storage.to API, CLI, masaüstü uygulaması, web yükleyici ve oluşturmak istediğiniz herhangi bir üçüncü taraf istemciyi destekler. Yükleme akışı üç adımdan oluşur:

01 · POST /upload/init

Başlat

bir dosya yüklemek istediğinizi söyleyin. Depolama uç noktamıza işaret eden bir veya daha fazla önceden imzalanmış URL döndürürüz.

02 · PUT {upload_url}

Yükle

PUT baytlarını doğrudan önceden imzalanmış URL(ler)e gönder. Baytlar sunucularımızdan geçmez.

03 · POST /upload/confirm

Onayla

yüklemenin bittiğini bize bildirin. Bir File kaydı oluşturur ve paylaşılabilir bir URL veririz.

Aşağıdaki tüm uç noktalar bu temel adrese göredir. Örnek: POST /upload/init, POST https://storage.to/api/upload/init anlamına gelir.

Kimlik doğrulama

Anonim yüklemeler kimlik doğrulaması olmadan çalışır, ancak sıkı sınırlarla. Anahtarsız çağrılar cihaz veya IP başına 24 saatte 50 dosyayla sınırlıdır, ayrıca aşağıdaki bant genişliği kotaları uygulanır ve dosyalar 3 gün sonra sona erer.

Ücretsiz bir hesapla kimlik doğrulaması şunları açar:

Günlük dosya sınırı yok
Yükleme bant genişliği kotası yok
Hesabınıza eklenen yüklemeler ( /dashboard bölümünde görünür )
Premium özellikler (kalıcı dosyalar, daha büyük depolama)
Ziyaretçi-token eşleşmesi gerektirmeden sahipliğe dayalı işlemler (silme, şifre belirleme, son kullanma tarihini değiştirme)

Limitlere genel bakış

Token yok (anonim)

Ücretsiz hesap tokenı

Ücretli hesap tokenı

Günlük dosya sayısı

50 / 24 saat

Sınırsız

Yükleme bant genişliği

100 GB / 24 saat (500 GB IP başına)

Sınırsız

Maksimum dosya boyutu

25 GB

100 GB

Dosya süresi

Varsayılan 3 gün, expiry_days ile 7 güne kadar

Asla (dosyalar kalıcıdır)

Depolama alanı

Yok (dosyaların süresi dolar)

Plana göre kalıcı 100 GB - 1 TB

Planları gör →

Aylık kota yoktur - tüm limitler 24 saatlik kayan pencereler veya dakika başına hız limitleridir. Ücretsiz planda sabit bir depolama alanı yoktur: her dosyanın süresi kendiliğinden dolar, bu yüzden kotaya karşı hiçbir şey birikmez.

Kimlik doğrulamak için hesabınızdan kişisel bir API token’ı oluşturun ve her istekte bunu bearer token olarak gönderin: Giriş yapmanız gerekiyor. Tam token yalnızca oluşturma sırasında bir kez gösterilir; bu yüzden güvenli bir yere kopyalayın. Aynı sayfadan herhangi bir zamanda bir token’ı iptal edebilirsiniz. API token oluştur →

Authorization: Bearer <token>

Sahipliği kanıtlama

Sahip belirteciÖnerilen

Kaynak oluşturan her uç nokta (/upload/init multipart, /upload/confirm, /file/reserve, /collection) yanıtında bir owner_token döndürür. Token, IP’nizden veya ziyaretçi token’ınızdan bağımsız olarak, o belirli kaynağa bağlı imzalı bir sahiplik kanıtıdır. Token’lar, kaynak ne kadar süre varsa o kadar yaşar; kalıcı olarak saklamak güvenlidir ve bağımsız olarak süresi dolmaz. Token’ı kaybetmek, o kaynağın kontrolünü kaybetmek demektir (dosya/kolleksiyon/yükleme) - onları yerel parolalar gibi düşünün.

Authorization: Owner <token>
# veya bir Bearer oturumuyla birlikte
X-Owner-Token: <token>

Ziyaretçi belirteci

Anonim istemcilerin, bir hesap olmadan kendi yüklemelerinin sahipliğini kanıtlaması için bir yol gerekir. ziyaretçi token’ı kullanıyoruz - istemcinin bir kez oluşturup yeniden kullandığı rastgele bir dize. Her istekte bunu gönderin: Web’de token otomatik olarak visitor_token cookie’sinde saklanır. CLI bunu ~/.config/storageto/token konumunda saklar (bkz. CLI dokümantasyonu).

X-Visitor-Token: <random-string>

Değişiklik (mutation) uç noktalarında (silme, şifre belirleme, son kullanma tarihini değiştirme) sahiplik, ya da ziyaretçi token’ı eşleşiyorsa veya isteğin dosyayı oluşturan aynı IP’den gelmesi durumunda doğrulanır. İkisi de kaybolabilir (çerezlerin temizlenmesi, ağ değişiklikleri). Bundan sonra tercih edilen kanıt sahip token’ı’dır.

Hatalar

Hatalar tutarlı bir yapıda gelir: { "success": false, "error": "…" }

200Tamam.

201Oluşturuldu.

400Kötü istek (ör. koleksiyon boyutu sınırı aşıldı).

401Şifre gerekli ya da hatalı.

403Yetkilendirilmedi (kaynağın sahibi değilsiniz).

404Kaynak bulunamadı veya süresi doldu.

422Doğrulama başarısız oldu veya plan/kota kısıtlaması var.

429Oran sınırına (rate limit) takıldı veya yükleme kotası aşıldı.

500Sunucu hatası. durum değerini kontrol edin.

Hız limitleri

Tüm oran sınırları (rate limit) IP başınadır. 429 yanıtı standart Retry-After, X-RateLimit-Limit ve X-RateLimit-Remaining başlıklarını içerir.

Yükleme başlat / onayla / iptal et60 / dakika

Multipart tamamlandı500 / dakika

Multipart parça URL’leri120 / dakika

Toplu başlat / onayla500 / dakika

Durum yoklamaları (dosya & koleksiyon)120 / dakika

Ayarlar (şifre, son kullanma, en fazla indirme)30 / dakika

Şifre doğrulama10 / dakika

Koleksiyon oluşturma30 / dakika

Yönet (hazırla, sil)60 / dakika

Küçük resim yükleme120 / dakika

ShareX yükleme20 / gün

Uygulama analitiği / hatalardakikada 120 ve 60

Yükleme kotası: Anonim istemcilerin paralel çalışan iki limiti vardır - ziyaretçi token’ı başına 100 GB / 24 sa ve IP başına 500 GB / 24 sa (IP başına 500 GB / 24 sa limiti token’sız trafiği ve paylaşılan ağları yakalar). Bunlardan biri aşılırsa ayrıntılarla birlikte bir 429 alırsınız. Bu yalnızca bir yükleme kotasıdır - indirmeler sınırsız ve hız kısıtlamasızdır.

Yükle

8 uç nokta

Her dosya için üç adımlı yükleme akışı; 5 GB’tan büyük dosyalar dahil (otomatik olarak multipart). Sadece hızlı bir ekran görüntüsü tarzı yükleme gerekiyorsa bunun yerine ShareX’e bakın.

POST/upload/init60/min

Bir yükleme başlatın. 50 MB’tan büyük dosyalarda yanıt multipart yüklemedir (type: "multipart" alanı); aksi halde tek bir presigned PUT.

İstek gövdesi

Alan	Tür	Açıklama
`filename`	string · required	Orijinal dosya adı. En fazla 255 karakter.
`content_type`	string · required	MIME türü.
`size`	integer · required	Dosya boyutu (bayt). En az 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/partsYalnızca sahip120/min

Devam eden bir multipart yükleme için ek parça URL’leri iste. /init, sahip olduğun parça sayısından daha az URL döndürdüyse (veya URL’ler süresi dolduysa) kullanılır.

İstek gövdesi

Alan	Tür	Açıklama
`upload_id`	string · required	`/init` içinden gelen `upload_id`.
`part_numbers`	array<int> · required	URL’leri alınacak parça numaraları.

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-multipartYalnızca sahip500/min

Tüm parçalar yüklendikten sonra multipart yüklemeyi tamamla.

İstek gövdesi

Alan	Tür	Açıklama
`upload_id`	string · required	`/init` içinden gelen `upload_id`.
`parts`	array · required	Her giriş: parça yükleme yanıtındaki `{ partNumber, etag }`.

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/abortYalnızca sahip60/min

Bir multipart yüklemeyi iptal et ve eksik verileri temizle.

İstek gövdesi

Alan	Tür	Açıklama
`upload_id`	string · required	İptal edilecek yükleme.

Request

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

POST/upload/confirm60/min

Yüklemenin tamamlandığını onayla. Bu aşamada File kaydını oluşturur ve paylaşılabilir URL’yi döndürürüz.

İstek gövdesi

Alan	Tür	Açıklama
`filename`	string · required	Orijinal dosya adı.
`size`	integer · required	Dosya boyutu (bayt).
`content_type`	string · required	MIME türü.
`r2_key`	string · required	`/init` içinden gelen `r2_key`.
`collection_id`	string · optional	Bir koleksiyona ekle.
`crc32`	integer · optional	Bütünlük doğrulaması için CRC32 sağlama toplamı.
`file_id`	string(9) · optional	Daha önceki ayrılmış dosya ID’sini yerine getir.

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

Dosya ID’sini ve paylaşılabilir URL’yi baytlar hazır olmadan önce ayır. Önce bir bağlantı dağıtıp ardından yüklemeyi tamamlaman gerektiğinde işe yarar. Sahiplik, ziyaretçi token’ınız + IP’nize bağlıdır. Yüklemeyi daha sonra /upload/init + /upload/confirm ile bitir; onaylamak için file_id iletin.

İstek gövdesi

Alan	Tür	Açıklama
`filename`	string · optional	Yer tutucu dosya adı. Varsayılan: `"Pending"`.
`content_type`	string · optional	Yer tutucu MIME türü.

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

Web yükleyici için optimize edilmiş /upload/init’in toplu karşılığı. Tek gidiş-dönüşte en fazla 250 dosya başlatır.

Web yükleyici tarafından dahili olarak kullanılır. Çoğu istemci tek dosyalık /upload/init’i tercih etmelidir.

POST/upload/confirm-batch500/min

/upload/confirm’un toplu karşılığı. Tek gidiş-dönüşte birçok dosyayı onaylar.

Koleksiyonlar

9 uç nokta

Bir koleksiyon, bir tek paylaşım URL’si (/c/{id}) altında birden fazla dosyayı gruplar. Toplamda en fazla 10.000 dosya ve 25 GB.

POST/collection30/min

Yeni bir koleksiyon oluştur. Dosyaları daha sonra /upload/confirm üzerinde collection_id ile ileterek ekle.

İstek gövdesi

Alan	Tür	Açıklama
`expected_file_count`	integer · optional	Beklenen tüm dosyalar onaylandıktan sonra koleksiyonun otomatik olarak hazır işaretlenmesi için ipucu.

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

Bir koleksiyonun durumunu yokla. Ayrıca beklenen tüm dosyalar onaylandıysa koleksiyonu otomatik olarak hazır işaretler.

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}/readyYalnızca sahip60/min

Kolleksiyonu indirmeye hazır olarak işaretleyin. Genellikle gerekmez - expected_file_count değerine ulaşıldığında kolleksiyonlar otomatik olarak hazır olur.

DELETE/collection/{id}Yalnızca sahip60/min

Bir koleksiyonu ve tüm dosyalarını sil.

POST/collection/{id}/passwordYalnızca sahip30/min

Koleksiyona bir parola belirle. 4–100 karakter gerekir.

İstek gövdesi

Alan	Tür	Açıklama
`password`	string · required	4–100 karakter.

Request

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

DELETE/collection/{id}/passwordYalnızca sahip30/min

Koleksiyondaki parolayı kaldır.

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

Parolayı kontrol et. Başarılıysa 200, yanlışsa 401 döner.

İstek gövdesi

Alan	Tür	Açıklama
`password`	string · required

POST/collection/{id}/expiryYalnızca sahipKalıcı: ücretli30/min

Bir koleksiyonun son kullanma süresini değiştir.

İstek gövdesi

Alan	Tür	Açıklama
`days`	integer · optional	Şu andan itibaren 1–7 gün, ancak yüklemeden sonraki 7 günden (veya daha geçse mevcut sona erme tarihinden) daha geç olamaz. Kalıcı için boş bırakın veya `null` verin (yalnızca premium).

POST/collection/{id}/max-downloadsYalnızca sahip30/min

Bir indirme limiti belirle (burn-after-N-downloads). Limite ulaşıldığında koleksiyon otomatik olarak silinir.

İstek gövdesi

Alan	Tür	Açıklama
`max_downloads`	integer · optional	1–1000. Mevcut indirme sayısını aşmalı. Limiti kaldırmak için `null`.

Dosyalar

8 uç nokta

Tüm dosya düzeyi ayarlar (parola, son kullanma, max-downloads) koleksiyon uç noktalarını yansıtır. Yalnızca sahip.

GET/file/{id}/status120/min

Bir dosyanın yüklenmeyi bekleyip beklemediğini kontrol et.

Response

{ "pending": false }

DELETE/file/{id}Yalnızca sahip60/min

Bir dosyayı hemen sil.

POST/file/{id}/thumbnailYalnızca sahip120/min

Bir video ya da görsel dosya için küçük resim yükle (indirme sayfasında kullanılır). En fazla 2 MB.

İstek gövdesi

Alan	Tür	Açıklama
`thumbnail`	image · required	Multipart yükleme. En fazla 2 MB.

Response

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

POST/file/{id}/passwordYalnızca sahip30/min

Bir dosyaya parola belirle. 4–100 karakter gerekir.

DELETE/file/{id}/passwordYalnızca sahip30/min

Bir dosyanın parolasını kaldır.

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

Bir dosyanın parolasını doğrula.

POST/file/{id}/expiryYalnızca sahipKalıcı: ücretli30/min

Bir dosyanın son kullanma süresini değiştir.

İstek gövdesi

Alan	Tür	Açıklama
`days`	integer · optional	Şu andan itibaren 1–7 gün, ancak yüklemeden sonraki 7 günden (veya daha geçse mevcut sona erme tarihinden) daha geç olamaz. Kalıcı için boş bırakın veya `null` verin (yalnızca premium).

POST/file/{id}/max-downloadsYalnızca sahip30/min

Bir dosyanın toplam indirme sayısını sınırla. Eşiğe ulaşıldığında otomatik olarak silinir.

ShareX yükleme

1 uç nokta

Tek seferlik yükleme endpoint’i - multipart bir dosya gönderin, paylaşılabilir bir URL geri alın. Init/onay karmaşası yok. Ekran görüntüsü araçları için ideal. Tam kurulum rehberi: /docs/sharex.

POST/sharex/upload20/day

Bir görseli ya da dosyayı doğrudan yükle (multipart form, file alanı). En fazla 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"
}

Masaüstü kimlik doğrulama

2 uç nokta

Bearer token'ı olan, oturum açmış istemciler için, örneğin masaüstü uygulaması.

GET/userBearer token

Kimliği doğrulanmış kullanıcıyı döndür.

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

Mevcut erişim belirtecini (access token) iptal et.

Diğer

5 uç nokta

Durum, kotalar ve istemci telemetrisi.

GET/health

Canlılık kontrolü. API worker hizmet verirken 200 ve { "status": "ok" } döner.

Response

{ "status": "ok" }

GET/activity

Ana sayfadaki dünya için canlı etkinlik akışı. Kenarda önbelleğe alınır.

GET/bandwidth/status60/min

Çağıran için mevcut yükleme kotası kullanımı - CLI ve masaüstü uygulaması kalan kapasiteyi göstermek için kullanır. Kimliği doğrulanmış kullanıcılar için yanıt biçimi farklıdır. URL adında geçmesine rağmen yalnızca yükleme baytlarını takip eder; indirmeler sayılmaz.

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

CLI veya masaüstü uygulamasından bir kullanım olayı gönder.

İstek gövdesi

Alan	Tür	Açıklama
`app`	string · required	`desktop`, `cli` veya `web`.
`version`	string · optional	İstemci sürümü.
`event`	string · required	Olay adı, ör. `upload_complete`.
`context`	object · optional	Ek meta veriler.

POST/app-errors60/min

CLI veya masaüstü uygulamasından hata raporu gönderin. Sunucu tarafında yinelenenler kaldırılır - aynı hatadan saatte en fazla 10.

İstek gövdesi

Alan	Tür	Açıklama
`app`	string · required	`desktop`, `cli` veya `web`.
`type`	string · required	Hata sınıfı/türü.
`message`	string · required	Hata mesajı.
`stack`	string · optional	Stack trace.
`version`, `os`, `os_version`, `arch`, `context`	various · optional	Tanılama meta verileri.

← Önceki

ShareX

Kabul edilen dosya türleri