Skip to main content

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

beginner 🤖 متوافق مع LLM 3 دقيقة · 563 كلمة تم التحديث: 2026-06-27 العربية

جميع نقاط نهاية Synapse API وعنوان URL الأساسي وأنماط المصادقة وتنسيقات الاستجابة في لمحة سريعة.

اقرأ هذه المقالة كـ: 📄 نص عادي ⚡ JSON 🤖 تنسيق LLM
اللغة: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

نظرة عامة على الـ 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

راجع المصادقة للتفاصيل.

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

المجموعة المصادقة الوصف
عامة لا شيء الصفحة الرئيسية، الحالة، 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

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

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

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

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

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
يربط الحقل `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 (المستودع)
  • خادم MCP: npx -y synapse-mcp-api@latest (المستودع)
  • عميل HTTP: أي مكتبة HTTP (curl، fetch، axios، إلخ)

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

← العودة إلى مرجع واجهة البرمجة