واجهة REST API

ارفع الملفات، أنشئ مجموعات، وادِر المشاركات عبر HTTP. جميع الردود بصيغة JSON؛ لا يلزم مفتاح API لعمليات الرفع المجهولة.

مقدمة

تعمل واجهة storage.to API على تشغيل سطر الأوامر (CLI) وتطبيق سطح المكتب وأداة رفع الويب وأي عميل تابع لجهة خارجية تريد بناؤه.

تدفق الرفع على ثلاث خطوات:

تهيئة - أخبرنا أنك تريد رفع ملف. سنُرجع عنوان URL مُوقّعًا مسبقًا واحدًا أو أكثر يشير إلى Cloudflare R2.
الرفع إلى R2 - استخدم PUT لإرسال بياناتك (bytes) مباشرةً إلى عناوين URL المُوقَّعة مسبقًا. لا تمر البيانات عبر خوادمنا.
تأكيد - أخبرنا أن عملية الرفع اكتملت. سننشئ سجل File ونزوّدك بعنوان URL قابلًا للمشاركة.

عنوان URL الأساسي

https://storage.to/api

جميع نقاط النهاية أدناه مرتبطة بهذا الأساس. مثال: POST /upload/init تعني POST https://storage.to/api/upload/init.

المصادقة

تعمل عمليات الرفع المجهولة دون مصادقة، ولكن بحدود صارمة. تقتصر الاستدعاءات بدون مفتاح على 50 ملفًا لكل 24 ساعة لكل جهاز أو عنوان IP، بالإضافة إلى حصص النطاق الترددي أدناه، وتنتهي صلاحية الملفات بعد 3 أيام.

المصادقة بحساب مجاني تتيح لك:

لا يوجد حد يومي للملفات
بدون حصة لنطاق الرفع
عمليات الرفع المرتبطة بحسابك (تظهر في /dashboard)
ميزات Premium (ملفات دائمة، مساحة تخزين أكبر)
عمليات تعديل بناءً على الملكية (حذف، تعيين كلمة مرور، تغيير تاريخ الانتهاء) دون الحاجة إلى مطابقة visitor-token

نظرة سريعة على الحدود

الحد	بدون رمز (مجهول)	رمز حساب مجاني	رمز حساب مدفوع
ملفات في اليوم	50 / 24 ساعة	غير محدود	غير محدود
نطاق الرفع	100 GB / 24 ساعة (500 GB لكل عنوان IP)	غير محدود	غير محدود
الحد الأقصى لحجم الملف	25 GB	25 GB	100 GB
انتهاء صلاحية الملف	3 أيام افتراضياً وحتى 7 عبر `expiry_days`	3 أيام افتراضياً وحتى 7 عبر `expiry_days`	أبداً (الملفات دائمة)
مساحة التخزين	لا يوجد (تنتهي صلاحية الملفات)	لا يوجد (تنتهي صلاحية الملفات)	100 غيغابايت - 1 تيرابايت بشكل دائم حسب الخطة

لا توجد حصص شهرية - جميع الحدود هي نوافذ متجددة مدتها 24 ساعة أو حدود في الدقيقة. الخطة المجانية ليس لها مساحة تخزين ثابتة: كل ملف تنتهي صلاحيته من تلقاء نفسه، فلا يتراكم شيء ضمن الحصة.

للتوثيق، أنشئ رمز API شخصي من حسابك وأرسله كـ bearer token في كل طلب:

Authorization: Bearer <token>

إنشاء رمز API

تحتاج إلى تسجيل الدخول. يتم عرض الرمز الكامل مرة واحدة فقط عند الإنشاء، لذا انسخه في مكان آمن. يمكنك إلغاء أي رمز في أي وقت من نفس الصفحة.

رمز الزائر

تحتاج التطبيقات/العملاء المجهولون إلى طريقة لإثبات ملكيتهم لعمليات الرفع الخاصة بهم بدون حساب. نستخدم رمز الزائر (visitor token) - سلسلة عشوائية ينشئها العميل مرة واحدة ويعيد استخدامها. أرسلها مع كل طلب:

X-Visitor-Token: <random-string>

على الويب، يتم تخزين الرمز تلقائيًا في ملف تعريف الارتباط visitor_token. يقوم سطر الأوامر (CLI) بتخزينه في ~/.config/storageto/token (انظر مستندات CLI).

بالنسبة لنقاط النهاية الخاصة بالعمليات (delete، set password، change expiry)، يتم تأكيد الملكية إذا إما كان رمز الزائر مطابقًا أو إذا جاءت الطلب من نفس عنوان IP الذي أنشأ الملف. يمكن أن يضيع كلاهما (حذف الكوكيز، تغييرات الشبكة). يُعدّ رمز المالك هو الدليل المفضل للمضي قدمًا.

