سجل التغييرات

تتتبّع هذه الصفحة التغييرات على عقد واجهة المطورين كي تتمكن من تتبّع السطح الذي يعتمد عليه تكاملك.

v1 — مستقر (2026-06)

الإصدار العام الأول لواجهة المطورين من Cuneiform Chat. v1 هو العقد الحالي المستقر ويُرسي خط الأساس لكل ما هو موثّق في هذا المرجع:

• المصادقة — وصول محمي بالاعتماد باستخدام key بصيغة cuk_<env>_<random>، تُقدَّم كـ Authorization: Bearer cuk_… أو X-API-Key: cuk_…. خمسة scopes: knowledge:read، knowledge:write، agents:read، agents:write، agents:query.
• Knowledge — رفع المستندات غير المتزامن، والعرض، والبحث، والجلب، والحالة (الاستفسار + SSE)، والحذف؛ وCRUD للمجلدات وtags؛ وتنظيم المستندات (النقل إلى مجلد، إضافة/إزالة tags).
• Agents — إنشاء، وعرض، وجلب، وتحديث، وأرشفة (soft-delete)، واستعادة؛ وقراءة وتحديث ضبط agent.
• استعلام Agent — تشغيل agent في وضع JSON الحاجب أو وضع SSE المتدفق.
• الاتفاقيات — الترقيم بمؤشر مُبهَم، وعقد Idempotency-Key، وغلاف الخطأ بأسلوب Stripe، وترويسات RateLimit-*.

كيف يتطوّر العقد

v1 إضافي ومستقر:

• قد تُقدَّم حقول جديدة وendpoints جديدة ضمن v1.
• لا تُحذف الحقول الموجودة أو يُعاد توظيفها أبدًا ضمن v1.
• لا يُعاد توظيف فئات الأخطاء أبدًا — قد تُضاف فئة جديدة، لكن فئة موجودة تحتفظ بمعناها، لذا من الآمن التفريع بناءً على type الخطأ.

سيصدر أي تغيير كاسر تحت بادئة إصدار جديدة (/v2)، لا بصمت ضمن v1 أبدًا.