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.

Giriş

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:

1. Başlat - bir dosya yüklemek istediğinizi söyleyin. Cloudflare R2’ye işaret eden bir veya daha fazla önceden imzalanmış URL döndürürüz.
2. R2’ye yükle - PUT baytlarını doğrudan önceden imzalanmış URL(ler)e gönder. Baytlar sunucularımızdan geçmez.
3. Onayla - yüklemenin bittiğini bize bildirin. Bir File kaydı oluşturur ve paylaşılabilir bir URL veririz.

Temel URL

https://storage.to/api

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ış

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:

Authorization: Bearer <token>

API token oluştur

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.

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:

X-Visitor-Token: <random-string>

Web’de token otomatik olarak visitor_token cookie’sinde saklanır. CLI bunu ~/.config/storageto/token konumunda saklar (bkz. CLI dokümantasyonu).

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.

Sahip belirteci

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’ı kaynak kimliğiyle birlikte saklayın ve herhangi bir mutation işleminde şu şekilde gönderin:

Authorization: Owner <token>

Ya da kimliği doğrulanmış bir oturum için zaten Authorization: Bearer kullanıyorsanız, şu şekilde gönderin:

X-Owner-Token: <token>

Sunucu, eski ziyaretçi token’ı + IP yedeklemesine ek olarak owner token’ı geçerli bir sahiplik kanıtı olarak kabul eder - token’ı olan istemciler ağ değiştirince veya çerezleri temizleyince de çalışmaya devam eder; token’ı olmayan istemciler ise her şey aynen eskisi gibi çalışı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.

Hatalar

Hatalar tutarlı bir yapıda gelir:

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

Yaygın HTTP durum kodları:

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 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 (doğrudan R2 signed URL’lerden servis edilir).

Yükle

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.

Koleksiyonlar

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.

Dosyalar

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

ShareX yükleme

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.

Masaüstü kimlik doğrulama

Sanctum token’ı olan doğrulanmış istemciler için (ör. masaüstü uygulaması).

Diğer