رمز المالك

كل نقطة نهاية تنشئ موردًا (/upload/init multipart، /upload/confirm، /file/reserve، /collection) تُرجع owner_token ضمن الاستجابة. الرمز هو إثبات ملكية مُوقّع مرتبط بهذا المورد تحديدًا، ومستقل عن عنوان IP أو رمز الزائر لديك.

احفظ الرمز إلى جانب معرّف المورد وأرسله مع أي عملية (mutation) كما يلي:

Authorization: Owner <token>

أو، إذا كنت تستخدم بالفعل Authorization: Bearer لجلسة مُصادَقة، أرسله كما يلي:

X-Owner-Token: <token>

يقبل الخادم رمز المالك كدليل ملكية صالح إلى جانب آلية الرجوع القديمة رمز الزائر (visitor token) + IP - فالعملاء الذين يحملون الرمز يستمرون في العمل بعد تغيير الشبكات أو مسح ملفات تعريف الارتباط، بينما العملاء الذين لا يحملونه يظلون يعملون تمامًا كما كان من قبل.

تعيش الرموز طالما أن المورد موجود، وهي آمنة للاحتفاظ بها ولا تنتهي بشكل مستقل. يعني فقدان الرمز فقدان السيطرة على ذلك المورد (الملف/المجموعة/الرفع) - تعامل معها مثل كلمات المرور المحلية.

الأخطاء

تتبع الأخطاء شكلًا ثابتًا:

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

أكواد حالة HTTP الشائعة:

الكود	المعنى
`200`	حسنًا.
`201`	تم الإنشاء.
`400`	طلب غير صالح (مثل تجاوز حد حجم المجموعة).
`401`	كلمة المرور مطلوبة أو غير صحيحة.
`403`	غير مصرح (لست مالك المورد).
`404`	لم يتم العثور على المورد أو أنه انتهت صلاحيته.
`422`	فشل التحقق، أو يوجد تقييد على الخطة/الحصة.
`429`	تم تجاوز حد المعدّل أو حصة الرفع.
`500`	خطأ في الخادم. تحقق من الحالة.

حدود المعدّل

جميع حدود المعدّل لكل عنوان IP. تتضمن استجابة 429 رؤوس Retry-After و X-RateLimit-Limit و X-RateLimit-Remaining القياسية.

النطاق	الحد
بدء الرفع / تأكيد / إلغاء	60 / دقيقة
إكمال الرفع متعدد الأجزاء	500 / دقيقة
روابط أجزاء الرفع متعدد الأجزاء	120 / دقيقة
بدء / تأكيد دفعي	500 / دقيقة
استعلامات الحالة (الملف والمجموعة)	120 / دقيقة
الإعدادات (كلمة المرور، تاريخ الانتهاء، الحد الأقصى للتنزيلات)	30 / دقيقة
التحقق من كلمة المرور	10 / دقيقة
إنشاء مجموعة	30 / دقيقة
إدارة (ready، delete)	60 / دقيقة
رفع صورة مصغّرة	120 / دقيقة
رفع عبر ShareX	20 / يوم
تحليلات التطبيق / الأخطاء	120 و 60 / دقيقة

حصة الرفع: لدى العملاء المجهولين حدّان يعملان بالتوازي - 100 جيجابايت / 24 ساعة لكل رمز الزائر (visitor token) و 500 جيجابايت / 24 ساعة لكل IP (حد IP يلتقط حركة المرور بدون رموز والشبكات المشتركة). عند تجاوز أي منهما ستحصل على 429 مع التفاصيل. هذا حدّ رفع فقط - التنزيلات غير محدودة وغير مُقيّدة (تُقدَّم مباشرة من عناوين R2 الموقعة).

رفع

تدفق الرفع من ثلاث خطوات لأي ملف، بما في ذلك الملفات التي تتجاوز 5 جيجابايت (يتم تلقائيًا تقسيمها إلى أجزاء multipart). إذا كنت تحتاج فقط إلى رفع سريع بأسلوب لقطة شاشة، فراجع ShareX بدلًا من ذلك.

POST/upload/init60/min

ابدأ عملية رفع. للملفات >50 ميجابايت تكون الاستجابة رفعًا متعدد الأجزاء (حقل type: "multipart")؛ وإلا فسيكون PUT واحد مُوقّع مسبقًا.

نص الطلب

الحقل	النوع	الوصف
`filename`	string · required	اسم الملف الأصلي. بحد أقصى 255 حرفًا.
`content_type`	string · required	نوع MIME.
`size`	integer · required	حجم الملف بالبايت. الحد الأدنى 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/partsOwner only120/min

