REST API

Dosya yükleyin, koleksiyonlar oluşturun ve paylaşımları HTTP üzerinden yönetin. Tüm yanıtlar JSON formatındadır; 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 süreci üç adımdan oluşur:

Başlat — bir dosya yüklemek istediğinizi söyleyin. Cloudflare R2'ye işaret eden bir veya daha fazla ön imzalı URL döneriz.
R2'ye yükle — Baytlarınızı doğrudan ön imzalı URL(ler)e PUT. Baytlar sunucularımızdan geçmez.
Onayla — yüklemenin tamamlandığını 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 URL'ye göredir. Örnek: POST /upload/init, POST https://storage.to/api/upload/init anlamına gelir.

Kimlik doğrulama

Çoğu uç nokta kimlik doğrulama gerektirmez. Anonim yüklemeler temel bir özelliktir.

Kimlik doğrulama isteğe bağlıdır ve şunları açar:

Hesabınıza bağlı yüklemeler (/dashboard'da görünür)
Premium özellikler (kalıcı dosyalar, daha büyük depolama)
Ziyaretçi token eşleşmesi olmadan sahiplik tabanlı değişiklikler (silme, şifre belirleme, süresi değiştirme)

Laravel Sanctum bearer tokenları kullanıyoruz. Masaüstü OAuth devri veya web girişinden bir token alın, sonra şu şekilde gönderin:

Authorization: Bearer <token>

Ziyaretçi tokenı

Anonim istemcilerin hesap olmadan kendi yüklemelerinin sahipliğini kanıtlaması gerekir. Bir ziyaretçi tokenı kullanıyoruz — istemcinin bir kez oluşturup tekrar kullandığı rastgele bir dize. Her istekte gönderin:

X-Visitor-Token: <random-string>

Web’de token otomatik olarak visitor_token çerezinde saklanır. CLI ise bunu ~/.config/storageto/token konumunda saklar (bkz. CLI dokümanları).

Değişiklik uç noktalarında (silme, şifre belirleme, süresi değiştirme), sahiplik şu durumlarda doğrulanır: ya da ziyaretçi tokenı eşleşir veya istek dosyayı oluşturan aynı IP’den gelir.

Hatalar

Hatalar tutarlı bir biçimde olur:

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

Yaygın HTTP durum kodları:

Kod	Anlam
`200`	Tamam.
`201`	Oluşturuldu.
`400`	Geçersiz istek (ör. koleksiyon boyutu sınırı aşıldı).
`401`	Şifre gerekli veya yanlış.
`403`	Yetkisiz (kaynak sahibi değil).
`404`	Kaynak bulunamadı veya süresi doldu.
`422`	Doğrulama başarısız oldu veya plan/kota kısıtlaması.
`429`	Hız sınırı veya yükleme kotası aşıldı.
`500`	Sunucu hatası. durum değerini kontrol edin.

Hız sınırları

Tüm hız sınırları IP başına uygulanır. 429 yanıtı standart Retry-After, X-RateLimit-Limit ve X-RateLimit-Remaining başlıklarını içerir.

Kapsam	Limit
Yükleme başlat / onayla / iptal et	60 / dakika
Parçalı yükleme tamamlanması	500 / dakika
Parçalı yükleme parça URL’leri	120 / dakika
Toplu işlem başlat / onayla	500 / dakika
Durum sorgulamaları (dosya ve koleksiyon)	120 / dakika
Ayarlar (şifre, son kullanma, maksimum indirme)	30 / dakika
Şifre doğrulama	10 / dakika
Koleksiyon oluştur	30 / dakika
Yönet (hazır, sil)	60 / dakika
Küçük resim yükleme	120 / dakika
ShareX yüklemesi	20 / gün
Uygulama analizleri / hatalar	Dakikada 120 ve 60

Yükleme kotası: Anonim istemcilerin paralel olarak iki sınırı vardır — Her ziyaretçi tokenı için 24 saatte 100 GB ve Her IP için 24 saatte 500 GB (IP sınırı token'sız trafiği ve paylaşılan ağları yakalar). Herhangi biri aşılırsa detaylarla birlikte 429 alırsınız. Bu sadece bir yükle kota — indirmeler sınırsız ve kısıtlanmamıştır (R2 imzalı URL'lerden doğrudan sunulur).

Yükle

Herhangi bir dosya için üç aşamalı yükleme akışı, 5 GB üzeri dosyalar dahil (otomatik olarak parçalı). Sadece hızlı ekran görüntüsü tarzı yükleme istiyorsanız, onun yerine ShareX’e bakın.

POST /upload/init 60/min

Bir yüklemeyi başlatın. 50 MB üzeri dosyalar için yanıt, parçalı yükleme için part_urls içerir; aksi takdirde tek bir url.

İstek gövdesi

Alan	Tür	Açıklama
`filename`	string · required	Orijinal dosya adı. Maksimum 255 karakter.
`content_type`	string · required	MIME türü.
`size`	integer · required	Dosya boyutu bayt cinsinden. Minimum 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, "url": "https://r2.cloudflarestorage.com/...signed...", "r2_key": "uuid-abc123", "upload_id": null, "is_multipart": false }

