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

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

كيف أُصادق؟

طريقتان:

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

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

راجع المصادقة.

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

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

راجع Mind Key مقابل JWT.

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

أسباب شائعة:

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

الإصلاح: تحقق من رمزك. راجع المصادقة.

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

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

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

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

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

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

راجع حدود المعدل.

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

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:

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

راجع الأخطاء ومعالجتها.

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

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 للتفاصيل.

كيف أتصفّح؟

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

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

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

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

نعم:

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 و البحث الدلالي.

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

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

# التخزين الأول
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"}'

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

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

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

نعم:

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

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

• نظرة عامة على الـ API
• الأخطاء ومعالجتها
• المصادقة