{"title":"الأسئلة الشائعة عن الـ API","slug":"api-faq","category":"faq","summary":"أسئلة شائعة عن الـ API — المصادقة، حدود المعدل، معالجة الأخطاء، اكتشاف نقاط النهاية.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":359,"read_minutes":2,"lang":"ar","translated":true,"requested_lang":"ar","content_markdown":"\n# الأسئلة الشائعة عن الـ API\n\nأسئلة شائعة عن واجهة Synapse API.\n\n## كيف أُصادق؟\n\nطريقتان:\n\n1. **Mind Key** (لنقاط بيانات النهاية): `Authorization: Bearer mk_...`\n2. **JWT** (لنقاط نهاية الحساب): `Authorization: Bearer eyJ...`\n\nأو عبر معامل الاستعلام (حد 60 طلبًا/دقيقة): `?key=mk_...`\n\nراجع [المصادقة](/docs/getting-started/authentication).\n\n## ما الفرق بين Mind Key و JWT؟\n\n- **Mind Key**: محدود بمستأجر، لا ينتهي، لبيانات الذاكرة/الدردشة/المهام\n- **JWT**: محدود بالمستخدم، ينتهي بعد 7 أيام، لإدارة الحساب/العقل\n\nراجع [Mind Key مقابل JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## لماذا أحصل على 401 Unauthorized؟\n\nأسباب شائعة:\n\n1. ترويسة `Authorization` مفقودة\n2. Mind Key غير صالح (تحقق أنه يبدأ بـ `mk_`)\n3. استخدام JWT حيث يُطلب Mind Key (أو العكس)\n4. تم إبطال Mind Key\n\n**الإصلاح:** تحقق من رمزك. راجع [المصادقة](/docs/getting-started/authentication).\n\n## لماذا أحصل على 404 Not Found؟\n\nاستخدمت مسار نقطة نهاية خاطئًا. يمتلك Synapse فقط المسارات المذكورة في\n`GET /endpoints`.\n\n**الإصلاح:** استدعِ `GET /endpoints` لرؤية جميع المسارات الصالحة. لا تخمّن.\n\n## لماذا أحصل على 429 Too Many Requests؟\n\nتستخدم مصادقة معامل الاستعلام `?key=`، المحدودة بـ 60/دقيقة.\n\n**الإصلاح:** بدّل إلى ترويسة `Authorization: Bearer` (بلا حد معدل).\n\nراجع [حدود المعدل](/docs/api/rate-limits).\n\n## كيف أُدرج جميع نقاط النهاية؟\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## كيف أجد نقطة النهاية المناسبة؟\n\n1. تحقق من `GET /endpoints` للقائمة القابلة للقراءة آليًا\n2. تحقق من `GET /help` لوثائق API الكاملة\n3. تصفّح `GET /docs` لنظام الوثائق\n4. استخدم `GET /openapi.json` لمواصفات OpenAPI 3.0\n\n## هل يمكنني استخدام GET بدلًا من POST؟\n\nبعض نقاط POST لها مكافئات GET للأدوات التي تفتح عناوين URL فقط:\n\n- `POST /memory` ↔ `GET /memory/store?content=...`\n- `POST /mind/task` ↔ `GET /mind/task?title=...`\n- `POST /chat/reply` ↔ `GET /chat/reply?content=...`\n\nتحقق من `GET /endpoints` لمتغيرات GET المتاحة.\n\n## كيف أتعامل مع الأخطاء؟\n\nتُرجع جميع الأخطاء JSON:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\nراجع [الأخطاء ومعالجتها](/docs/api/errors).\n\n## ما حد حجم نص الطلب؟\n\n10 ميجابايت. للحمولات الأكبر (مثل رفع الملفات)، استخدم نقاط النهاية multipart.\n\n## هل يدعم الـ API CORS؟\n\nنعم. جميع نقاط النهاية تُرجع:\n\n```\nAccess-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT\n```\n\n## هل توجد حزمة SDK؟\n\nنعم:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\nراجع [نظرة عامة على الـ API](/docs/api/overview) للتفاصيل.\n\n## كيف أتصفّح؟\n\nاستخدم `?limit=` و `?offset=`:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nالحد الافتراضي: 100. الحد الأقصى: 500.\n\n## هل أستطيع تصفية الذكريات حسب الفئة أو الوسم؟\n\nنعم:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## كيف أبحث في الذكريات؟\n\nبطريقتين:\n\n1. **بحث FTS5 بالكلمات المفتاحية**: `GET /memory/search?q=docker+swarm`\n2. **البحث الدلالي**: `GET /memory/semantic-search?q=container+orchestration`\n\nراجع [بحث FTS5](/docs/concepts/fts5-search) و [البحث الدلالي](/docs/concepts/semantic-search).\n\n## كيف أُحدّث ذاكرة؟\n\nاستدعِ `POST /memory` بنفس `category` + `key` — تُحدَّث الذاكرة\nالموجودة، لا تُكرّر.\n\n```bash\n# التخزين الأول\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# التحديث (نفس المفتاح)\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## كيف أحذف ذاكرة؟\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## هل أستطيع الحذف الكمي؟\n\nنعم:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## الخطوات التالية\n\n- [نظرة عامة على الـ API](/docs/api/overview)\n- [الأخطاء ومعالجتها](/docs/api/errors)\n- [المصادقة](/docs/getting-started/authentication)\n","content_html":"

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

\n

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

\n

كيف أُصادق؟

\n

طريقتان:

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

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

\n

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

\n

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

\n\n

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

\n

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

\n

أسباب شائعة:

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

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

\n

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

\n

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

\n

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

\n

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

\n

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

\n

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

\n

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

\n

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

\n
curl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text

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

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

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

\n

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

\n\n

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

\n

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

\n

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

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

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

\n

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

\n

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

\n

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

\n

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

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

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

\n

نعم:

\n\n

راجع نظرة عامة على الـ API للتفاصيل.

\n

كيف أتصفّح؟

\n

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

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

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

\n

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

\n

نعم:

\n
curl ".../memory?category=project"\ncurl ".../memory?tag=docker"\ncurl ".../memory/by-tag?tag=production"

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

\n

بطريقتين:

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

راجع بحث FTS5 و البحث الدلالي.

\n

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

\n

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

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

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

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

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

\n

نعم:

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

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

\n\n","urls":{"html":"/docs/faq/api-faq","text":"/docs/faq/api-faq?format=text","json":"/docs/faq/api-faq?format=json","llm":"/docs/faq/api-faq?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}