# نظرة عامة على الـ API وعنوان URL الأساسي

واجهة Synapse API هي واجهة HTTP RESTful. تُرجع جميع نقاط النهاية JSON (إلا في
الحالات المذكورة). تغطي هذه الصفحة الأساسيات التي تحتاجها قبل التعمق في نقاط
النهاية المحددة.

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

```
https://synapse.schaefer.zone
```

جميع المسارات في هذا الدليل نسبية إلى عنوان URL الأساسي. بالنسبة للنسخ
المستضافة ذاتيًا، استبدل العنوان بعنوان URL الخاص بك.

## المصادقة

طريقتان، كلاهما يُرسل عبر ترويسة `Authorization`:

```
Authorization: Bearer YOUR_MIND_KEY    # لنقاط بيانات النهاية
Authorization: Bearer YOUR_JWT          # لنقاط نهاية الحساب
```

أو عبر معامل الاستعلام (محدود بـ 60 طلبًا/دقيقة):

```
?key=YOUR_MIND_KEY
```

راجع [المصادقة](/docs/getting-started/authentication) للتفاصيل.

## مجموعات نقاط النهاية

| المجموعة | المصادقة | الوصف |
|-------|------|-------------|
| عامة | لا شيء | الصفحة الرئيسية، الحالة، 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** (افتراضي): `{ "key": "value", ... }`
- **نص عادي**: يُرجع `/memory/recall` نصًا محسّنًا لنماذج LLM
- **HTML**: `/`، `/docs`، `/human`، `/support`، `/playground`

## مظروف الاستجابة القياسي

تُرجع استجابات النجاح البيانات مباشرة:

```json
{ "id": "mem_001", "status": "stored" }
```

استجابات الخطأ تستخدم هذا التنسيق:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

> [!NOTE]
> يربط الحقل `docs` بالوثائق ذات الصلة للأخطاء الشائعة.

## رموز حالة HTTP

| الرمز | المعنى |
|------|---------|
| 200 | نجاح (GET، PUT) |
| 201 | تم الإنشاء (POST) |
| 204 | لا يوجد محتوى (DELETE) |
| 400 | طلب سيئ (خطأ تحقق) |
| 401 | غير مصرّح (رمز مفقود/غير صالح) |
| 403 | محظور (نوع رمز خاطئ) |
| 404 | غير موجود (المسار غير موجود) |
| 409 | تعارض (مكرر) |
| 429 | طلبات كثيرة جدًا (حد المعدل) |
| 500 | خطأ في الخادم |

## نقاط نهاية الاكتشاف

| نقطة النهاية | الغرض |
|----------|---------|
| `GET /` | الصفحة الرئيسية (مُحسّنة لـ LLM) |
| `GET /endpoints` | قائمة قابلة للقراءة آليًا بجميع نقاط النهاية |
| `GET /endpoints?format=text` | قائمة نقاط النهاية كنص عادي |
| `GET /openapi.json` | مواصفات OpenAPI 3.0 |
| `GET /help` | وثائق API الكاملة (HTML) |
| `GET /help?format=json` | وثائق API كـ JSON |
| `GET /docs` | نظام الوثائق (HTML) |
| `GET /docs?format=json` | فهرس الوثائق (JSON) |
| `GET /docs?format=text&scope=all` | جميع الوثائق ككتلة نصية واحدة |
| `GET /playground` | ساحة تجريبية تفاعلية للـ API |

## حدود المعدل

| طريقة المصادقة | الحد |
|-------------|-------|
| Mind Key (ترويسة) | لا يوجد |
| Mind Key (?key=) | 60/دقيقة لكل IP |
| JWT (ترويسة) | لا يوجد |
| نقاط النهاية العامة | لا يوجد |

تتضمن الاستجابات الخاضعة لحد المعدل:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (فقط عند 429)
```

## التصفح

نقاط نهاية القوائم تدعم `?limit=` و `?offset=`:

```
GET /memory?limit=50&offset=100
GET /mind/tasks?status=pending
```

الحد الافتراضي: 100. الحد الأقصى: 500.

## CORS

جميع نقاط النهاية تدعم CORS لعملاء المتصفح:

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT, Mcp-Session-Id, Mcp-Tool-Profile
```

## حزم SDK والعملاء

- **Node.js SDK**: `npm install synapse-memory-sdk` ([المستودع](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **خادم MCP**: `npx -y synapse-mcp-api@latest` ([المستودع](https://gitlab.com/schaefer-services/synapse-mcp))
- **عميل HTTP**: أي مكتبة HTTP (curl، fetch، axios، إلخ)

## الخطوات التالية

- [Memory API](/docs/api/memory) — أهم نقاط النهاية
- [Chat API](/docs/api/chat) — تواصل غير متزامن بين الإنسان والوكيل
- [الأخطاء ومعالجتها](/docs/api/errors)