OpenQCoreAI
ابدأ الآن

مرجع API · الجلسات والرسائل

واجهة جلسات المحادثة والرسائل

إنشاء جلسات المحادثة وعرضها وإعادة تسميتها وتثبيتها وتمييزها بنجمة وحذفها، وإدارة الرسائل الفردية داخلها — بما في ذلك سجل التعديلات المتتبَّع والتراجع عنها.

← العودة إلى التوثيقالانتقال إلى نقاط النهاية

نقاط نهاية الجلسات

POST /api/v1/sessions
GET /api/v1/sessions
GET /api/v1/sessions/{session_id}/messages
PATCH /api/v1/sessions/{session_id}
DELETE /api/v1/sessions/{session_id}

نقاط نهاية الرسائل

GET /api/v1/messages/{message_id}
PATCH /api/v1/messages/{message_id}
GET /api/v1/messages/{message_id}/history
POST /api/v1/messages/{message_id}/undo
DELETE /api/v1/messages/{message_id}

إنشاء جلسة — نص الطلب

json
{
  "title": "Untitled Chat",
  "kind": "chat",
  "folder_id": null,
  "agent_id": null,
  "metadata": {}
}

لا يُقبَل workspace_id من العميل في وضع التشغيل الشخصي، ويجب أن يطابق سياق مساحة العمل النشطة في غير ذلك — لا يُؤخَذ أبدًا كقيمة يفرضها العميل بحرّية.

العرض — معاملات الاستعلام والاستجابة

kindagent_idpinnedlimit (الافتراضي 50، الحد الأقصى 200)offset (الافتراضي 0)
json
{
  "items": [ { "id": "...", "title": "...", "pinned": false, "...": "..." } ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

تحديث الجلسة (PATCH)

يجب أن يكون هناك حقل واحد على الأقل في نص الطلب — يُرفَض أي طلب PATCH فارغ.

titlepinnedstarredmarked_unread
json
{
  "pinned": true,
  "starred": false
}

سلوكيات الجلسة

  • تنتمي الجلسة إلى مالك واحد فقط (مستخدم، وربما مرتبطة بمساحة عمل) — يُحدَّد من سياق الطلب المصادَق عليه، لا من مدخلات العميل.
  • حذف الجلسة هو حذف ناعم (يُضبَط deleted_at)؛ تبقى الجلسة ورسائلها في قاعدة البيانات لكن تُستبعَد من كل الاستعلامات القياسية.
  • يُعيد GET /sessions/{session_id}/messages عدد رسائل يُحسَب حيًا من الرسائل نفسها، لا من عداد مخزَّن.
  • معاملات المسار session_id وmessage_id يُتحقَّق منها كمعرّفات UUID — أي معرّف غير صحيح الشكل يُعيد خطأ تحقق نظيف، لا خطأ خادم.
  • جلسات العرض التوضيحي في الموقع التسويقي محدودة بثلاث جلسات لكل مستخدم، وتُعيد 403 عند بلوغ الحد.

سجل تعديل الرسائل والتراجع

يُسجَّل كل تعديل على محتوى الرسالة أو بياناتها قبل تطبيق التغيير، بما يحافظ على النسخة السابقة.

json
[
  {
    "id": "8f14e...",
    "old_content": "Original message text",
    "old_payload": null,
    "edited_at": "2026-07-30T16:40:00Z"
  }
]
  • لا يمكن تعديل الرسالة أو حذفها إلا من قِبل مالك الجلسة التي تنتمي إليها.
  • التراجع يستعيد آخر نسخة مُسجَّلة ويحذف ذلك السجل — ولا يرجع إلى ما هو أبعد من آخر تعديل.
  • تعديل الرسالة أو حذفها لا يُعدِّل حاليًا حقل عداد الرسائل المخزَّن في الجلسة؛ فهو يعكس دومًا العدد الحي بدلًا من ذلك.

نماذج الأخطاء

400

طلب غير صالح — بما في ذلك نص PATCH فارغ أو عدم اكتشاف أي تغيير.

401

مصادقة مفقودة أو غير صحيحة.

404

الجلسة أو الرسالة غير موجودة (أو غير مملوكة لصاحب الطلب).

أمثلة

إنشاء جلسة

bash
curl -X POST "/api/v1/sessions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Chat", "kind": "chat"}'

تثبيت جلسة

bash
curl -X PATCH "/api/v1/sessions/[session_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'

تعديل رسالة

bash
curl -X PATCH "/api/v1/messages/[message_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"content": "Corrected message text"}'

التراجع عن آخر تعديل

bash
curl -X POST "/api/v1/messages/[message_id]/undo" \
  -H "Authorization: Bearer [token]"