مرجع API (OpenAPI 3.1)

يوفّر AskAIs Customer Service مواصفات OpenAPI 3.1 كاملة تصف كل نقطة نهاية عامة. وهي تشغّل مجموعات SDK المُولَّدة تلقائيًا لدينا وتعمل مع أي أداة في منظومة OpenAPI (Insomnia وPostman وSwagger UI وHoppscotch وغيرها).

الحصول على المواصفات

# Live (cached 5 min, CORS open)
curl https://cs.askais.com/api/v1/openapi.json

# Save to disk
curl https://cs.askais.com/api/v1/openapi.json -o singlink-openapi.json

عنوان URL الأساسي

• السحابة: https://cs.askais.com/api/v1
• الاستضافة الذاتية: العنوان الذي يحلّ إليه APP_URL الخاص بك، مع إضافة اللاحقة /api/v1

المصادقة

نظامان، كلاهما عبر Authorization: Bearer <value>:

• JWT جهة الاتصال — يُصدَر بواسطة POST /auth/identify. مقصور على جهة اتصال واحدة. تستخدمه مجموعات SDK للويب / للجوال.
• مفتاح API مساحة العمل — sk_live_...، يُنشَأ في الإعدادات → API Keys. يشمل مساحة العمل بأكملها. للاتصال من خادم إلى خادم.

نقاط النهاية في لمحة

• POST /auth/identify — إصدار JWT جهة اتصال
• POST /conversations — بدء محادثة جديدة
• GET /conversations — عرض محادثاتك
• GET /conversations/{id}
• GET /conversations/{id}/messages?before=&limit=
• POST /conversations/{id}/messages
• POST /upload — الحصول على عنوان POST S3 موقَّع مسبقًا
• POST /upload/{id}/confirm

الأخطاء

تستخدم جميع الاستجابات غير 2xx غلافًا ثابتًا:

{
  "error": {
    "code": "validation_error",
    "message": "content or attachments required",
    "field": "content"
  }
}

الرموز: validation_error، unauthorized، forbidden، not_found، conflict، unprocessable، rate_limit_exceeded، internal_error.

الرفيق في الوقت الفعلي

REST مناسب للاستدعاءات الفردية. للرسائل المباشرة، اتصل بـ wss://<wsUrl>/v1/ws?token=<jwt> واستمع إلى أحداث message:new وai:stream:delta وai:stream:end و typing وpresence. راجع أداة الويب للحصول على مخطط الأحداث الكامل.