Early. These endpoints power SmoothOS today and may still change. Reference documentation lives inside the product for early-access agencies; a public developer program, partner keys and outgoing webhooks aren't available yet.
المصادقة
يحمل كل طلب رمز الوصول الخاص بمستخدم مسجّل الدخول في ترويسة Authorization بوصفه Bearer token. ولا توجد مفاتيح API منفصلة. يقرأ SAI ويكتب بجلسة ذلك الشخص، فيقرر أمان مستوى الصف في قاعدة البيانات ما يمكنه رؤيته، لا النموذج. وحين تصطدم أداة بحاجز صلاحيات، لا يخمّن SAI، بل يقول إن المعلومة غير مرئية بهذا الوصول.
POST /functions/v1/sai/chat
دورة محادثة واحدة. أرسلوا message، واختياريًا السجل المعروض على الشاشة (context) وthreadId وagent وtask وlocale. وتعيد الاستجابة threadId وreply وagent (operator أو finance أو delivery أو brand أو growth) وmodel وlocale وregion وgrounding والأدوات التي استدعاها. ومن دون threadId، تُفتح محادثة جديدة إن كان يحق للمستخدم حفظ المحادثات، وإلا تكون الدورة بلا حالة وتكون قيمة threadId هي null.
curl -X POST "$SMOOTHOS_API/functions/v1/sai/chat" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "Which invoices are overdue?", "locale": "en-US", "context": {"route": "/admin"}}'POST /functions/v1/sai/action
استدعاء أداة واحد دون أي نموذج، للأدوات المصغّرة والاختصارات. أرسلوا tool وargs، واستلموا tool وresult. الأدوات المتاحة اليوم: get_financial_summary (إجماليات المدفوع والمفتوح والمتأخر والمستحق خلال 30 يومًا بحسب العملة لفترة محددة)، وget_project_kpis (الحالة والتقدم والمهام والوقت مقابل الميزانية والمفوتر والمدفوع لمشروع واحد)، وget_client_dossier (الذاكرة المعتمدة لعلامة ما). وكلها تعمل بصلاحيات المستدعي.
curl -X POST "$SMOOTHOS_API/functions/v1/sai/action" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"tool": "get_financial_summary", "args": {"from": "2026-10-01", "to": "2026-10-31"}}'POST /functions/v1/sai/context
تعيد ما سيحمّله SAI لشاشة ما: السجل والعلامة التي يتبع لها. أرسلوا سياق الصفحة مع route، وtitle اختياري، وentity اختياري يتكون من kind وid وlabel. ويبني تطبيق الويب هذا الشكل من الصفحة الحالية، وسيرسل تطبيق الجوال المخطط له لاحقًا الشكل نفسه.
اللغات
يجيب SAI دائمًا بلغة المستخدم، أيًا كانت لغة البيانات. وتُؤخذ اللغة من الحقل locale في الطلب، ثم من ترويسة Accept-Language، ثم من اللغة المحفوظة للمستخدم. ويدعم المنتج الإنجليزية والتركية والعربية.
النماذج والمفاتيح
يذهب كل دور إلى إحدى ثلاث فئات: جماعية للقراءة الطويلة (Gemini 3.6 Flash)، واستدلال للأدوات والمال والنطاق والإجابات من السجلات (Claude Sonnet 5.5)، وسريعة للأسئلة القصيرة دون سجل على الشاشة (Claude Haiku 5.5). تعمل الاستدعاءات على حسابات SmoothOS لدى المزوّدين وتُخصم من أرصدة الذكاء الاصطناعي الشهرية للوكالة؛ وعند نفادها يرد SAI بـ 402 ai_credits_exhausted. وتُسجَّل كل استدعاءات النماذج بنموذجها ورموزها وتكلفتها.
الأخطاء
401 unauthorized: الرمز مفقود أو غير صالح. 403 no_agency: المستخدم لا ينتمي إلى وكالة. 409 ai_not_configured: لم تُعِدّ الوكالة مزوّد ذكاء اصطناعي. 400 invalid_message أو unknown_tool: الرسالة أو اسم الأداة غير صالح.
ليس بعد
الاستجابات المتدفقة، وأدوات الكتابة مثل إنشاء مهمة أو صياغة فاتورة (مع خطوة موافقة لكل منها)، والإشعارات الفورية على الجوال، كلها مخطط لها ولم تُطلق بعد. ولا توجد بعد Webhooks صادرة للشركاء.
الترخيص
SmoothOS متاح المصدر بموجب Business Source License 1.1، ويصبح كل إصدار Apache 2.0 بعد ثلاث سنوات. وCommunity Edition المستضاف ذاتيًا في الطريق، مع قائمة انتظار.