مبنيّ للوكلاء لا للمتصفحات فقط: كيف تعمل الواجهة البرمجية
كل أداة في الكتالوج نقطة نهاية REST تحت /api/v1/ مع خادم MCP عند /mcp. الاستدعاء المجهول بلا حساب ولا مفتاح، والأخطاء بصيغة RFC 7807.

لا يزال بإمكانك العمل من لسان المتصفح: تختار أداة، وترفع ملفاً، وتنزّل النتيجة. أما الوكلاء والسكربتات فيستدعون العمليات ذاتها من دون فتح أي واجهة. وكلا المسارين يصل إلى الكتالوج نفسه.
كل صفحة أداة هي أيضاً نقطة نهاية
دمج والتقسيم والضغط وOCR والتحويل: لكل أداة في الكتالوج مسار تحت /api/v1/…. افتح صفحة أي أداة وامرر إلى Call this from code لترى مثال curl مبنيّاً من معاملات تلك الأداة الحقيقية، لا قالباً عاماً. ولا تحتاج الاستدعاءات المجهولة إلى حساب ولا إلى مفتاح API على الموقع العام؛ وبادئات المسارات المجهولة هي /api/v1/general/ و/api/v1/misc/ و/api/v1/security/ و/api/v1/convert/ و/api/v1/filter/.
مثال الدمج ملموس:
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
تجد OpenAPI عند /v1/openapi.json. وتستخدم المهام متعددة الخطوات POST /api/v1/pipeline مع قائمة steps مرتّبة. أرسل Idempotency-Key حين يجب ألا تُعاد مهمة مُعدِّلة عند إعادة المحاولة. وتُعلن الردود المستضافة ترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset وعند استجابة HTTP 429 اقرأ Retry-After (تحديد معدل الطلبات المجهولة).
ويعيد OCR عبر الكتالوج نفسه صيغة Markdown (text/markdown) من /api/v1/misc/ocr-pdf افتراضياً. وعند إرسال outputFormat=pdf تعيد نقطة النهاية نفسها ملف PDF قابلاً للبحث بدلاً من ذلك (application/pdf، حتى 50 صفحة، ويجري التعرّف عليه بواسطة Tesseract). وينبغي للوكيل أن يقرأ Content-Type في الاستجابة بدلاً من افتراض أن التنزيل نصي، لأن الناتجين يأتيان من محرّكين مختلفين وبحدود مختلفة.
MCP للعملاء الذين يتحدثون به
يتيح MCP (بروتوكول سياق النموذج) لعملاء الوكلاء استكشاف الأدوات واستدعاءها كدوال، بدل كشط التوثيق. ويعرض هذا الموقع خادم MCP عند /mcp إلى جانب واجهة REST، فيتصل العميل المتوافق مرة واحدة ويحصل على الكتالوج كاملاً.
ويشترك MCP وREST في توقعات المصادقة نفسها: استدعاء مجهول حيث تسمح بادئات الأدوات، ومفاتيح API للأتمتة المستقرة وللخوادم ذاتية الاستضافة المقيّدة. وتوجيه وكيل إلى /mcp ليس منتجاً مختلفاً عن توجيه curl إلى /api/v1/…. التوثيق: MCP للمطوّرين.
الأخطاء منظّمة لا نصوص حرّة
تعيد الأعطال application/problem+json (بأسلوب RFC 7807)، لا استجابة 500 عارية ولا «حدث خطأ ما». ويحمل كل رد رمزاً مستقراً، مثل rate_limited وbad_request وinvalid_document وmissing_dependency ونظائرها، وتلميحاً مقروءاً، وخطوة تالية في كثير من الحالات. يستطيع الإنسان تصفّحه، ويستطيع الوكيل أن يقرر إعادة المحاولة أو تبديل الملف أو التوقف من دون أن يحلل أحدهم أثر المكدس.
ويتجاوز هذا البناء فائدة صفحة خطأ HTML الودودة حين يكون المستدعي سكربتاً. المرجع: أخطاء المطوّرين.
llms.txt لأدوات البرمجة لا للترتيب
/llms.txt فهرس نصي بسيط لكل أداة (الاسم، والوصف، والرابط)، مولّد من الكتالوج ذاته الذي يقود الموقع. يستطيع وكلاء البرمجة وأدوات التوثيق قراءته كما يقرأون ملف README. وهو ليس رافعة ترتيب في Google: يتجاهل البحث /llms.txt (المصادر: دليل Google لتحسين البحث بالذكاء الاصطناعي). ولأنه مولّد، لا يمكن أن يتقادم صامتاً كما يتقادم ملف يُحرَّر يدوياً.
CLI والمهارة يتشاركان الأشكال نفسها
pdfx عميل لسطح REST نفسه، يوجَّه إلى عنوان أساسي مع مفتاح API اختياري، فيرسل طلب multipart الذي يرسله curl بدل كشف كتالوج ثانٍ. وتوثّق المهارة المنشورة عند /skills/pdf123.md أشكال الدمج وخطوط المعالجة، كي لا يخترع الوكلاء عقداً ثانياً هم أيضاً. أربعة عملاء وكتالوج واحد: العملية نفسها، أربعة عملاء.
مسار المتصفح لم يتغير
ما زال إسقاط ملف في لسان المتصفح يعمل كما هو. والسطح الإضافي هو نقاط النهاية ذاتها لوكيل أو سكربت أو CI: المعالجة نفسها، بلا إنسان في المنتصف. وتحتفظ الاستضافة الذاتية بهذا السطح داخل شبكتك (الاستضافة الذاتية)، وتبقى الاستضافة العامة مسار التجربة المجهولة.
مرجع الواجهة البرمجية: Swagger. ولأساسيات أي من المسارين: المساعدة والمطوّرون.