Response · multipart

{ "success": true, "upload_id": "01HXYZ...", "r2_key": "uuid-abc123", "is_multipart": true, "part_size": 52428800, "part_urls": [ { "partNumber": 1, "url": "https://..." }, { "partNumber": 2, "url": "https://..." } ] }

POST /upload/parts 120/min

Devam eden parçalı yükleme için ek parça URL’leri isteyin. /init, sahip olduğunuz parçalardan daha az URL döndürdüğünde (veya URL’ler süresi dolduğunda) kullanılır.

İstek gövdesi

Alan	Tür	Açıklama
`upload_id`	string · required	`/init`’den alınan `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-multipart 500/min

Tüm parçalar yüklendikten sonra R2’de parçalı yüklemeyi tamamla.

İstek gövdesi

Alan	Tür	Açıklama
`upload_id`	string · required	`/init`’den alınan `upload_id`.
`parts`	array · required	Her giriş: R2 yanıtından `{ 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/abort 60/min

Parçalı yüklemeyi iptal et ve R2’deki kısmi 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/confirm 60/min

Yüklemenin tamamlandığını onayla. Bu aşamada File kaydı oluşturulur ve paylaşılabilir URL döner.

İstek gövdesi

Alan	Tür	Açıklama
`filename`	string · required	Orijinal dosya adı.
`size`	integer · required	Dosya boyutu bayt cinsinden.
`content_type`	string · required	MIME türü.
`r2_key`	string · required	`/init`’den alınan `r2_key`.
`collection_id`	string · optional	Bir koleksiyona ekle.
`crc32`	integer · optional	Bütünlük doğrulaması için CRC32 kontrol toplamı.
`file_id`	string(9) · optional	Önceden rezerve edildi verilen dosya ID’sini tamamla.

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", "raw_url": "https://storage.to/r/FQxyz1234", "filename": "report.pdf", "size": 2202009, "human_size": "2.1 MB", "expires_at": "2026-04-15T12:00:00Z" } }

POST /file/reserve 60/min

Baytlar hazır olmadan önce bir dosya ID’si ve paylaşılabilir URL ayırın. Önce bir bağlantı vermeniz ve yüklemeyi sonra tamamlamanız gerektiğinde faydalıdır. Sahiplik ziyaretçi token’ınız ve IP’nize bağlıdır. Yüklemeyi daha sonra /upload/init + /upload/confirm ile tamamlayın, onaylamak için file_id gönderin.

İ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", "raw_url": "https://storage.to/r/FQxyz1234", "expires_at": "2026-04-12T18:00:00Z" } }

POST /upload/init-batch 500/min

Web yükleyici için optimize edilmiş /upload/init'in toplu eşdeğeri. Tek seferde 250 dosyaya kadar 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-batch 500/min

/upload/confirm'un toplu eşdeğeri. Bir seferde birçok dosyayı onaylar.

Koleksiyonlar

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

POST /collection 30/min

Yeni bir koleksiyon oluşturun. Dosyaları daha sonra /upload/confirm üzerinde collection_id ile ekleyin.

İstek gövdesi

Alan	Tür	Açıklama
`expected_file_count`	integer · optional	Tüm beklenen dosyalar onaylandığında 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" } }

GET /collection/{id}/status 120/min

Bir koleksiyonun durumunu sorgula. Ayrıca tüm beklenen 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}/ready Owner only 60/min

Koleksiyonu indirmeye hazır olarak işaretle. Genellikle gerekmez — koleksiyonlar expected_file_count ulaşıldığında otomatik olarak hazır olur.

DELETE /collection/{id} Owner only 60/min

Bir koleksiyonu ve içindeki tüm dosyaları sil.

POST /collection/{id}/password Owner only 30/min

Koleksiyona şifre belirle. 4–100 karakter gerektirir.

İ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}/password Owner only 30/min

