نظرة عامة على API

واجهة REST عامة تحت /api/v1، للقراءة والكتابة على الوثائق والوسوم وأنواع الوثائق والمساحات من خارج التطبيق — سكربت، تكامل مع نظام آخر، أو أداة مثل Postman.

التوثيق

كل طلب يحمل ترويسة Authorization: Bearer <مفتاح>. أنشئ المفتاح من الإعدادات ← مفاتيح API. المفتاح يرث صلاحيات صاحبه على المساحات — لا وصول أوسع منها.

curl https://your-instance.example/api/v1/documents \
  -H "Authorization: Bearer osk_..."

نقاط النهاية

المسار	الوصف
`GET /documents`	قائمة الوثائق، مع فلاتر مساحة/نوع/وسم/تاريخ ونص بحث (صفحات، حتى 100 عنصر لكل صفحة)
`POST /documents`	رفع وثيقة (multipart، حتى 100 ميغابايت)
`GET /documents/{id}`	تفاصيل وثيقة مع مقتطف من النص المستخرج
`PATCH /documents/{id}`	تعديل العنوان أو الوسوم أو النوع أو المساحة
`DELETE /documents/{id}`	نقل إلى سلة المحذوفات
`POST /documents/bulk`	نقل أو حذف أو وسم جماعي
`GET /documents/inbox`	الوثائق التي لم تُفرز بعد
`POST /documents/{id}/inbox/clear`	اعتبار الوثيقة مفروزة
`GET /documents/{id}/ai-suggestions`	اقتراح النوع والوسوم المحفوظ للوثيقة
`GET /documents/{id}/history`	إصدارات الوثيقة وسجل تغييراتها
`GET /documents/{id}/revisions/{revId}/file`	تنزيل ملف إصدار سابق من الوثيقة
`GET /tags` · `POST /tags`	قراءة/إنشاء وسوم
`GET /document-types`	قائمة الأنواع مع حقولها المخصصة
`GET /spaces`	المساحات المرئية لصاحب المفتاح
`GET /search`	بحث نصي عبر محرك Meilisearch مباشرة
`GET /exports/{id}/download`	تنزيل أرشيف تصدير جاهز (لمديري النظام)
`GET /auth-methods`	طرق تسجيل الدخول المتاحة في هذا التثبيت، دون توثيق
`GET /health`	فحص حيّ، دون توثيق

كل استجابة خطأ تأتي بالشكل {"error": {"code": "...", "message": "..."}}.

حدود معدل الطلبات

الافتراضي 60 طلبا في الدقيقة لكل مستخدم ولكل نقطة نهاية — مفتاحان يملكهما المستخدم نفسه يتشاركان الحد ذاته. تجاوز الحد يعيد 429 مع ترويسة Retry-After تحمل عدد الثواني المتبقية.

المواصفة الكاملة

مواصفة OpenAPI 3.1 كاملة، آلية القراءة، متاحة على /api/v1/openapi — استوردها مباشرة في Postman أو Bruno أو أي عارض OpenAPI. هي المرجع النهائي لشكل كل طلب واستجابة؛ الجدول أعلاه خريطة، لا بديل عنها.