اطلب عناوين URL إضافية للأجزاء لرفع متعدد الأجزاء قيد التنفيذ. يُستخدم عندما تُرجع /init عناوين URL أقل مما لديك من أجزاء (أو كانت قد انتهت صلاحيتها).

نص الطلب

الحقل	النوع	الوصف
`upload_id`	string · required	‏`upload_id` القادم من `/init`.
`part_numbers`	array<int> · required	أرقام الأجزاء للحصول على عناوين 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-multipartOwner only500/min

أكمل رفع متعدد الأجزاء على R2 بمجرد رفع جميع الأجزاء.

نص الطلب

الحقل	النوع	الوصف
`upload_id`	string · required	‏`upload_id` القادم من `/init`.
`parts`	array · required	كل إدخال: `{ partNumber, etag }` من استجابة R2.

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/abortOwner only60/min

ألغِ رفعًا متعدد الأجزاء ونظّف أي بيانات جزئية على R2.

نص الطلب

الحقل	النوع	الوصف
`upload_id`	string · required	الرفع الذي يجب إلغاؤه.

Request

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

POST/upload/confirm60/min

أكد أن الرفع اكتمل. عندها ننشئ سجل File ونُرجع عنوان URL القابل للمشاركة.

نص الطلب

الحقل	النوع	الوصف
`filename`	string · required	اسم الملف الأصلي.
`size`	integer · required	حجم الملف بالبايت.
`content_type`	string · required	نوع MIME.
`r2_key`	string · required	‏`r2_key` القادم من `/init`.
`collection_id`	string · optional	إرفاقه إلى مجموعة.
`crc32`	integer · optional	مجموع CRC32 للتحقق من سلامة البيانات.
`file_id`	string(9) · optional	إتمام معرف ملف محجوز سابقًا.

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

احجز معرف ملف وعنوان URL قابل للمشاركة قبل أن تصبح البيانات جاهزة. مفيد عندما تحتاج إلى مشاركة رابط أولًا ثم إتمام الرفع لاحقًا. ترتبط الملكية برمز الزائر + عنوان IP الخاصين بك. أنهِ الرفع لاحقًا باستخدام /upload/init + /upload/confirm، مع تمرير file_id للتأكيد.

نص الطلب

الحقل	النوع	الوصف
`filename`	string · optional	اسم ملف بديل. القيمة الافتراضية هي `"Pending"`.
`content_type`	string · optional	نوع MIME بديل.

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

مكافئ الدفعات لـ /upload/init، مُحسّن لرافع الويب. يبدأ حتى 250 ملفًا في رحلة واحدة.

يُستخدم داخليًا بواسطة رافع الويب. يجب أن يفضّل معظم العملاء استخدام /upload/init لملف واحد.

POST/upload/confirm-batch500/min

مكافئ الدفعات لـ /upload/confirm. يؤكد رفع العديد من الملفات في رحلة واحدة.

المجموعات

تجمع المجموعة عدة ملفات تحت عنوان URL واحد للمشاركة (/c/{id}). حتى 10,000 ملف وبإجمالي 25 جيجابايت.

POST/collection30/min

أنشئ مجموعة جديدة. أرفق الملفات لاحقًا عبر تمرير collection_id على /upload/confirm.

نص الطلب

الحقل	النوع	الوصف
`expected_file_count`	integer · optional	تلميح لتعليم المجموعة تلقائيًا أنها جاهزة بمجرد تأكيد جميع الملفات المتوقعة.

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

استعلم عن حالة المجموعة. كما يعلّم المجموعة تلقائيًا أنها جاهزة إذا تم تأكيد جميع الملفات المتوقعة.

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}/readyOwner only60/min

علّم المجموعة على أنها جاهزة للتنزيل. هذا ليس مطلوبًا عادةً - تصبح المجموعات جاهزة تلقائيًا بمجرد الوصول إلى expected_file_count.

DELETE/collection/{id}Owner only60/min

احذف مجموعة وجميع ملفاتها.

POST/collection/{id}/passwordOwner only30/min

عيّن كلمة مرور للمجموعة. تتطلب 4–100 حرفًا.

نص الطلب

الحقل	النوع	الوصف
`password`	string · required	4–100 حرفًا.

Request

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

DELETE/collection/{id}/passwordOwner only30/min

إزالة كلمة المرور من المجموعة.

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

تحقق من كلمة المرور. تُرجع 200 عند النجاح و 401 عند كلمة مرور غير صحيحة.

نص الطلب

الحقل	النوع	الوصف
`password`	string · required

POST/collection/{id}/expiryOwner only30/min

تغيير مدة انتهاء صلاحية المجموعة (collection).

