خدمة الـ API — دمج المنصة

كل الواجهة تعمل عبر HTTP + SSE يمكنك استدعاؤها من أنظمتك. القاعدة: https://<نطاقك>/api/v1.

1. المصادقة (JWT)

curl -X POST $BASE/api/v1/auth/login -H 'content-type: application/json' \
  -d '{"email":"dev@acme.com","password":"…"}'   # → { access_token, refresh_token }

أرسل بعدها Authorization: Bearer <access_token> مع كل نداء.

1ب. مفاتيح API الشخصية (يُنصح بها للتكامل)

بدلاً من استخدام كلمة المرور، أنشئ مفتاح API: الإعدادات ← 🔑 مفاتيح API ← «مفتاح جديد». يظهر المفتاح (sk_live_...) مرة واحدة فقط — انسخه فوراً. حتى 20 مفتاحاً نشطاً؛ يمكن إلغاؤها في أي وقت من الصفحة نفسها.

TOKEN=$(curl -s -X POST $BASE/api/v1/auth/token -H "X-API-Key: sk_live_..." | jq -r .access_token)
curl -X POST $BASE/api/v1/chat -H "Authorization: Bearer $TOKEN" ...

يُخزَّن فقط بصمة (hash) المفتاح على الخادم. إلغاء المفتاح يمنع فوراً أي تبادل جديد؛ وتنتهي صلاحية الرمز الصادر خلال 15 دقيقة. يُحتسب الاستهلاك على رصيدك المعتاد.

2. التحدث إلى وكيل

curl -X POST $BASE/api/v1/chat -H "Authorization: Bearer $TOK" -H 'content-type: application/json' -d '{
  "message": "حلّل هذا العقد واذكر المخاطر",
  "app_name": "contract_review_dz",
  "attachments": ["<upload_id>"],
  "kb_ids": ["<kb_id>"]
}'
# → { "run_id", "session_id", "cursor" }

• app_name — الوكيل المستهدف: من الكتالوج أو وكيل مخصص: custom_<id>.
• kb_ids — استعلام وكيل مع قواعد معرفتك: يعتمد الوكيل على هذه المساحات أثناء المحادثة.
• attachments — معرفات ملفات مرفوعة عبر POST /api/v1/uploads.

3. متابعة الجواب (SSE)

curl -N $BASE/api/v1/runs/$RUN_ID/events -H "Authorization: Bearer $TOK"

الأحداث الرئيسية: token (نص الجواب)، tool_call/tool_result (استخدام أداة)، plan/plan_step (الخطة والتقدم)، document_* (مستند يُكتب بالبث)، chart (رسم بياني)، file/artifact (ملف ناتج → GET /api/v1/artifacts/{id})، usage/done/error. البث قابل للاستئناف عبر Last-Event-ID.

4. استعلام مساحة عمل (قاعدة معرفة) مباشرة

curl -N -X POST $BASE/api/v1/kb/query/stream -H "Authorization: Bearer $TOK" \
 -H 'content-type: application/json' -d '{
  "kb_id":"<kb_id>", "q":"ما بنود الفسخ؟", "enhance": true, "mode": "auto", "cite": true }'

الأوضاع: auto · quick · full · deep · graph_local · graph_global + تفكيك agent: true + استشهادات [N] + الصور المستخرجة + التكلفة لكل استعلام. التفاصيل: قواعد المعرفة.

5. ودجة قابلة للتضمين (روبوت محادثة عمومي على موقعك)

أنشئ ودجة من التكاملات → Widget ثم ألصق:

<script src="https://<النطاق>/embed.js" data-widget="<widget_key>" defer></script>

6. المشاركة العمومية

• قاعدة معرفة مشتركة: POST /api/v1/kb/{id}/share → رابط /shared-kb/<slug> قابل للاستعلام عمومياً (تُفوتر للمالك).
• مستندات / مشاريع: روابط مشاركة مماثلة.