توثيق API - PasteBox

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

https://pastebox.io/api/paste.php

المصادقة

مفتاح API (موصى به للسكربتات)

يمكن للمستخدمين المسجلين إنشاء مفاتيح API من ملفك الشخصي ← مفاتيح API. يصادق المفتاح الطلب باسمك دون الحاجة إلى ملف تعريف ارتباط للجلسة أو رمز CSRF. أرسله في ترويسة Authorization (أو ترويسة X-API-Key):

Authorization: Bearer pb_your_api_key

المفاتيح مرتبطة بالحساب، ولكل مفتاح حد معدل خاص به. يمكنك إيقاف أي مفتاح مؤقتا أو حذفه في أي وقت، ويمكن للمسؤول تعطيل مفاتيح بعينها أو تعطيل API بالكامل.

جلسة المتصفح (رمز CSRF)

أما الطلبات المرسلة من جلسة متصفح مسجلة الدخول فتستخدم بدلا من ذلك رمز CSRF، الذي يقرأ من الوسم في كل صفحة ويرسل كترويسة:

X-CSRF-Token: your_csrf_token

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

curl -s -H "Authorization: Bearer pb_your_api_key" \
  -d '{"content":"hello","syntax":"text"}' \
  https://pastebox.io/api/paste.php?action=create

إنشاء لصقة

POST /api/paste.php?action=create

المعاملات

المعامل	النوع	مطلوب	الوصف
content	string	نعم	محتوى اللصقة
title	string	لا	عنوان اللصقة (الافتراضي: «بدون عنوان»)
syntax	string	لا	معرف لغة تمييز بناء الجملة (الافتراضي: "plaintext")
expiration	string	لا	مدة الصلاحية: 5min, 10min, 1hour, 1day, 1week, 2weeks, 1month, 6months, 1year, never
visibility	string	لا	public أو unlisted أو private (الافتراضي: "public")
slug	string	لا	معرف الرابط المخصص (للمستخدمين المسجلين فقط، وعندما يفعل المسؤول الروابط المخصصة فقط): من 3 إلى 64 حرفا، أحرف إنجليزية صغيرة وأرقام وشرطات. يتم تجاهله للزوار، أو عند تعطيل الميزة، أو إذا كان مستخدما أو غير صالح، ويستخدم معرف عشوائي بدلا منه.
password	string	لا	كلمة مرور لحماية اللصقة
burn_after_read	boolean	لا	حذف اللصقة بعد أول عرض
encrypt	boolean	لا	تمكين التشفير على جانب الخادم

مثال على الطلب

curl -X POST https://pastebox.io/api/paste.php?action=create \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: YOUR_TOKEN" \
  -d '{
    "content": "console.log(\"Hello World\");",
    "title": "Hello World",
    "syntax": "javascript",
    "expiration": "1week",
    "visibility": "public"
  }'

مثال على الاستجابة

{
  "success": true,
  "message": "Paste created successfully.",
  "url": "https://pastebox.io/paste/abc123",
  "slug": "abc123"
}

الحصول على اللصقة الخام

GET /api/paste.php?action=raw&slug={slug}

يعيد محتوى اللصقة كنص خام. بالنسبة إلى اللصقات المحمية بكلمة مرور، مرر كلمة المرور كمعامل استعلام.

مثال

curl https://pastebox.io/api/paste.php?action=raw&slug=abc123

تنزيل اللصقة

GET /api/paste.php?action=download&slug={slug}

ينزل اللصقة كملف بالامتداد المناسب حسب لغة تمييز بناء الجملة.

حذف اللصقة

POST /api/paste.php?action=delete

حذف لصقة. متاح فقط لمالك اللصقة أو للمسؤولين.

مثال على الطلب

curl -X POST https://pastebox.io/api/paste.php?action=delete \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: YOUR_TOKEN" \
  -d '{"slug": "abc123"}'

حدود المعدل

طلبات مفتاح API: الحد الأقصى 1000 في الساعة لكل مفتاح (يحدده مسؤول الموقع، ويعاد الرمز 429 عند تجاوزه).
إنشاء اللصقات للزوار (دون مفتاح أو جلسة): 10 لصقات في الساعة لكل عنوان IP. لا يخضع المستخدمون المسجلون لحد المعدل حسب IP عند الإنشاء.
محاولات فتح القفل بكلمة المرور: 10 محاولات كل 10 دقائق لكل لصقة.
البلاغات: 5 بلاغات في الساعة لكل عنوان IP.
لا تخضع نقاط النهاية المخصصة للقراءة فقط (العرض / الخام / التنزيل) لحدود المعدل.

عند تجاوز الحد يرفض الطلب، لذا انتظر قبل إعادة المحاولة.

استجابات الأخطاء

تتبع جميع استجابات الأخطاء هذا التنسيق:

{
  "success": false,
  "message": "Error description here."
}