نص الطلب

الحقل	النوع	الوصف
`days`	integer · optional	من الآن خلال 1–7 أيام. احذفها أو استخدم `null` للمدة الدائمة (فقط للمميز).

POST/collection/{id}/max-downloadsOwner only30/min

حدّد سقفًا للتنزيل (burn-after-N-downloads). يتم حذف المجموعة تلقائيًا عند الوصول إلى الحد.

نص الطلب

الحقل	النوع	الوصف
`max_downloads`	integer · optional	1–1000. يجب أن يتجاوز عدد التنزيلات الحالي. استخدم `null` لإزالة السقف.

الملفات

تطابق جميع إعدادات مستوى الملف (كلمة المرور، الانتهاء، الحد الأقصى للتنزيلات) نقاط نهاية المجموعة. للمالك فقط.

GET/file/{id}/status120/min

تحقق مما إذا كان الملف لا يزال بانتظار رفعه.

Response

{ "pending": false }

DELETE/file/{id}Owner only60/min

احذف الملف فورًا.

POST/file/{id}/thumbnailOwner only120/min

ارفع صورة مصغّرة لفيديو أو ملف صورة (تُستخدم في صفحة التنزيل). بحد أقصى 2 ميجابايت.

نص الطلب

الحقل	النوع	الوصف
`thumbnail`	image · required	رفع متعدد الأجزاء. بحد أقصى 2 ميجابايت.

Response

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

POST/file/{id}/passwordOwner only30/min

عيّن كلمة مرور لملف. تتطلب 4–100 حرفًا.

DELETE/file/{id}/passwordOwner only30/min

إزالة كلمة مرور الملف.

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

التحقق من كلمة مرور الملف.

POST/file/{id}/expiryOwner only30/min

تغيير مدة انتهاء صلاحية الملف.

نص الطلب

الحقل	النوع	الوصف
`days`	integer · optional	من الآن خلال 1–7 أيام. احذفها أو استخدم `null` للمدة الدائمة (فقط للمميز).

POST/file/{id}/max-downloadsOwner only30/min

تحديد الحد الأقصى لإجمالي تنزيلات الملف. يتم الحذف تلقائيًا عند الوصول إلى الحد.

رفع عبر ShareX

نقطة رفع بنقرة واحدة - أرسل ملفًا متعدد الأجزاء (multipart) وستحصل على رابط قابل للمشاركة. لا توجد رقصة init/confirm. مثالي لأدوات لقطات الشاشة. دليل الإعداد الكامل في /docs/sharex.

POST/sharex/upload20/day

ارفع صورة أو ملفًا مباشرةً (نموذج multipart، حقل file). بحد أقصى 25 ميجابايت.

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" }

مصادقة سطح المكتب

للعملاء الموثّقين (مثل تطبيق سطح المكتب) الذين يحملون رمز Sanctum.

GET/userBearer token

إرجاع المستخدم المُصادَق عليه.

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

إبطال رمز الوصول الحالي.

متفرقات

GET/health

فحص الجاهزية. يعيد 200 مع { "status": "ok" } عندما يكون عامل الـ API يعمل.

Response

{ "status": "ok" }

GET/activity

بث نشاط مباشر لواجهة الكرة على الصفحة الرئيسية. يتم تخزينه مؤقتًا على حافة Cloudflare.

GET/bandwidth/status60/min

استخدام حصة الرفع الحالية للمتصل - يستخدمه CLI وتطبيق سطح المكتب لعرض السعة المتبقية. شكل الاستجابة يختلف للمستخدمين المُعرّفين. وعلى الرغم من اسم الرابط، فهذا يتتبع رفع بالبايت فقط؛ لا يتم احتساب التنزيلات.

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) أو تطبيق سطح المكتب.

نص الطلب

الحقل	النوع	الوصف
`app`	string · required	`desktop` أو `cli` أو `web`.
`version`	string · optional	إصدار العميل.
`event`	string · required	اسم الحدث، مثل `upload_complete`.
`context`	object · optional	بيانات تعريف إضافية.

POST/app-errors60/min

أرسل تقرير خطأ من CLI أو تطبيق سطح المكتب. إزالة التكرار تتم على الخادم - بحد أقصى 10 من نفس الخطأ لكل ساعة.

نص الطلب

الحقل	النوع	الوصف
`app`	string · required	`desktop` أو `cli` أو `web`.
`type`	string · required	فئة/نوع الخطأ.
`message`	string · required	رسالة الخطأ.
`stack`	string · optional	تتبّع المكدس (Stack trace).
`version`, `os`, `os_version`, `arch`, `context`	various · optional	بيانات تعريف تشخيصية.