# الأسئلة الشائعة عن الـ API

أسئلة شائعة عن واجهة Synapse API.

## كيف أُصادق؟

طريقتان:

1. **Mind Key** (لنقاط بيانات النهاية): `Authorization: Bearer mk_...`
2. **JWT** (لنقاط نهاية الحساب): `Authorization: Bearer eyJ...`

أو عبر معامل الاستعلام (حد 60 طلبًا/دقيقة): `?key=mk_...`

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

## ما الفرق بين Mind Key و JWT؟

- **Mind Key**: محدود بمستأجر، لا ينتهي، لبيانات الذاكرة/الدردشة/المهام
- **JWT**: محدود بالمستخدم، ينتهي بعد 7 أيام، لإدارة الحساب/العقل

راجع [Mind Key مقابل JWT](/docs/getting-started/mind-key-vs-jwt).

## لماذا أحصل على 401 Unauthorized؟

أسباب شائعة:

1. ترويسة `Authorization` مفقودة
2. Mind Key غير صالح (تحقق أنه يبدأ بـ `mk_`)
3. استخدام JWT حيث يُطلب Mind Key (أو العكس)
4. تم إبطال Mind Key

**الإصلاح:** تحقق من رمزك. راجع [المصادقة](/docs/getting-started/authentication).

## لماذا أحصل على 404 Not Found؟

استخدمت مسار نقطة نهاية خاطئًا. يمتلك Synapse فقط المسارات المذكورة في
`GET /endpoints`.

**الإصلاح:** استدعِ `GET /endpoints` لرؤية جميع المسارات الصالحة. لا تخمّن.

## لماذا أحصل على 429 Too Many Requests؟

تستخدم مصادقة معامل الاستعلام `?key=`، المحدودة بـ 60/دقيقة.

**الإصلاح:** بدّل إلى ترويسة `Authorization: Bearer` (بلا حد معدل).

راجع [حدود المعدل](/docs/api/rate-limits).

## كيف أُدرج جميع نقاط النهاية؟

```bash
curl https://synapse.schaefer.zone/endpoints
curl https://synapse.schaefer.zone/endpoints?format=text
```

## كيف أجد نقطة النهاية المناسبة؟

1. تحقق من `GET /endpoints` للقائمة القابلة للقراءة آليًا
2. تحقق من `GET /help` لوثائق API الكاملة
3. تصفّح `GET /docs` لنظام الوثائق
4. استخدم `GET /openapi.json` لمواصفات OpenAPI 3.0

## هل يمكنني استخدام GET بدلًا من POST؟

بعض نقاط POST لها مكافئات GET للأدوات التي تفتح عناوين URL فقط:

- `POST /memory` ↔ `GET /memory/store?content=...`
- `POST /mind/task` ↔ `GET /mind/task?title=...`
- `POST /chat/reply` ↔ `GET /chat/reply?content=...`

تحقق من `GET /endpoints` لمتغيرات GET المتاحة.

## كيف أتعامل مع الأخطاء؟

تُرجع جميع الأخطاء JSON:

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

راجع [الأخطاء ومعالجتها](/docs/api/errors).

## ما حد حجم نص الطلب؟

10 ميجابايت. للحمولات الأكبر (مثل رفع الملفات)، استخدم نقاط النهاية multipart.

## هل يدعم الـ API CORS؟

نعم. جميع نقاط النهاية تُرجع:

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

## هل توجد حزمة SDK؟

نعم:

- **Node.js**: `npm install synapse-memory-sdk`
- **MCP**: `npx -y synapse-mcp-api@latest`

راجع [نظرة عامة على الـ API](/docs/api/overview) للتفاصيل.

## كيف أتصفّح؟

استخدم `?limit=` و `?offset=`:

```bash
curl ".../memory?limit=50&offset=100"
```

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

## هل أستطيع تصفية الذكريات حسب الفئة أو الوسم؟

نعم:

```bash
curl ".../memory?category=project"
curl ".../memory?tag=docker"
curl ".../memory/by-tag?tag=production"
```

## كيف أبحث في الذكريات؟

بطريقتين:

1. **بحث FTS5 بالكلمات المفتاحية**: `GET /memory/search?q=docker+swarm`
2. **البحث الدلالي**: `GET /memory/semantic-search?q=container+orchestration`

راجع [بحث FTS5](/docs/concepts/fts5-search) و [البحث الدلالي](/docs/concepts/semantic-search).

## كيف أُحدّث ذاكرة؟

استدعِ `POST /memory` بنفس `category` + `key` — تُحدَّث الذاكرة
الموجودة، لا تُكرّر.

```bash
# التخزين الأول
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'

# التحديث (نفس المفتاح)
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'
```

## كيف أحذف ذاكرة؟

```bash
curl -X DELETE -H "Authorization: Bearer $KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## هل أستطيع الحذف الكمي؟

نعم:

```bash
curl -X POST .../memory/bulk-delete \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

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

- [نظرة عامة على الـ API](/docs/api/overview)
- [الأخطاء ومعالجتها](/docs/api/errors)
- [المصادقة](/docs/getting-started/authentication)