{"title":"نظرة عامة على الـ API وعنوان URL الأساسي","slug":"overview","category":"api","summary":"جميع نقاط نهاية Synapse API وعنوان URL الأساسي وأنماط المصادقة وتنسيقات الاستجابة في لمحة سريعة.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":563,"read_minutes":3,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n      OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"ar","translated":true,"requested_lang":"ar","content_markdown":"\n# نظرة عامة على الـ API وعنوان URL الأساسي\n\nواجهة Synapse API هي واجهة HTTP RESTful. تُرجع جميع نقاط النهاية JSON (إلا في\nالحالات المذكورة). تغطي هذه الصفحة الأساسيات التي تحتاجها قبل التعمق في نقاط\nالنهاية المحددة.\n\n## عنوان URL الأساسي\n\n```\nhttps://synapse.schaefer.zone\n```\n\nجميع المسارات في هذا الدليل نسبية إلى عنوان URL الأساسي. بالنسبة للنسخ\nالمستضافة ذاتيًا، استبدل العنوان بعنوان URL الخاص بك.\n\n## المصادقة\n\nطريقتان، كلاهما يُرسل عبر ترويسة `Authorization`:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY    # لنقاط بيانات النهاية\nAuthorization: Bearer YOUR_JWT          # لنقاط نهاية الحساب\n```\n\nأو عبر معامل الاستعلام (محدود بـ 60 طلبًا/دقيقة):\n\n```\n?key=YOUR_MIND_KEY\n```\n\nراجع [المصادقة](/docs/getting-started/authentication) للتفاصيل.\n\n## مجموعات نقاط النهاية\n\n| المجموعة | المصادقة | الوصف |\n|-------|------|-------------|\n| عامة | لا شيء | الصفحة الرئيسية، الحالة، OpenAPI، الوثائق |\n| الذاكرة | Mind Key | إنشاء/قراءة/تحديث/حذف، بحث، مزامنة، تضمينات |\n| الدردشة | Mind Key / JWT | مراسلة غير متزامنة بين الإنسان والوكيل |\n| المهام | Mind Key | إدارة المهام |\n| السكربتات | Mind Key / JWT | تخزين دائم للسكربتات |\n| المجدول | Mind Key | مهام Cron + المتغيرات |\n| الـ Webhooks | Mind Key | استدعاءات HTTP عند الأحداث |\n| الأجهزة | Mind Key / JWT | تحكم بعيد في الأجهزة |\n| المستخدم/العقول | JWT | الحساب + إدارة العقول |\n| المشاركة | JWT | مشاركة العقل بين المستخدمين |\n| الإشعارات | JWT | اشتراكات Web Push |\n| الأدوات | لا شيء | الوقت، الحاسبة، عشوائي (أدوات عامة) |\n\n## تنسيقات الاستجابة\n\n- **JSON** (افتراضي): `{ \"key\": \"value\", ... }`\n- **نص عادي**: يُرجع `/memory/recall` نصًا محسّنًا لنماذج LLM\n- **HTML**: `/`، `/docs`، `/human`، `/support`، `/playground`\n\n## مظروف الاستجابة القياسي\n\nتُرجع استجابات النجاح البيانات مباشرة:\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nاستجابات الخطأ تستخدم هذا التنسيق:\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> [!NOTE]\n> يربط الحقل `docs` بالوثائق ذات الصلة للأخطاء الشائعة.\n\n## رموز حالة HTTP\n\n| الرمز | المعنى |\n|------|---------|\n| 200 | نجاح (GET، PUT) |\n| 201 | تم الإنشاء (POST) |\n| 204 | لا يوجد محتوى (DELETE) |\n| 400 | طلب سيئ (خطأ تحقق) |\n| 401 | غير مصرّح (رمز مفقود/غير صالح) |\n| 403 | محظور (نوع رمز خاطئ) |\n| 404 | غير موجود (المسار غير موجود) |\n| 409 | تعارض (مكرر) |\n| 429 | طلبات كثيرة جدًا (حد المعدل) |\n| 500 | خطأ في الخادم |\n\n## نقاط نهاية الاكتشاف\n\n| نقطة النهاية | الغرض |\n|----------|---------|\n| `GET /` | الصفحة الرئيسية (مُحسّنة لـ LLM) |\n| `GET /endpoints` | قائمة قابلة للقراءة آليًا بجميع نقاط النهاية |\n| `GET /endpoints?format=text` | قائمة نقاط النهاية كنص عادي |\n| `GET /openapi.json` | مواصفات OpenAPI 3.0 |\n| `GET /help` | وثائق API الكاملة (HTML) |\n| `GET /help?format=json` | وثائق API كـ JSON |\n| `GET /docs` | نظام الوثائق (HTML) |\n| `GET /docs?format=json` | فهرس الوثائق (JSON) |\n| `GET /docs?format=text&scope=all` | جميع الوثائق ككتلة نصية واحدة |\n| `GET /playground` | ساحة تجريبية تفاعلية للـ API |\n\n## حدود المعدل\n\n| طريقة المصادقة | الحد |\n|-------------|-------|\n| Mind Key (ترويسة) | لا يوجد |\n| Mind Key (?key=) | 60/دقيقة لكل IP |\n| JWT (ترويسة) | لا يوجد |\n| نقاط النهاية العامة | لا يوجد |\n\nتتضمن الاستجابات الخاضعة لحد المعدل:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (فقط عند 429)\n```\n\n## التصفح\n\nنقاط نهاية القوائم تدعم `?limit=` و `?offset=`:\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nالحد الافتراضي: 100. الحد الأقصى: 500.\n\n## CORS\n\nجميع نقاط النهاية تدعم CORS لعملاء المتصفح:\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, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## حزم SDK والعملاء\n\n- **Node.js SDK**: `npm install synapse-memory-sdk` ([المستودع](https://gitlab.com/schaefer-services/synapse-sdk-js))\n- **خادم MCP**: `npx -y synapse-mcp-api@latest` ([المستودع](https://gitlab.com/schaefer-services/synapse-mcp))\n- **عميل HTTP**: أي مكتبة HTTP (curl، fetch، axios، إلخ)\n\n## الخطوات التالية\n\n- [Memory API](/docs/api/memory) — أهم نقاط النهاية\n- [Chat API](/docs/api/chat) — تواصل غير متزامن بين الإنسان والوكيل\n- [الأخطاء ومعالجتها](/docs/api/errors)\n","content_html":"<h1>نظرة عامة على الـ API وعنوان URL الأساسي</h1>\n<p>واجهة Synapse API هي واجهة HTTP RESTful. تُرجع جميع نقاط النهاية JSON (إلا في\nالحالات المذكورة). تغطي هذه الصفحة الأساسيات التي تحتاجها قبل التعمق في نقاط\nالنهاية المحددة.</p>\n<h2>عنوان URL الأساسي</h2>\n<pre><code class=\"hljs language-plaintext\">https://synapse.schaefer.zone</code></pre><p>جميع المسارات في هذا الدليل نسبية إلى عنوان URL الأساسي. بالنسبة للنسخ\nالمستضافة ذاتيًا، استبدل العنوان بعنوان URL الخاص بك.</p>\n<h2>المصادقة</h2>\n<p>طريقتان، كلاهما يُرسل عبر ترويسة <code>Authorization</code>:</p>\n<pre><code class=\"hljs language-plaintext\">Authorization: Bearer YOUR_MIND_KEY    # لنقاط بيانات النهاية\nAuthorization: Bearer YOUR_JWT          # لنقاط نهاية الحساب</code></pre><p>أو عبر معامل الاستعلام (محدود بـ 60 طلبًا/دقيقة):</p>\n<pre><code class=\"hljs language-plaintext\">?key=YOUR_MIND_KEY</code></pre><p>راجع <a href=\"/docs/getting-started/authentication\">المصادقة</a> للتفاصيل.</p>\n<h2>مجموعات نقاط النهاية</h2>\n<table>\n<thead>\n<tr>\n<th>المجموعة</th>\n<th>المصادقة</th>\n<th>الوصف</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>عامة</td>\n<td>لا شيء</td>\n<td>الصفحة الرئيسية، الحالة، OpenAPI، الوثائق</td>\n</tr>\n<tr>\n<td>الذاكرة</td>\n<td>Mind Key</td>\n<td>إنشاء/قراءة/تحديث/حذف، بحث، مزامنة، تضمينات</td>\n</tr>\n<tr>\n<td>الدردشة</td>\n<td>Mind Key / JWT</td>\n<td>مراسلة غير متزامنة بين الإنسان والوكيل</td>\n</tr>\n<tr>\n<td>المهام</td>\n<td>Mind Key</td>\n<td>إدارة المهام</td>\n</tr>\n<tr>\n<td>السكربتات</td>\n<td>Mind Key / JWT</td>\n<td>تخزين دائم للسكربتات</td>\n</tr>\n<tr>\n<td>المجدول</td>\n<td>Mind Key</td>\n<td>مهام Cron + المتغيرات</td>\n</tr>\n<tr>\n<td>الـ Webhooks</td>\n<td>Mind Key</td>\n<td>استدعاءات HTTP عند الأحداث</td>\n</tr>\n<tr>\n<td>الأجهزة</td>\n<td>Mind Key / JWT</td>\n<td>تحكم بعيد في الأجهزة</td>\n</tr>\n<tr>\n<td>المستخدم/العقول</td>\n<td>JWT</td>\n<td>الحساب + إدارة العقول</td>\n</tr>\n<tr>\n<td>المشاركة</td>\n<td>JWT</td>\n<td>مشاركة العقل بين المستخدمين</td>\n</tr>\n<tr>\n<td>الإشعارات</td>\n<td>JWT</td>\n<td>اشتراكات Web Push</td>\n</tr>\n<tr>\n<td>الأدوات</td>\n<td>لا شيء</td>\n<td>الوقت، الحاسبة، عشوائي (أدوات عامة)</td>\n</tr>\n</tbody></table>\n<h2>تنسيقات الاستجابة</h2>\n<ul>\n<li><strong>JSON</strong> (افتراضي): <code>{ &quot;key&quot;: &quot;value&quot;, ... }</code></li>\n<li><strong>نص عادي</strong>: يُرجع <code>/memory/recall</code> نصًا محسّنًا لنماذج LLM</li>\n<li><strong>HTML</strong>: <code>/</code>، <code>/docs</code>، <code>/human</code>، <code>/support</code>، <code>/playground</code></li>\n</ul>\n<h2>مظروف الاستجابة القياسي</h2>\n<p>تُرجع استجابات النجاح البيانات مباشرة:</p>\n<pre><code class=\"hljs language-json\"><span class=\"hljs-punctuation\">{</span> <span class=\"hljs-attr\">&quot;id&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;mem_001&quot;</span><span class=\"hljs-punctuation\">,</span> <span class=\"hljs-attr\">&quot;status&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;stored&quot;</span> <span class=\"hljs-punctuation\">}</span></code></pre><p>استجابات الخطأ تستخدم هذا التنسيق:</p>\n<pre><code class=\"hljs language-json\"><span class=\"hljs-punctuation\">{</span>\n  <span class=\"hljs-attr\">&quot;statusCode&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-number\">401</span><span class=\"hljs-punctuation\">,</span>\n  <span class=\"hljs-attr\">&quot;error&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;Unauthorized&quot;</span><span class=\"hljs-punctuation\">,</span>\n  <span class=\"hljs-attr\">&quot;message&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;Mind Key fehlt oder ungültig.&quot;</span><span class=\"hljs-punctuation\">,</span>\n  <span class=\"hljs-attr\">&quot;docs&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/docs/getting-started/authentication&quot;</span>\n<span class=\"hljs-punctuation\">}</span></code></pre><div class=\"callout callout-note\">يربط الحقل `docs` بالوثائق ذات الصلة للأخطاء الشائعة.</div><h2>رموز حالة HTTP</h2>\n<table>\n<thead>\n<tr>\n<th>الرمز</th>\n<th>المعنى</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>200</td>\n<td>نجاح (GET، PUT)</td>\n</tr>\n<tr>\n<td>201</td>\n<td>تم الإنشاء (POST)</td>\n</tr>\n<tr>\n<td>204</td>\n<td>لا يوجد محتوى (DELETE)</td>\n</tr>\n<tr>\n<td>400</td>\n<td>طلب سيئ (خطأ تحقق)</td>\n</tr>\n<tr>\n<td>401</td>\n<td>غير مصرّح (رمز مفقود/غير صالح)</td>\n</tr>\n<tr>\n<td>403</td>\n<td>محظور (نوع رمز خاطئ)</td>\n</tr>\n<tr>\n<td>404</td>\n<td>غير موجود (المسار غير موجود)</td>\n</tr>\n<tr>\n<td>409</td>\n<td>تعارض (مكرر)</td>\n</tr>\n<tr>\n<td>429</td>\n<td>طلبات كثيرة جدًا (حد المعدل)</td>\n</tr>\n<tr>\n<td>500</td>\n<td>خطأ في الخادم</td>\n</tr>\n</tbody></table>\n<h2>نقاط نهاية الاكتشاف</h2>\n<table>\n<thead>\n<tr>\n<th>نقطة النهاية</th>\n<th>الغرض</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /</code></td>\n<td>الصفحة الرئيسية (مُحسّنة لـ LLM)</td>\n</tr>\n<tr>\n<td><code>GET /endpoints</code></td>\n<td>قائمة قابلة للقراءة آليًا بجميع نقاط النهاية</td>\n</tr>\n<tr>\n<td><code>GET /endpoints?format=text</code></td>\n<td>قائمة نقاط النهاية كنص عادي</td>\n</tr>\n<tr>\n<td><code>GET /openapi.json</code></td>\n<td>مواصفات OpenAPI 3.0</td>\n</tr>\n<tr>\n<td><code>GET /help</code></td>\n<td>وثائق API الكاملة (HTML)</td>\n</tr>\n<tr>\n<td><code>GET /help?format=json</code></td>\n<td>وثائق API كـ JSON</td>\n</tr>\n<tr>\n<td><code>GET /docs</code></td>\n<td>نظام الوثائق (HTML)</td>\n</tr>\n<tr>\n<td><code>GET /docs?format=json</code></td>\n<td>فهرس الوثائق (JSON)</td>\n</tr>\n<tr>\n<td><code>GET /docs?format=text&amp;scope=all</code></td>\n<td>جميع الوثائق ككتلة نصية واحدة</td>\n</tr>\n<tr>\n<td><code>GET /playground</code></td>\n<td>ساحة تجريبية تفاعلية للـ API</td>\n</tr>\n</tbody></table>\n<h2>حدود المعدل</h2>\n<table>\n<thead>\n<tr>\n<th>طريقة المصادقة</th>\n<th>الحد</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Mind Key (ترويسة)</td>\n<td>لا يوجد</td>\n</tr>\n<tr>\n<td>Mind Key (?key=)</td>\n<td>60/دقيقة لكل IP</td>\n</tr>\n<tr>\n<td>JWT (ترويسة)</td>\n<td>لا يوجد</td>\n</tr>\n<tr>\n<td>نقاط النهاية العامة</td>\n<td>لا يوجد</td>\n</tr>\n</tbody></table>\n<p>تتضمن الاستجابات الخاضعة لحد المعدل:</p>\n<pre><code class=\"hljs language-plaintext\">X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (فقط عند 429)</code></pre><h2>التصفح</h2>\n<p>نقاط نهاية القوائم تدعم <code>?limit=</code> و <code>?offset=</code>:</p>\n<pre><code class=\"hljs language-plaintext\">GET /memory?limit=50&amp;offset=100\nGET /mind/tasks?status=pending</code></pre><p>الحد الافتراضي: 100. الحد الأقصى: 500.</p>\n<h2>CORS</h2>\n<p>جميع نقاط النهاية تدعم CORS لعملاء المتصفح:</p>\n<pre><code class=\"hljs language-plaintext\">Access-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT, Mcp-Session-Id, Mcp-Tool-Profile</code></pre><h2>حزم SDK والعملاء</h2>\n<ul>\n<li><strong>Node.js SDK</strong>: <code>npm install synapse-memory-sdk</code> (<a href=\"https://gitlab.com/schaefer-services/synapse-sdk-js\">المستودع</a>)</li>\n<li><strong>خادم MCP</strong>: <code>npx -y synapse-mcp-api@latest</code> (<a href=\"https://gitlab.com/schaefer-services/synapse-mcp\">المستودع</a>)</li>\n<li><strong>عميل HTTP</strong>: أي مكتبة HTTP (curl، fetch، axios، إلخ)</li>\n</ul>\n<h2>الخطوات التالية</h2>\n<ul>\n<li><a href=\"/docs/api/memory\">Memory API</a> — أهم نقاط النهاية</li>\n<li><a href=\"/docs/api/chat\">Chat API</a> — تواصل غير متزامن بين الإنسان والوكيل</li>\n<li><a href=\"/docs/api/errors\">الأخطاء ومعالجتها</a></li>\n</ul>\n","urls":{"html":"/docs/api/overview","text":"/docs/api/overview?format=text","json":"/docs/api/overview?format=json","llm":"/docs/api/overview?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}