# نظرة عامة على الـ API وعنوان URL الأساسي
SUMMARY: جميع نقاط نهاية Synapse API وعنوان URL الأساسي وأنماط المصادقة وتنسيقات الاستجابة في لمحة سريعة.

KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
      OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.

نظرة عامة على الـ API وعنوان URL الأساسي
واجهة Synapse API هي واجهة HTTP RESTful. تُرجع جميع نقاط النهاية JSON (إلا في
الحالات المذكورة). تغطي هذه الصفحة الأساسيات التي تحتاجها قبل التعمق في نقاط
النهاية المحددة.
عنوان URL الأساسي
[CODE BLOCK]
جميع المسارات في هذا الدليل نسبية إلى عنوان URL الأساسي. بالنسبة للنسخ
المستضافة ذاتيًا، استبدل العنوان بعنوان URL الخاص بك.
المصادقة
طريقتان، كلاهما يُرسل عبر ترويسة :
[CODE BLOCK]
أو عبر معامل الاستعلام (محدود بـ 60 طلبًا/دقيقة):
[CODE BLOCK]
راجع المصادقة للتفاصيل.
مجموعات نقاط النهاية
| المجموعة | المصادقة | الوصف |
|-------|------|-------------|
| عامة | لا شيء | الصفحة الرئيسية، الحالة، OpenAPI، الوثائق |
| الذاكرة | Mind Key | إنشاء/قراءة/تحديث/حذف، بحث، مزامنة، تضمينات |
| الدردشة | Mind Key / JWT | مراسلة غير متزامنة بين الإنسان والوكيل |
| المهام | Mind Key | إدارة المهام |
| السكربتات | Mind Key / JWT | تخزين دائم للسكربتات |
| المجدول | Mind Key | مهام Cron + المتغيرات |
| الـ Webhooks | Mind Key | استدعاءات HTTP عند الأحداث |
| الأجهزة | Mind Key / JWT | تحكم بعيد في الأجهزة |
| المستخدم/العقول | JWT | الحساب + إدارة العقول |
| المشاركة | JWT | مشاركة العقل بين المستخدمين |
| الإشعارات | JWT | اشتراكات Web Push |
| الأدوات | لا شيء | الوقت، الحاسبة، عشوائي (أدوات عامة) |
تنسيقات الاستجابة
- JSON (افتراضي): 
- نص عادي: يُرجع  نصًا محسّنًا لنماذج LLM
- HTML: ، ، ، ، 
مظروف الاستجابة القياسي
تُرجع استجابات النجاح البيانات مباشرة:
[CODE BLOCK]
استجابات الخطأ تستخدم هذا التنسيق:
[CODE BLOCK]
> [!NOTE]
> يربط الحقل  بالوثائق ذات الصلة للأخطاء الشائعة.
رموز حالة HTTP
| الرمز | المعنى |
|------|---------|
| 200 | نجاح (GET، PUT) |
| 201 | تم الإنشاء (POST) |
| 204 | لا يوجد محتوى (DELETE) |
| 400 | طلب سيئ (خطأ تحقق) |
| 401 | غير مصرّح (رمز مفقود/غير صالح) |
| 403 | محظور (نوع رمز خاطئ) |
| 404 | غير موجود (المسار غير موجود) |
| 409 | تعارض (مكرر) |
| 429 | طلبات كثيرة جدًا (حد المعدل) |
| 500 | خطأ في الخادم |
نقاط نهاية الاكتشاف
| نقطة النهاية | الغرض |
|----------|---------|
|  | الصفحة الرئيسية (مُحسّنة لـ LLM) |
|  | قائمة قابلة للقراءة آليًا بجميع نقاط النهاية |
|  | قائمة نقاط النهاية كنص عادي |
|  | مواصفات OpenAPI 3.0 |
|  | وثائق API الكاملة (HTML) |
|  | وثائق API كـ JSON |
|  | نظام الوثائق (HTML) |
|  | فهرس الوثائق (JSON) |
|  | جميع الوثائق ككتلة نصية واحدة |
|  | ساحة تجريبية تفاعلية للـ API |
حدود المعدل
| طريقة المصادقة | الحد |
|-------------|-------|
| Mind Key (ترويسة) | لا يوجد |
| Mind Key (?key=) | 60/دقيقة لكل IP |
| JWT (ترويسة) | لا يوجد |
| نقاط النهاية العامة | لا يوجد |
تتضمن الاستجابات الخاضعة لحد المعدل:
[CODE BLOCK]
التصفح
نقاط نهاية القوائم تدعم  و :
[CODE BLOCK]
الحد الافتراضي: 100. الحد الأقصى: 500.
CORS
جميع نقاط النهاية تدعم CORS لعملاء المتصفح:
[CODE BLOCK]
حزم SDK والعملاء
- Node.js SDK:  (المستودع)
- خادم MCP:  (المستودع)
- عميل HTTP: أي مكتبة HTTP (curl، fetch، axios، إلخ)
الخطوات التالية
- Memory API — أهم نقاط النهاية
- Chat API — تواصل غير متزامن بين الإنسان والوكيل
- الأخطاء ومعالجتها