مصفوفة واجهة API والمسارات

الأسطح الأساسية لتطبيق FastAPI (kazma_ui). المصادقة رفض افتراضي لمسارات /api/* ما لم تُذكر مفتوحة. خطر HITL ينطبق على تنفيذ الأدوات، وليس على كل مسار HTTP.

مفتوحة دائمًا (الصحة)

الطريقة	المسار	المصادقة	الوصف
GET	/health	مفتوح	حيوية
GET	/health/live	مفتوح	العملية حية
GET	/health/ready	مفتوح	الجاهزية (اختبار DB عند ضبطه)

المصادقة والحساب

الطريقة	المسار	نطاق المصادقة	الوصف
GET/POST	/login	صفحة عامة	تسجيل دخول متعدد الأوضاع (مستخدم / سر / OIDC)
POST	/api/auth/*	متفاوت	دخول، خروج، جلسة (انظر auth.py، saas_api.py)
GET	/api/saas/*	مشرف / مشغِّل	المستأجرون، ومستخدمو المنصة (RBAC)

الدردشة والجلسات

الطريقة	المسار	المصادقة	HITL	الوصف
POST	/api/chat/stream	جلسة/سر	مقاطعة الرسم البياني عند أدوات الخطورة	تدفق دردشة SSE
POST	/api/approve/{thread_id}	جلسة	يستأنف HITL الرسم البياني	الموافقة على أداة خطرة
*	عمليات CRUD للجلسات تحت /api/sessions*	جلسة	—	قائمة الخيوط / السجل (session_manager)

IDE

الطريقة	المسار	المصادقة	HITL	الوصف
*	/api/ide/*	جلسة	عبر سجل الأدوات	ملفات، وapply_patch، وبحث قاعدة الشيفرة، وLSP (GET/POST /lsp)، وتشغيل، وgit، وإرسال السرب (ide_api.py)
GET	/ide	جلسة	—	صفحة IDE

السرب / مركز القيادة

الطريقة	المسار	المصادقة	الوصف
*	/api/swarm/*	جلسة (GET) / مشرف (كل ما عداه)	العمّال، والإرسال، والمهام، والمقاييس. جدول واحد، kazma_ui/swarm_panel/route_roles.py؛ ويُرفض بـ 409 swarm_single_operator على تثبيت فيه مستخدمو منصة
POST	/api/swarm/workers/{name}/circuit-breaker/reset	مشرف	إغلاق قاطع دائرة عامل الآن (زر Reset على بطاقة العامل، يظهر والقاطع مفتوح أو نصف مفتوح)
GET	/api/swarm/approvals/{id}	جلسة	طلب موافقة واحد من ناقل السرب، للوحة الموافقة في صفحة السرب (الرابط الموجود على كل بطاقة موافقة في الدردشة): الأداة، وحالتها، والاستدعاء كاملًا كما يحفظه سجل البوابة، والبصمة (hash) التي تعرضها البطاقة، ومن قرّر. بوابة موافقة الدردشة لا توجد هنا
POST	/api/swarm/approvals/{id}/decide	مشرف	{"decision": "approve" | "deny"}: يجيب عن الطلب من الويب، وهو القرار المشترك نفسه الذي تتخذه أزرار الدردشة (platform: web). ‏409 not_pending بعد أن يُجاب عنه أو ينتهي
GET	/api/swarm/tasks/export	جلسة	سجل المهام بصيغة JSON، أو CSV مع ?format=csv (أحدث 1,000 مهمة؛ بمرشحات type وstatus وq مثل قائمة السجل). زر تصدير CSV في سجل المهام
GET	/api/swarm/tasks/{id}/stream	جلسة	تدفق المهمة الحي (swarm_sse): أحداث المهمة حتى الآن، ثم الأحداث الحية حتى تنتهي. وينتهي تدفق المهمة المكتملة دائمًا بـ task_completed ونتيجة المهمة، تُبنى من المهمة المخزّنة حين لا يحتفظ الخادم بأحداثها (بعد إعادة التشغيل).
GET	/swarm	جلسة	صفحة لوحة السرب
*	/api/replay/*	جلسة	السفر عبر الزمن: خيوط، ولقطات، واستعادة، وتفريع، ومقارنة، ومسح (replay_routes.py)
GET	/replay	جلسة	صفحة لوحة السفر عبر الزمن
*	/api/research/*	جلسة	البحث: قائمة، وتفصيل، ومقارنة، وتصدير، وأرشفة، وإلغاء أرشفة (research_panel/routes.py). التقرير الذي يسمّيه الطلب مسارٌ داخل مجلد research/reports، ولا يُقرأ غيره
POST	/api/research/sessions	جلسة	بدء جلسة بحث معمّق (خط أنابيب خلفي)
GET	/api/research/sessions	جلسة	سرد جلسات البحث الدائمة
GET	/api/research/sessions/{id}	جلسة	حالة الجلسة / السجل / مسار التقرير
GET	/api/research/sessions/{id}/stream	جلسة	تقدم SSE (snapshot / progress / done)
GET	/api/research/eval	جلسة	معيار هيكلي لـ?path=research/reports/… أو ?session_id=
POST	/api/memory/v2/eval/golden	جلسة	تشغيل حالات استدعاء الذاكرة الذهبية (نسبة النجاح)
GET	/research	جلسة	صفحة لوحة البحث (نموذج بدء + تقدم حي)

الذاكرة / RAG

الطريقة	المسار	المصادقة	الوصف
GET	/api/system/status	جلسة	لوحة صحة الذاكرة + تحقيقات المُضمِّن/الطبقة (build_memory_health)
GET	/api/memory/graph	جلسة	رسم بياني للخصائص بصيغة JSON (nodes/edges)؛ مرشح ?q= اختياري
GET	/api/memory/graph/stats	جلسة	أعداد العقد/الحواف + مسار الخلفية
GET	/api/memory/graph/search	جلسة	بحث FTS عبر عقد الرسم البياني (?q=&limit=)
POST	/api/memory/graph/clear	جلسة	إبطال ثنائي الزمن لمعتقدات V2 النشطة لمستأجر واحد (?tenant= الافتراضي default؛ لا يوجد وضع لكل المستأجرين). يضع شواهد قبور على مرآة PG، ويحذف حواف Neo4j، ويكتب صف تدقيق graph_clear. الواجهة تؤكد.
*	/api/system/memory/*	جلسة	نسخ احتياطي / استعادة / صيانة لمخازن الذاكرة

محرك V2 المعرفي (/api/memory/v2/*)

مفعَّل عندما تكون memory.v2.use_new_stack صحيحة. كل المسارات تعيد JSON مُشكَّلًا عند الخطأ (لا 500 مكشوف أبدًا)؛ المعاملات غير الرقمية تعطي FastAPI 422.

الطريقة	المسار	المصادقة	الوصف
GET	/api/memory/v2/health	جلسة	لقطة صحة V2 — أعداد المعتقدات النشطة/المُستبدَلة/المؤرشفة، وإحصاءات الحلقات/الكيانات/الإجراءات، وعمق الطابور. تُغذّي شبكة مؤشرات لوحة القيادة (pollV2Health، إيقاع 5s).
GET	/api/memory/v2/beliefs	جلسة	قائمة المعتقدات النشطة. مرشح FTS عبر ?q=، و?limit= (الافتراضي 50، محدود 1–200).
GET	/api/memory/v2/beliefs/{id}	جلسة	تفصيل المعتقد + سلسلة الاستبدال.
POST	/api/memory/v2/beliefs/{id}/invalidate	جلسة	إبطال ناعم لمعتقد واحد (+ حذف حافة Neo4j بأفضل جهد).
POST	/api/memory/v2/beliefs/invalidate-batch	جلسة	إبطال ناعم لعدة معتقدات ({ "ids": [...] }).
PATCH	/api/memory/v2/beliefs/{id}	جلسة	تعديل المشغِّل لثلاثية نشطة: اختياري subject، وpredicate، وobject، وpredicate_type. يضبط extraction_method=user_explicit؛ يمسح التضمين عند تغير المفعول.
GET	/api/memory/v2/graph	جلسة	رسم المعتقدات {nodes, links, stats, groups} للوحة الرسم. ثنائي الزمن + معاملات ترشيح: ?at=<unix_ts> (تمرير نقطة زمنية؛ المعتقدات المُستبدَلة موسومة superseded=true)، و?type= (functional/set/state لـpredicate_type)، و?entity_type= (person/tool/concept/…)، و?limit= (الافتراضي 200)، و?source=neo4j (تحقق اختياري). stats.total_links مقابل stats.links هو فارق التقطيع الظاهر على لافتة الاقتطاع. الثوابت: معرفات عقد فريدة؛ لا عقدة حقيقة افتراضية عندما يساوي نص المفعول معرف كيان؛ لا روابط معلقة؛ عقدة المحور id=user مع name للعرض من entities.user (أغلفة الشخص الذاتية مطوية على المحور)؛ موضوعات مفعول الحمولة تحمل مرساة محور related_to.
GET	/api/memory/v2/entities	جلسة	قائمة الكيانات لعمليات /memory. الأعلام: empty، وisolated، وprotected، و**core** (محمي دائمًا، لا يمكن إلغاء حمايته)، و**is_self، وgraph_id** (الأغلفة الذاتية → "user"). الاستعلام: ?q=، و?empty_only=، و?isolated_only=، و?limit=.
POST	/api/memory/v2/entities/{id}/protect	جلسة	{ "protected": true|false }: الكيان المحمي لا يمكن حذفه أو دمجه بعيدًا (Protect / Unprotect في صفحة الذاكرة). الكيانات الجوهرية ترفض false.
POST	/api/memory/v2/entities/{id}/rename	جلسة	إعادة تسمية للعرض فقط ({ "name": "…" }). المعرف ثابت؛ الأسماء المستعارة محفوظة. أغلفة User للذات/الشخص ترفع أيضًا محور entities.user. يعيد hub_synced، وgraph_id.
POST	/api/memory/v2/entities/merge	جلسة	دمج المصدر في الهدف (إعادة توصيل المعتقدات، واتحاد الأسماء المستعارة).
POST	/api/memory/v2/entities/link	جلسة	إنشاء حافة معتقد (subject، وpredicate، وobject).
DELETE	/api/memory/v2/entities/{id}	جلسة	حذف غلاف الكيان (محجوب للمعرفات المحمية: user، وassistant، …). ينسخ صفوف entity_merges المطابقة إلى entity_merges_archive قبل إسقاط صفوف السجل الحية (FK).
GET	/api/memory/v2/admin/summary	جلسة	أعداد لرقاقات العمليات (المعتقدات الحية/المبطلة، والكيانات الفارغة/المعزولة).
GET/POST	/api/memory/v2/hygiene/*	جلسة	معاينة + تشغيل تطهير الفارغة / إبطال شبه المكررة / الأرشفة.
GET/POST	/api/memory/v2/entity-merges*	جلسة	قائمة الدمج في الحجر الصحي + الموافقة/الرفض.
GET/POST/DELETE	/api/memory/v2/graph/groups*	جلسة	تجميعات للعرض فقط (سرد/إنشاء/حذف/نقل/تدرج). لا تعدّل المعتقدات أبدًا. ويرفض الإنشاء عقدةً لها أمٌّ أصلًا (ويسمّي الجوابُ مسار النقل)؛ وجمّع تحت← على عقدة مُجمّعة ينقلها، والمستوى… يحدد مستوى عقدة مُجمّعة. استطلاع اللوحة يستخدم groups على GET /graph؛ وفض التجميع هو DELETE …/groups/{id}.
GET	/api/memory/v2/graph/export	جلسة	تصدير JSON أو GraphML عند الطلب (?format=json|graphml).
POST	/api/memory/v2/probe	جلسة	تشغيل جاف للاستدعاء (رقاقات الشرح).
POST	/api/memory/v2/federated-search	جلسة	بحث موسوم في الذاكرة + قاعدة المعرفة.
POST	/api/memory/v2/eval/golden	جلسة	حزمة الاستدعاء الذهبية.

الصفحة: GET /memory (HTML إداري). الدليل: الذاكرة وRAG · أفضل مسار للذاكرة.

الإعدادات والضبط

الطريقة	المسار	المصادقة	الوصف
*	/api/settings*، تصدير الإعدادات	مشرف/مشغِّل	واجهة إعدادات مدعومة بـConfigStore
PUT	/api/settings/single، /api/settings	مشرف	حفظ إعداد واحد، أو عدة إعدادات في معاملة واحدة. يطبّق الاثنان فحوص القيم نفسها (settings_validation): المنطقة الزمنية التي لا يستطيع المجدول حلّها، ومدة الاحتفاظ التي لا يستطيع التنظيف قراءتها، وحدث حالة الخادم الذي لا يرسله Kazma، تُرَدّ كلها بـ 400 ولا يُكتب شيء.
GET	/api/settings/system/backup	مشرف	النسخة الاحتياطية للإعدادات (YAML): كل إعداد مخزَّن، والمفاتيح كإشارات إلى الخزنة، دون بيانات اعتماد ولا شيء من حالة Kazma الخاصة. الإعداد.
GET	/api/settings/export?format=yaml|json	مشرف	النسخة الاحتياطية نفسها بصيغة YAML أو JSON.
POST	/api/settings/system/restore?dry_run=&sections=&expect=	مشرف	المحتوى: نسخة احتياطية (YAML أو JSON، 10 ميغابايت على الأكثر). يعيد dry_run=true الخطة (changed وkeys_restored وkeys_to_reenter وrefused وkept وdigest) ولا يكتب شيئًا. ومن دونه تُكتب الخطة؛ ومع expect (قيمة digest من المعاينة) تُرفض الخطة التي تغيّرت منذئذ بـ 409 مع الخطة كما هي الآن. ‏400 لملف ليس نسخة احتياطية، و413 لما يتجاوز 10 ميغابايت، و503 حين تكون الإعدادات محفوظة في الذاكرة (قاعدة البيانات غائبة). ويستعيد sections=agent,providers تلك الأقسام فقط.
GET / POST	/api/settings/system/restore/undo	مشرف	‏GET: ما سيعيده التراجع عن آخر استعادة (available). ‏POST (‏expect= قيمة digest من GET): يعيده؛ ويبقى الإعداد الذي تغيّر مجددًا بعدها والمفتاح الذي أعادته الاستعادة. ‏409 حين لا يوجد ما يُتراجع عنه.
GET/PUT	/api/settings/agent/nonstop	جلسة / مشرف	إعدادات المراقب/تجاوز الفشل/السجل لعدم التوقف والشفاء الذاتي
*	مساحات العمل /api/workspaces*	جلسة	عمليات CRUD لـWorkspaceStore
GET/PUT	/api/workspace/extra-roots	جلسة	مجلدات خارج مساحة العمل يجوز للوكيل استخدامها دون سؤال (صفحة مساحة العمل). يستبدل PUT القائمة؛ يجب أن يكون الجذر الجديد مسارًا كاملًا لمجلد موجود، لا قرصًا كاملًا ولا مجلدًا يحوي ملفات كاظمه نفسها (ويقول 400 السبب). القراءة الفاشلة تعيد 500، لا قائمة فارغة أبدًا.
GET	/api/notifications/turn-complete	جلسة	مفتاح «الإشعار عند انتهاء مهمة»، وهو القارئ نفسه الذي يستخدمه مرسل Web Push أيضًا

المستندات / ذكاء المستندات

مركَّبة من documents_api.py عند /api/documents/*. نقل نحيف فوق DocumentIngestionService المشترك (لا مسار محلِّل موازٍ). المستأجر والفاعل ومساحة العمل تأتي من الطلب، لا من جسمه أبدًا: المستأجر من وسيط المستأجر (tenant middleware)، والفاعل من اسم الكيان المسجِّل دخوله (operator للسر المشترك المُرسَل في ترويسة، وlocal لطلب بلا بيانات اعتماد)، ومساحة العمل من صف مساحة العمل النشطة. لا يزوّد العملاء أبدًا مسارات خادم موثوقة.

يعود المستند إلى الفاعل الذي استوعبه؛ وكل قراءة، وقراءة مهمة، وإجراء يفحص ACL المستند. والمستند أو المهمة التي لا يستطيع المستدعي قراءتها يُجاب عنها تمامًا كما يُجاب عن غير الموجود (404). على تثبيت بمشغِّل واحد تعمل هذه المسارات وأوامر الدردشة وأدوات الوكيل كلها بوصفها مشغِّل التثبيت (documents.principal، منذ 2026-10-13)، فيرى كلٌّ منها المستندات التي استوعبها الآخرون؛ ومع مستخدمي منصة (وضع تعدد المستخدمين) تعمل هذه المسارات بوصفها كل مستخدم، وترفض الدردشة والوكيل.

الدليل: ذكاء المستندات · العمليات: معالجة المستندات · الأمان: أمان المستندات.

الاستيعاب، والمكتبة، والمهام

الطريقة	المسار	المصادقة	الوصف
POST	/api/documents	جلسة	رفع متدفق. الجسم: بايتات الملف؛ واسم الملف في X-Document-Filename (مُرمَّز URL) أو ?filename=؛ واختياريًا X-Idempotency-Key و?force_ocr=1. الحجم المُعلَن، وتفعيل الكتابة، والحد الأدنى للتخزين، والطابور، وحدود المستأجر، ونافذة معدّله، يُجاب عنها كلها قبل قراءة الجسم (انظر الأجوبة أدناه؛ وحصة بايتات المستأجر تُفحص أثناء تخزين الملف)؛ ويُستقبل على الأكثر documents.capacity.max_concurrent_uploads (الافتراضي 4) رفعًا في آن واحد لكل عملية (503 uploads_busy). ويُخزَّن الجسم مؤقتًا تحت جذر التخزين ويُقطع عند documents.intake.max_bytes أو عند طوله المُعلَن (413).
POST	/api/documents/import	جلسة	استيعاب ملف من مساحة العمل النشطة: {"path": …} (نسبةً إلى مساحة العمل، أو مطلقًا داخلها)؛ وإلا 400 path_outside_workspace
POST	/api/documents/generate	جلسة	توليد + استيعاب دائم: target_format، وpayload (كائن لا يتجاوز 1 MiB مُسلسَلًا، و413 فوق ذلك؛ والتداخل الأعمق من 32 يعطي 400)، واختياريًا output_name وtitle
GET	/api/documents	جلسة	المستندات التي يستطيع المستدعي قراءتها، كلٌّ منها مع حالة أحدث مهمة له
GET	/api/documents/health	جلسة	جاهزية المحلل/OCR/العارض/مُعدِّل PDF + حالة العامل (تشخيص للقراءة فقط). ومع KAZMA_DOCUMENT_WORKER_ISOLATION=container تكون المحركات هي التي تُبلغ عنها صورة العامل
POST	/api/documents/merge	جلسة	دمج ملفات PDF لـ document_ids (اثنين على الأقل) في قطعة جديدة
GET	/api/documents/{document_id}	جلسة	التفصيل (الإصدارات + المهام + القطع)
GET	/api/documents/{document_id}/versions	جلسة	قائمة الإصدارات
GET	/api/documents/{document_id}/content	جلسة	المحتوى المُطبَّع، مُسيَّجًا كبيانات غير موثوقة: ?page= أو ?page_start=&page_end=، وoffset، وmax_chars (الافتراضي 20,000، و200,000 على الأكثر)، مع متابعة (continuation). ‏409 not_ready قبل انتهاء المعالجة
GET	/api/documents/{document_id}/artifacts	جلسة	القطع المشتقة لمستند
GET	/api/documents/artifacts/{artifact_id}/download	جلسة	تنزيل قطعة عبر معرف معتم (404 حين لا يستطيع المستدعي قراءتها)
POST	/api/documents/{document_id}/convert	جلسة	تحويل الإصدار الحالي: target_format، واختياريًا output_name → قطعة جديدة
GET	/api/documents/{document_id}/pdf-info	جلسة	تقرير PDF هيكلي
POST	/api/documents/{document_id}/split	جلسة	تقسيم نطاق صفحات: start_page، وend_page، واختياريًا output_name
POST	/api/documents/{document_id}/fill-form	جلسة	ملء حقول AcroForm: fields (كائن)، واختياريًا output_name
POST	/api/documents/{document_id}/redact	جلسة	حجب terms (قائمة) حجبًا فيزيائيًا → قطعة جديدة؛ والأصل لا يتغيّر. لا حوار تأكيد على API (الصفحة تسأل أولًا)
POST	/api/documents/{document_id}/index	جلسة	نشر الإصدار الحالي في المكتبة المعرفية library_id
POST	/api/documents/{document_id}/unindex	جلسة	إزالته من المكتبة library_id
POST	/api/documents/search	جلسة	البحث في مكتبة: library_id، وquery، وtop_k (الافتراضي 5، من 1 إلى 50)؛ وتعود النتائج داخل سياج بيانات غير موثوقة
GET	/api/documents/jobs/{job_id}	جلسة	حالة المهمة. ‏404 Job not found لمهمة غير معروفة ولمهمة لا يستطيع المستدعي قراءة مستندها، بالشكل نفسه تمامًا
GET	/api/documents/jobs/{job_id}/events	جلسة	سجل أحداث المهمة بالإلحاق فقط (قاعدة 404 نفسها)
POST	/api/documents/jobs/{job_id}/cancel	جلسة	إلغاء تعاوني (قاعدة 404 نفسها؛ و409 لمهمة لم يعد إلغاؤها ممكنًا)
POST	/api/documents/jobs/{job_id}/retry	جلسة	إعادة تشغيل مهمة dead_letter أو rejected بوصفها مهمة جديدة (409 لأي حالة أخرى). تحتاج إذن كتابة على المستند، وتمرّ بالقبول نفسه الذي يمرّ به الرفع (429/503/507)
POST	/api/documents/{document_id}/delete	جلسة	شاهد قبر: يغادر المستند كل مكتبة معرفية أولًا (والمكتبة التي لا يستطيع مغادرتها توقف الحذف، 500 document_unindex_failed، كي تستطيع إعادة المحاولة إكماله)، ثم تُؤرشف بياناته الوصفية؛ ويستعيد جمع المهملات البايتات لاحقًا. جسم اختياري {"reason": …}
DELETE	/api/documents/{document_id}	جلسة	شاهد القبر نفسه الذي يضعه POST …/delete (تنفيذ واحد)؛ والسبب يُمرَّر في ?reason=

أجوبة تشترك فيها هذه المسارات. المسارات ذات جسم JSON (import، وgenerate، وmerge، وconvert، وsplit، وfill-form، وredact، وindex، وunindex، وsearch، والجسم الاختياري لـ POST /{id}/delete) تقرأ 2 MiB على الأكثر: الطول المُعلَن الذي يتجاوزها يُرفض قبل قراءة بايت واحد، وغير المُعلَن يُقطع (413 request_too_large)؛ وJSON المشوَّه، أو الجسم الذي ليس كائنًا، أو التداخل العميق جدًا، يعطي 422 invalid_json. وسياسة المستندات الحية التي لا يمكن قراءتها أو التي تحمل قيمة محفوظة غير صالحة ترفض الاستدعاء بـ 503 وRetry-After: 30 (document_policy_unavailable). حالة واحدة لكل رمز خطأ على كل مسار (documents_api._STATUS_BY_CODE، منذ 2026-10-13؛ كانت مساعدات المسارات تحتفظ بثلاثة جداول متعارضة): الرفض الذي تسببه حالة الخادم هو 503 مع Retry-After: 30 أينما حدث — الكتابة الدائمة معطَّلة (document_platform_disabled: القراءات ومعلومات PDF والإلغاء تبقى تعمل)، وماسح برمجيات خبيثة مطلوب لا يستطيع العمل (malware_scanner_unavailable، يجيب عنه الرفع قبل قراءة جسمه)، ولا ملف تعريف عامل مسموح به (worker_isolation_*). والرمز الذي لا يسمّيه الجدول يحتفظ بالقيمة الافتراضية لمساره: 400 للاستيعاب ودورة الحياة، و422 لمسارات الإجراءات. وتحمل رفضات الرفع والاستيراد وإعادة المحاولة code؛ وتحمل رفضات 429 و503 و507 أيضًا reason وترويسة Retry-After:

الحالة	الرمز	متى
413	intake_too_large، quota_exceeded	تجاوز documents.intake.max_bytes (المُعلَن أو المُستلَم)، أو تجاوز حصة بايتات المستأجر
507	storage_full	المساحة الحرة ناقص الملف الوارد ستنزل تحت documents.capacity.storage_free_floor_bytes
503	queue_full، capacity_unavailable، uploads_busy	الطابور الدائم عند documents.capacity.max_queued_jobs؛ أو تعذّر إجراء قياس سعة (التخزين، أو الطابور، أو حمل المستأجر، أو مخزن القبول)؛ أو رفوع كثيرة جدًا قيد الاستقبال
429	tenant_queue_full، tenant_active_full، rate_limited	حدود المستأجر للمهام في الطابور/النشطة، أو نافذة الملفات/البايتات في الدقيقة الخاصة به
409	idempotency_conflict، intake_in_progress، intake_taken_over	المفتاح استُخدم لطلب آخر أو من فاعل آخر؛ أو المفتاح نفسه ما يزال قيد الاستقبال؛ أو استغرق الرفع وقتًا طويلًا حتى انقضى عقد إيجاره وتراجعت عنه عملية أخرى (لم يُحفظ شيء: أرسله مرة أخرى)

حين يكون سرٌّ مضبوطًا، تُحتسب أيضًا مسارات الرفع وimport وgenerate وmerge وconvert وsplit وfill-form وredact وindex وsearch ضمن دلو حد معدل HTTP documents، المحسوب لكل كيان (429 مع Retry-After): 10 طلبات في الدقيقة، ويُسمح للبحث بما يصل إلى 30 في النافذة نفسها؛ والقيمة المحفوظة api.rate_limit.documents_per_minute تحل محل الاثنين.

العمليات (/api/documents/ops/*)

الطريقة	المسار	المصادقة	الوصف
GET	/api/documents/ops/metrics	جلسة	لقطة مقاييس خالية من المحتوى
GET	/api/documents/ops/capacity	جلسة	لقطة الضغط العكسي + degraded_reasons
GET	/api/documents/ops/readiness	جلسة	للقراءة فقط: خلفيات التخزين وصدق تعدد النسخ (jobs_multi_replica، وmetadata_multi_replica؛ وخلفية SQLite المختارة عمدًا ليست متدهورة)، وpolicy (المضبوط مقابل الفعلي، وrestart_required)، وmalware، وworker_isolation (hostile_document_profile، وimage_code_matches)، وstranded_intake_reservations، وrollout، وaccepting_durable_writes. وتكون status بقيمة degraded حين تتراجع خلفية مضبوطة أو حين تسمّي degraded_reasons مشكلة (عزل العامل غير متاح، أو حجوزات استيعاب عالقة، أو صورة عامل قديمة، أو فحص البرمجيات الخبيثة يحجب الاستيعاب)، وبقيمة disabled ما دامت الكتابة الدائمة معطَّلة
GET	/api/documents/ops/retention	جلسة	عرض حي لسياسة الاحتجاز/GC
GET	/api/documents/ops/audit	مشرف	تدقيق تشغيلي للمستأجر مرقّم بمفتاح الصفحة (?document_id=&event_type=&limit=&before_id=). للمشرف فقط: يسمّي السجل مستندات وفاعلين قد لا يستطيع المستدعي قراءتهم
POST	/api/documents/ops/maintenance/dry-run	مشرف	تقرير تشغيل جاف لـGC
POST	/api/documents/ops/maintenance/run	مشرف	تشغيل GC (الصفحة تُجري دائمًا تشغيلًا جافًا وتؤكد أولًا؛ والمسار لا يشترط ذلك)

صفحة HTML: GET /documents (جلسة). يقرأ تبويب المستندات في TUI ‏GET /api/documents وGET /api/documents/{document_id}/content من الخادم العامل.

البريد الإلكتروني (email_api.py)

الطريقة	المسار	المصادقة	الوصف
GET	/api/email/status	جلسة	المزوّد النشط، وأوضاع المصادقة، وملخص الإعدادات الجاهزة
GET	/api/email/accounts	جلسة	كل حساب بريد: source بقيم main / settings / env، والاسم، والنوع، والعنوان، وauth (oauth / password / incomplete)، وcalendar، وremovable
POST	/api/email/accounts	جلسة	إضافة حساب آخر يسجّل الدخول بكلمة مرور (alias، وtype، وaddress، وpassword، والمضيفون)؛ يُجرَّب تسجيل الدخول أولًا والفاشل يُرفض (400)
POST	/api/email/accounts/{alias}/remove	جلسة	نسيان حساب أُضيف في الإعدادات (رموزه وكلمة مروره)
GET	/api/email/presets	جلسة	الإعدادات الجاهزة لمضيفي Gmail/Microsoft IMAP/POP
POST	/api/email/protocol/connect	جلسة	حفظ IMAP/POP لـgmail|microsoft|generic
POST	/api/email/protocol/disconnect	جلسة	مسح البروتوكول + رموز OAuth للمزوّد
POST	/api/email/gmail/connect	جلسة	كلمة مرور تطبيق Gmail → IMAP
POST	/api/email/gmail/disconnect	جلسة	مسح بيانات اعتماد Gmail
POST	/api/email/oauth/gmail/client	جلسة	حفظ معرف/سر عميل Google OAuth
GET	/api/email/oauth/gmail/start · start.json	جلسة	إعادة توجيه OAuth في المتصفح / JSON؛ ?account=<name> يسجّل الدخول بحساب آخر تحت ذلك الاسم
GET	/api/email/oauth/gmail/callback	مفتوح (OAuth)	تبادل الرموز؛ إعادة توجيه إلى الإعدادات
POST	/api/email/oauth/microsoft/client	جلسة	حفظ معرف/سر تطبيق Azure
GET	/api/email/oauth/microsoft/start · start.json	جلسة	OAuth في المتصفح؛ ?account=<name> لحساب آخر
GET	/api/email/oauth/microsoft/callback	مفتوح (OAuth)	تبادل الرموز
POST	/api/email/oauth/microsoft/device/start · …/poll	جلسة	تراجع رمز الجهاز؛ الجسم {"account": "<name>"} لحساب آخر
POST	/api/email/oauth/microsoft/disconnect	جلسة	مسح بريد Microsoft: الرموز، وعنوان تسجيل الدخول ونطاقاته (تقويم Outlook يحتفظ بمفتاحه الخاص)
GET	/api/calendar/status	جلسة	حالة كل تقويم وعنوانه، والمزوّد النشط
GET	/api/calendar/oauth/google/start · start.json	جلسة	تسجيل دخول Google Calendar (رد النداء: خاص Gmail)
GET	/api/calendar/oauth/microsoft/start.json	جلسة	تسجيل دخول تقويم Outlook للتقويم وحده (رد النداء: خاص Microsoft، purpose=calendar)؛ يُترك البريد كما هو
POST	/api/calendar/oauth/microsoft/device/start	جلسة	الشيء نفسه عبر رمز الجهاز (الاستقصاء بـ/api/email/oauth/microsoft/device/poll)
POST	/api/calendar/oauth/google/disconnect · …/microsoft/disconnect	جلسة	تعطيل ذلك التقويم حتى يُعاد توصيله من البطاقة؛ البريد يبقى متصلًا

عمليات بريد الوكيل تستخدم الأدوات (email_list, …)، وليس مسارات HTTP هذه. الدليل: دمج البريد الإلكتروني.

ناشر X

الطريقة	المسار	المصادقة	الوصف
GET	/x	جلسة	صفحة X Studio (المحرِّر + مخطِّط X فقط).
GET	/api/x/status	جلسة	مُضبوط؟، المعرِّف، الحدود. لا يعيد الأسرار أبدًا.
POST	/api/x/preview	جلسة	تشغيل جاف لسياسة ToU (evaluate_post). لا شبكة، لا سجل.
GET	/api/x/drafts	جلسة	عناصر save_proposal المسطَّحة لصندوق Studio.
GET	/api/x/audit	جلسة	صفوف x_audit.db الحديثة (?action=&limit=).
POST	/api/x/post	جلسة + CSRF	نشر فوري (publish_x_post). نقرة المشغِّل هي الموافقة. اختياري reply_to_id، وproposal_id (النص المخزَّن يتفوق).
POST	/api/x/delete	جلسة + CSRF	حذف تغريدة حية (delete_x_post). نقرة المشغِّل هي الموافقة.
POST	/api/x/credentials	جلسة + CSRF	حفظ مفاتيح OAuth 1.0a الأربعة (في الخزنة) + المعرِّف + الحدود.
POST	/api/x/test	جلسة + CSRF	GET /2/users/me بالمفاتيح المخزَّنة.
POST	/api/x/disconnect	جلسة + CSRF	حذف المفاتيح، وتعطيل النشر.
GET	/api/x/reply	جلسة	إعدادات الرد التلقائي + حالة مستطلع الإشارات الحي.
POST	/api/x/reply	جلسة + CSRF	حفظ إعدادات الرد التلقائي؛ يبدأ/يوقف مستطلع الإشارات.
POST	/api/x/reply/preview	جلسة + CSRF	تشغيل جاف لمسودة. لا شيء يُنشر أو يُسجَّل.
GET	/api/x/reply/conversations	جلسة	سجل الاستدعاء (الأصل + الإشارة + المسودة/السبب).
POST	/api/x/reply/poll	جلسة + CSRF	جلب الإشارات من X الآن (يتجاهل المؤشر العالق).
POST	/api/x/reply/approve	جلسة + CSRF	نشر مسودة محتجزة (أو فشل سلكي).
POST	/api/x/reply/deny	جلسة + CSRF	ركن مسودة محتجزة.
POST	/api/x/reply/retry	جلسة + CSRF	إعادة تشغيل استدعاء متخطى/فاشل/قيد الصياغة.
POST	/api/x/reply/delete	جلسة + CSRF	حذف الرد المنشور على X (إن وُجد) وإسقاط صف السجل.

تغريدات الدردشة ما تزال تمر عبر x_post (HITL دائمًا + proposal_id). الدليل: ناشر X. الإشارات: الرد التلقائي على X.

المجدول (cron + X)

الطريقة	المسار	المصادقة	الوصف
GET	/scheduled	جلسة	صفحة الساعات المختلطة (مهام cron و منشورات X).
GET	/api/scheduled/tasks	جلسة	كل مهام cron (القادمة والمنتهية، كلٌّ منها مع فئة حالتها وactions التي يسمح بها الخادم) وعمليات مخزن نشر X. التعليمات (prompts) ملخصات للعرض؛ والعنوان تسمية destination.
GET	/api/scheduled/cron/{job_id}	جلسة	مهمة واحدة مع تعليمتها كاملة وversion، لحوار التعديل.
POST	/api/scheduled/cron	جلسة + CSRF	حجز مهمة: timing، وprompt، واختياريًا kind (reminder/task) وcapabilities (read/read_write). تنطبق الحدود القصوى، وحدود الطول، ودلو المعدل scheduled.
PUT	/api/scheduled/cron/{job_id}	جلسة + CSRF	تعديل timing و/أو prompt مع expected_version الذي قرأته الاستمارة: 200 rescheduled، و202 edit_pending (أثناء إطلاق)، و409 conflict / not_editable.
DELETE	/api/scheduled/cron/{job_id}	جلسة + CSRF	إلغاء: 200 cancelled، و202 cancel_pending (أثناء إطلاق)، و409 لمهمة منتهية.
POST	/api/scheduled/cron/{job_id}/restore	جلسة + CSRF	شغّل مرة أخرى: حجز مهمة منتهية من جديد عند timing.
POST	/api/scheduled/x	جلسة + CSRF	حجز منشور X (book_x_post). اختياري reply_to_id، وproposal_id. يجيب بالوقت والحالة المخزَّنين.

تُعاد جدولة منشورات X في هذه الصفحة وتُلغى عبر POST /api/x/queue/{operation_id}/reschedule و.../cancel (مع المراجعة التي قرأتها الصفحة)، وهي المسارات التي يستخدمها X Studio. وكل مسار مُعدِّل يفحص أن الطلب من الأصل نفسه (kazma_ui/same_origin.py). وعلى تثبيت فيه مستخدمو منصة يجيب كل مسار بـ 409 scheduled_single_operator. السلوك: التذكيرات والمهام المجدولة.

رابط كل الساعات في X Studio هو هذه الصفحة. مخطِّط Studio نفسه لـX فقط.

البوابات والمنصات

الطريقة	المسار	المصادقة	الوصف
خطافات الويب	ردود نداء Telegram/Discord/Slack	أسرار المحوِّل	رسائل واردة + أزرار HITL
*	/api/gateway/*	جلسة	حالة/تحكم البوابة من CLI

أخرى

الطريقة	المسار	المصادقة	الوصف
WS	مسارات الصوت	جلسة	routes_voice_ws.py
*	مسارات الفوضى	KAZMA_CHAOS_ENABLED	للتطوير فقط
Static	/, /chat, /settings, /x, /scheduled, …	كوكي/جلسة	صفحات HTML

قوائم المسارات الدقيقة تتطور مع المحوِّلات المركَّبة في app.py. لنقاط التوسعة انظر واجهة API ونقاط التوسعة.

ملخص نموذج المصادقة

الوضع	متى
كوكي / ترويسة سر مشترك	مشغِّل وحيد
جلسة ويب معتمة	الافتراضي لتعدد المستخدمين
RBAC منصة (مشاهد/مشغِّل/مشرف)	واجهات SaaS API
OIDC PKCE	دخول SSO
رمز API / JWT	برمجي (حيث يكون مفعَّلًا)

انظر SaaS متعدد المستخدمين ومتغيرات البيئة.