Bir koleksiyondan şifreyi kaldır.

POST /collection/{id}/verify-password 10/min

Şifreyi kontrol et. Başarılıysa 200, yanlış şifre ise 401 döner.

İstek gövdesi

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

POST /collection/{id}/expiry Owner only 30/min

Bir koleksiyonun son kullanma tarihini değiştir.

İstek gövdesi

Alan	Tür	Açıklama
`days`	integer · optional	Şimdiden itibaren 1–7 gün. Kalıcı için boş bırakın veya `null` kullanın (sadece premium).

POST /collection/{id}/max-downloads Owner only 30/min

İndirme sınırı belirle (N indirmeden sonra sil). Sınır aşıldığında koleksiyon otomatik silinir.

İstek gövdesi

Alan	Tür	Açıklama
`max_downloads`	integer · optional	1–1000. Mevcut indirme sayısından yüksek olmalı. Sınırı kaldırmak için `null` kullan.

Dosyalar

Tüm dosya düzeyi ayarlar (şifre, son kullanma, maksimum indirme) koleksiyon uç noktalarıyla eşleşir. Sadece sahibi yapabilir.

GET /file/{id}/status 120/min

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

Response

{ "pending": false }

DELETE /file/{id} Owner only 60/min

Bir dosyayı hemen sil.

POST /file/{id}/thumbnail Owner only 120/min

Bir video veya resim dosyası için küçük resim yükle (indirme sayfasında kullanılır). Maksimum 2 MB.

İstek gövdesi

Alan	Tür	Açıklama
`thumbnail`	image · required	Parçalı yükleme. Maksimum 2 MB.

Response

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

POST /file/{id}/password Owner only 30/min

Bir dosyaya şifre belirle. 4–100 karakter gerektirir.

DELETE /file/{id}/password Owner only 30/min

Bir dosyanın şifresini kaldır.

POST /file/{id}/verify-password 10/min

Bir dosyanın şifresini doğrula.

POST /file/{id}/expiry Owner only 30/min

Bir dosyanın son kullanma tarihini değiştir.

İstek gövdesi

Alan	Tür	Açıklama
`days`	integer · optional	Şimdiden itibaren 1–7 gün. Kalıcı için boş bırakın veya `null` kullanın (sadece premium).

POST /file/{id}/max-downloads Owner only 30/min

Bir dosyanın toplam indirme sayısını sınırla. Sınır aşıldığında otomatik silinir.

ShareX yüklemesi

Tek seferlik yükleme noktası — çok parçalı bir dosya gönderin, paylaşılabilir bir URL alın. Başlat/onayla işlemi yok. Ekran görüntüsü araçları için ideal. Tam kurulum rehberi /tr/docs/sharex adresinde.

POST /sharex/upload 20/day

Bir resim veya dosyayı doğrudan yükle (parçalı form, file alanı). Maksimum 25 MB.

Request

curl -X POST https://storage.to/api/sharex/upload \ -F "[email protected]"

Response

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

Masaüstü kimlik doğrulaması

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

GET /user Bearer token

Kimlik 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": "[email protected]", "is_premium": true }

POST /auth/logout Bearer token

Mevcut erişim token'ını iptal et.

Çeşitli

GET /health

Sağlık kontrolü. Veritabanı, R2 depolama ve Redis önbelleğine ping atar. Hepsi iyi ise 200, aksi halde 503 döner.

Response

{ "status": "healthy", "checks": { "database": "ok", "storage": "ok", "cache": "ok" }, "timestamp": "2026-04-12T12:00:00Z" }

GET /activity

Anasayfa küresi için canlı etkinlik akışı. Cloudflare kenarında önbelleğe alınmıştır.

GET /bandwidth/status 60/min

Çağıranın mevcut yükleme kota kullanımı — CLI ve masaüstü uygulaması tarafından kalan kapasiteyi göstermek için kullanılır. Yanıt yapısı kimlik doğrulanmış kullanıcılar için farklıdır. URL adına rağmen, sadece yükle baytları 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-analytics 120/min

Kullanım olayını CLI veya masaüstü uygulamasından 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ı, örn. `upload_complete`.
`context`	object · optional	Ek meta veriler.

POST /app-errors 60/min

Hata raporunu CLI veya masaüstü uygulamasından gönder. Sunucu tarafında çoğaltma önlenir — saatte aynı hatadan 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	Yığın izleme (stack trace).
`version`, `os`, `os_version`, `arch`, `context`	various · optional	Tanısal meta veriler.