مرجع API
الأساس https://ai.syctra.com/api/v1 · كل نقطة نهاية تتطلّب Authorization: Bearer <token>
ما لم تُعلَّم عام. راجع API والتكامل الأصلي للمصادقة والأخطاء والحدود والأمن.
التشغيلات — التحدّث إلى وكيل
POST /chat
يبدأ تشغيلاً دائماً ويردّ فوراً.
| الحقل | النوع | الافتراضي | الوصف |
|---|
message | string | — | مطلوب. ما تطلبه من الوكيل |
app_name | string | "main" | الوكيل الهدف. أي مفتاح من الفهرس (interactive، data_copilot، contract_review_dz، slide_master، finance_master…) أو custom_<id> لأحد وكلائك |
session_id | uuid | جديد | متابعة محادثة قائمة. اتركه فارغاً لبدء واحدة |
attachments | string[] | — | معرّفات من POST /uploads |
kb_ids | string[] | — | قواعد المعرفة التي يجوز للوكيل البحث فيها |
kb_enhance | bool | false | إعادة صياغة إجابات RAG بالنموذج (أبطأ، أغنى) |
plan | bool | false | وضع الخطة: يكتب الوكيل خطة خطوات وينفّذها، ويُصدر plan / plan_step |
model | string | افتراضي الحساب | مفتاح من فهرس النماذج — راجع GET /models |
reasoning | bool | false | تفكير أطول قبل الإجابة |
data_workspace_id | uuid | — | مساحة Data Lab التي يعمل عليها |
client_tz | string | UTC | منطقة IANA، مثل "Africa/Algiers" |
idempotency_key | string | — | آمن للإعادة: المفتاح نفسه يُرجع التشغيل نفسه |
{ "run_id": "…", "session_id": "…", "cursor": 0, "resumed": false,
"status": "running", "queue_seq": 0 }
status يكون running، أو queued إذا كانت الجلسة مشغولة (يبدأ تلقائياً عند انتهاء سابقه)،
أو blocked.
| الطريقة | المسار | الغرض |
|---|
POST | /tasks | مثل /chat لكن منفصل صراحةً — للمهام الخلفية |
GET | /runs/{run_id}/events | بثّ SSE للتشغيل (أدناه) |
POST | /runs/{run_id}/respond | الإجابة عن سؤال طرحه الوكيل (user_choice، quiz، موافقة) |
POST | /runs/{run_id}/cancel | إيقاف تشغيل جارٍ |
GET | /sessions/{id}/queue | فحص طابور الجلسة |
POST | /sessions/{id}/queue/resume | استئناف طابور أوقفه خطأ |
GET /runs/{run_id}/events — البثّ
text/event-stream. كل حدث يحمل id (رقم seq تصاعدي) وevent (نوعه) وdata (JSON).
قابل للاستئناف: أعد الاتصال بـ Last-Event-ID: <seq> أو ?after=<seq> فيُعاد بثّ كل ما بعد
هذا المؤشّر من التخزين الدائم — لا يضيع عمل ولا تتكرّر فوترة.
| المجموعة | الأحداث |
|---|
| الإجابة | token (شذرة نص) · usage (عدّاد الرموز) · done · error |
| الأدوات | tool_call · tool_result · sandbox_stdout |
| الخطة | plan (خطوات مرتّبة) · plan_step (الفهرس + الحالة) |
| المستندات | document_start · document_delta · document_end (يحمل artifact_id) |
| المخرجات | artifact · file (PDF/DOCX/PPTX/XLSX) · image · slides · webpage · chart · sheet |
| البحث | sources (نتائج الويب) · graph (رسم المعرفة) · browser (لقطات المتصفّح) · maps |
| تدخّل الإنسان | user_choice · choice_answer · quiz · approval (إجراء بانتظار تأكيدك) |
| الاتصال | email_draft · email_sent · social · call |
| الاستوديوهات القانونية | dossier · timeline · doc_summary · findings · contract · clause · contract_compare · consultation · legal_issues · ref_check · deadline · watch_synthesis · watch_change · watch_diff |
| التوظيف | candidate · iv_job · iv_candidate · iv_questions · iv_grid · iv_answers · iv_ask · iv_plan |
| الأعمال | prospect · cerfa · exhibition · finance · site_map · site_pack |
استهلك token وdone وerror للحصول على إجابة نصية بسيطة؛ الباقي بطاقات مهيكلة يمكنك عرضها
أو تجاهلها. الأنواع غير المعروفة يجب تخطّيها لا اعتبارها أخطاء — تُضاف أنواع جديدة مع الوقت.
| الطريقة | المسار | الغرض |
|---|
GET | /models | فهرس النماذج المتاحة لحسابك |
GET | /sessions | سرد المحادثات |
GET | /sessions/{id} | جلسة واحدة وأحدث أحداثها |
PATCH DELETE | /sessions/{id} | إعادة تسمية / حذف |
GET | /sessions/{id}/messages | سجلّ الرسائل الكامل |
GET | /sessions/{id}/artifacts | كل ما أنتجته الجلسة |
POST | /sessions/{id}/branch | تفريع المحادثة عند نقطة |
POST | /sessions/{id}/truncate | اقتطاع المحادثة عند رسالة |
GET POST | /sessions/{id}/versions | سجلّ نسخ المخرجات / الاستعادة |
GET | /sessions/search?q= | بحث نصّي كامل في محادثاتك |
الملفات
| الطريقة | المسار | الغرض |
|---|
POST | /uploads | {filename, content_base64, mime, session_id?} ← {upload_id}. يُحلَّل تلقائياً (OCR، رؤية، تفريغ صوتي). حتى ٢٠٠ ميغابايت للملف |
GET | /uploads/{id} | حالة التحليل والنص المستخرج |
GET | /uploads/{id}/raw | البايتات الأصلية |
POST | /artifacts | إنشاء مُخرَج من محتواك |
GET | /artifacts/{id} | تنزيل ملف مُنتَج |
POST | /export | تحويل Markdown/HTML إلى PDF أو DOCX أو PPTX |
POST | /export-text | تصدير نصّي بسيط |
اربط ملفاً مرفوعاً بتشغيل بتمرير معرّفه في attachments. المقبول: PDF، Office، صور، صوت،
فيديو، CSV/Excel، ZIP (يُفكّ تكرارياً).
قواعد المعرفة (RAG)
| الطريقة | المسار | الغرض |
|---|
POST GET | /kb | إنشاء / سرد قواعد المعرفة |
PATCH DELETE | /kb/{id} | إعادة تسمية / حذف |
GET POST | /kb/{id}/documents | سرد / إضافة مستندات (الاستيعاب غير متزامن) |
POST | /kb/query/stream | استعلام مبثوث (أدناه) |
GET PUT | /kb/{id}/config | ملف الاسترجاع (قانوني / مؤسسي / زمني / عام)، لغة FTS، الميزانيات. PUT يعيد كتابة كل الحقول — أرسل الكائن كاملاً |
GET | /kb/{id}/chunks · /entities · /graph | فحص الفهرس والكيانات المستخرجة والرسم |
GET | /kb/{id}/file/{doc_id} · /image/{image_id} | المستند المصدر / الصورة المستخرجة |
POST GET | /kb/{id}/conversations | محادثات RAG متعدّدة الأدوار |
GET | /kb/{id}/conversations/{cid}/messages | سجلّ المحادثة |
GET POST DELETE | /kb/{id}/connectors … | المزامنة من مصادر خارجية؛ /kb/connectors/catalog يسردها |
POST GET DELETE | /kb/{id}/share | نشر رابط استعلام عام |
GET | /kb/pricing | نموذج التكلفة لكل استعلام |
curl -N -X POST https://ai.syctra.com/api/v1/kb/query/stream \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{
"kb_id": "…", "q": "ما بنود الفسخ بعد ١٢ شهراً؟",
"mode": "full", "cite": true, "enhance": false, "agent": false, "top_k": 20
}'
| الحقل | القيم | الوصف |
|---|
mode | auto · quick · full · deep · graph_local · graph_global | عمق الاسترجاع. auto يختار حسب السؤال |
cite | bool | استشهادات [N] داخل النص ومعرّفات المصادر |
enhance | bool | إعادة صياغة الإجابة بالنموذج |
agent | bool | تفكيك الأسئلة المركّبة قبل الاسترجاع |
doc_id | string | حصر الاسترجاع في مستند واحد |
conversation_id | uuid | متابعة محادثة متعدّدة الأدوار |
الوكلاء المخصّصون
| الطريقة | المسار | الغرض |
|---|
GET | /agent-tools | فهرس القدرات القابلة للتفعيل على وكيل |
GET POST | /agents/custom | سرد / إنشاء |
GET PUT DELETE | /agents/custom/{id} | قراءة / تعديل / حذف |
POST | /agents/custom/persona | استخلاص شخصية من كتابات مرفوعة |
GET | /marketplace · /marketplace/{id} | الوكلاء المنشورون |
POST | /marketplace/{id}/install · /publish · /unpublish | التثبيت / النشر / السحب |
{
"name": "محلّل المناقصات", "emoji": "📑",
"description": "يقرأ ملفات المناقصات وينتج مذكّرة قرار",
"instruction": "أنت محلّل صفقات عمومية…",
"tool_keys": ["web", "deep_research", "documents", "knowledge_base", "database"],
"model": "standard", "visibility": "private",
"examples": ["حلّل هذه المناقصة"], "tags": ["مشتريات"]
}
مفاتيح القدرات: knowledge_base · web · deep_research · agent_team · computer_use ·
algerian_law · documents · slides · charts · images · webpage · code · quiz ·
email · planning · scraping · prospecting · linkedin · meta · obsidian ·
knowledge_graph · scheduling · workspace_files · data_engineering · database · n8n ·
stripe · paypal · notion · github · gitlab · elevenlabs · microsoft · atlassian · slack · s3 · apify · mcp_remote.
شغّله كأي وكيل آخر: POST /chat مع "app_name": "custom_<id>".
المُجدوِل
| الطريقة | المسار | الغرض |
|---|
GET POST | /cron | سرد / إنشاء تشغيل مجدول |
PATCH DELETE | /cron/{id} | إيقاف مؤقّت، تعديل، حذف |
POST | /cron/{id}/run | تشغيل فوري مرّة واحدة |
{ "name": "رصد المنافسين يوم الاثنين", "cron_expr": "0 8 * * 1",
"timezone": "Africa/Algiers", "prompt": "لخّص تحرّكات الأسبوع الماضي…",
"app_name": "main", "delivery_email": "team@acme.com" }
صيغة cron القياسية بخمسة حقول. delivery_email يرسل الإجابة النهائية بالبريد؛ اتركه فارغاً
لتعطيل الإرسال.
Data Lab
| الطريقة | المسار | الغرض |
|---|
GET POST | /data/workspaces | سرد / إنشاء مساحة DuckDB دائمة |
PATCH DELETE | /data/workspaces/{id} | إعادة تسمية / حذف |
POST | /data/workspaces/{id}/ingest | تحميل Excel/CSV — أوراق فوضوية، ترويسات متعدّدة الأسطر، عدّة جداول في الورقة |
GET | /data/workspaces/{id}/tables · /files | فحص المخطّط والمصادر |
POST | /data/workspaces/{id}/query | تنفيذ SQL على المساحة |
DELETE | /data/workspaces/{id}/tables/{table} | حذف جدول |
سرب الوكلاء
| الطريقة | المسار | الغرض |
|---|
GET | /swarm/api/teams · /catalogue · /health | الفرق المتاحة وحالة المحرّك |
POST | /swarm/api/run | بدء تشغيل متعدّد الوكلاء |
GET | /swarm/api/run/{id}/stream | التقدّم عبر SSE |
POST | /swarm/api/run/{id}/cancel | إيقافه |
GET | /swarm/api/dossiers · /{id} · /{id}/file/{name} | الملفّات المنتَجة وموادّها |
POST | /swarm/api/convert · /template/inspect | تحويل المخرجات / فحص قالب عرض |
المستندات والمشاريع
| الطريقة | المسار | الغرض |
|---|
GET | /docspace | شجرة المجلّدات والمستندات |
POST PATCH DELETE | /folders, /folders/{id} | إدارة المجلّدات |
POST PATCH DELETE | /documents, /documents/{id} | إدارة المستندات |
GET | /documents/{id}/content | قراءة المحتوى |
POST | /documents/{id}/attach | ربط مستند بمحادثة |
POST | /docspace/import-zip | استيراد جماعي |
GET POST | /projects, /projects/{id} | مساحات تجمع المحادثات والملفات |
POST GET DELETE | /projects/{id}/members | صلاحيات المشروع |
المشاركة (روابط عامة)
| الطريقة | المسار | الغرض |
|---|
POST GET DELETE | /sessions/{id}/share | نشر محادثة |
GET | /shared/{slug} | عام — قراءة محادثة منشورة |
GET | /shared/{slug}/artifacts/{id} | عام — مُخرَج من محادثة منشورة |
GET POST | /shared/{slug}/comments | عام — سلسلة تعليقات |
POST | /shared/{slug}/clone | نسخ محادثة منشورة إلى حسابك |
POST GET DELETE | /docshare | مشاركة المستندات والمجلّدات |
GET | /shared-doc/{slug} | عام — مستند مشترك |
GET | /shared-kb/{slug} · POST /shared-kb/{slug}/query/stream | عام — رابط قاعدة معرفة، والاستعلامات تُفوتر على المالك |
الرابط العام عنوان غير مُفهرس، لا مصادقة. ما تنشره يقرؤه كل من يملك الرابط — والاستعلامات على
قاعدة مشتركة تُفوتر عليك أنت. ألغِ بالمسار DELETE المقابل.
الأداة المدمجة (Widget)
أنشئ أداة في التكاملات ← Widget، ثم الصق سطراً واحداً في موقعك:
<script src="https://ai.syctra.com/embed.js" data-key="pk_live_…" async></script>
اختيارياً data-position="bottom-left" | "bottom-right". تستدعي الأداة واجهة عامة منفصلة تحت
/embed-api — المفتاح العام ليس مفتاح API ولا يستطيع قراءة حسابك:
| الطريقة | المسار | الغرض |
|---|
GET | /embed-api/config/{public_key} | عام — إعدادات الأداة |
POST | /embed-api/chat | عام — رسالة زائر |
GET | /embed-api/runs/{run_id}/events | عام — بثّ الإجابة |
GET | /embed-api/history/{public_key}/{visitor_id} | عام — سجلّ الزائر |
GET POST PATCH DELETE | /embed-widgets | إدارة المالك (بمصادقة) |
المساران /embed-api/* و/scim/v2/* يُقدَّمان من جذر النطاق، لا تحت /api/v1 —
مثال: https://ai.syctra.com/embed-api/chat.
لا يُربط بالأداة إلا الوكلاء المسموح بهم للاستخدام العام، وحركة الزوّار محدودة لكل أداة، وكل
محادثة تُفوتر على المؤسسة المالكة. قيّد المصادر (origins) المسموحة قبل النشر.
الفرق والمؤسسة والتزويد
| الطريقة | المسار | الغرض |
|---|
GET | /enterprise · /enterprise/analytics · /enterprise/retention | المؤسسة، الاستخدام، سياسة الاحتفاظ |
POST DELETE | /enterprise/teams, /teams/{id} | إدارة الفرق |
POST DELETE | /enterprise/teams/{id}/members… | العضوية |
POST DELETE | /enterprise/teams/{id}/grants | الوكلاء المسموحون لفريق |
POST | /enterprise/teams/{id}/invite · /invites/revoke · /invites/resend | الدعوات |
GET POST | /invite/{token}, /invite/{token}/accept | عام — قبول الدعوة |
GET PUT DELETE | /enterprise/sso | الدخول الموحّد SAML / OIDC |
POST | /enterprise/scim-token | إصدار رمز تزويد SCIM |
GET | /me/caps · /me/teams · POST /me/active-team | صلاحيات المستدعي وفرقه |
GET POST DELETE | /teams, /groups, /share-targets | فرق خفيفة، مجموعات، أهداف مشاركة |
SCIM 2.0 يُقدَّم على https://ai.syctra.com/scim/v2 برمز خاص به (ليس مفتاح API):
GET|POST /Users، GET|PUT|PATCH|DELETE /Users/{id}، GET /Groups.
الحساب والإشعارات والخصوصية
| الطريقة | المسار | الغرض |
|---|
GET PATCH | /auth/me | الملف الشخصي |
POST | /auth/change-password · /auth/logout | بيانات الاعتماد / الخروج |
GET | /balance | رصيد الأرصدة |
GET POST | /notifications, /notifications/read | فيد الإشعارات |
PUT | /me/notify-email · /me/low-balance-pct | تفضيلات الإشعار |
GET POST | /push/vapid-key, /push/subscribe | اشتراكات Web Push |
GET DELETE PUT | /memory, /memory/{id}, /memory/settings | الذاكرة طويلة الأمد: قراءة، حذف، إلغاء الاشتراك |
GET | /account/export | GDPR — تصدير كل ما تملكه |
DELETE | /account | GDPR — حذف الحساب وبياناته |
GET POST | /approvals, /approvals/{id}/decide | الموافقة على إجراء محجوب أو رفضه |
GET PUT | /approval-settings | أي القدرات تتطلّب موافقة بشرية |
أسطح أخرى
| الطريقة | المسار | الغرض |
|---|
GET POST DELETE | /deadlines… | أجندة الآجال القانونية |
POST GET DELETE | /meetings… | تفريغ الاجتماعات ومحاضرها |
POST GET DELETE | /dubbings…, GET /dubbing/languages | مهام دبلجة الفيديو / الصوت |
POST GET DELETE | /email-compose, /email-templates | الرسائل المُنشأة والقوالب |
POST | /email/send | إرسال بريد عبر المنصّة |
GET POST DELETE | /prompts | المُوجّهات المحفوظة |
POST | /feedback · /message-feedback | ملاحظات المنتج وملاحظات كل إجابة |
GET | /healthz · /readyz · /metrics | عام — الحياة والجاهزية ومقاييس Prometheus |
ملاحظات للمُكامِلين
- لا توجد بعد webhooks صادرة. تابع الأعمال الطويلة بإبقاء بثّ SSE مفتوحاً، أو باستطلاع
GET /sessions/{id} — التشغيل يصمد أمام انقطاعك في الحالتين.
- استطلع بأدب. فضّل SSE؛ وإن اضطررت للاستطلاع فاستخدم
cursor الذي تملكه.
- احفظ المؤشّر. حفظ آخر
seq عالجته يجعل تكاملك آمناً أمام الأعطال.
- ثبّت الوكيل.
app_name يحدّد السلوك والتكلفة والأدوات المتاحة — عيّنه صراحة بدل الاعتماد
على الافتراضي main.
- عالج
402 و429 أولاً. هما الخطآن اللذان يلقاهما أي تكامل سليم في الإنتاج؛ ما عداهما
يدلّ غالباً على خلل في الحمولة.