API Overview

أهلاً بك في وثائق Minds API. يتيح لك API الخاص بنا إنشاء وإدارة AI minds برمجياً، ورفع المعرفة، والتفاعل معها.

البدء

Minds API منظَّم حول مبادئ REST. لـ API الخاص بنا URLs موجهة نحو الموارد يمكن توقعها، ويقبل أجسام طلب بترميز JSON، ويُرجع استجابات بترميز JSON، ويستخدم رموز استجابة HTTP ومصادقة وأفعال قياسية.

Base URL

Production: https://getminds.ai/api/v1 أو https://api.getminds.ai/v1

Local Development: http://localhost:3000/api/v1

كلا base URLs للإنتاج متكافئان تماماً. يُوصى بالنطاق الفرعي api.getminds.ai للحصول على URLs تكامل أنظف.

المصادقة

تتطلب جميع endpoints الـ API مصادقة عبر مفتاح API. يمكنك توليد وإدارة مفاتيح API الخاصة بك في Settings → API Keys.

ضمّن مفتاح API الخاص بك في ترويسة Authorization:

Authorization: Bearer minds_your_api_key_here

مواصفة OpenAPI

تُنشَر مواصفة OpenAPI 3.1.0 قابلة للقراءة آليًا على /_openapi.json. استخدم المواصفة لتوليد عملاء بأنواع محددة (TypeScript وPython وغيرها) أو لإسقاطها في نموذج LLM للحصول على كود تكامل بضربة واحدة. راجع OpenAPI للاطّلاع على أمثلة.

Content Type

يجب أن تتضمن جميع الطلبات التي ترسل بيانات ترويسة Content-Type:

Content-Type: application/json

لرفع الملفات، استخدم:

Content-Type: multipart/form-data

Endpoints المتاحة

Minds

أنشئ وأدِر AI minds (agents) بتهيئات مخصصة.

• GET /api/v1/minds — عرض جميع الـ Minds
• GET /api/v1/minds/{mindId} — الحصول على تفاصيل Mind
• POST /api/v1/minds — إنشاء Mind جديد
• PUT /api/v1/minds/{mindId} — تحديث Mind
• DELETE /api/v1/minds/{mindId} — حذف Mind
• POST /api/v1/minds/{mindId}/regenerate-prompt — إعادة توليد نظام البرومبت من المعرفة

Knowledge

أدِر المعرفة للـ minds الخاصة بك.

• GET /api/v1/minds/{mindId}/knowledge — عرض عناصر المعرفة
• POST /api/v1/minds/{mindId}/knowledge — إضافة معرفة (روابط أو ملفات أو بحث بالكلمات المفتاحية)
• PUT /api/v1/minds/{mindId}/knowledge/{itemId} — تحديث عنصر معرفة
• DELETE /api/v1/minds/{mindId}/knowledge/{itemId} — حذف عنصر معرفة
• POST /api/v1/minds/{mindId}/knowledge/enrich — إثراء عبر البحث بالكلمات المفتاحية (اختصار مريح)
• GET /api/v1/minds/{mindId}/knowledge/patterns — الحصول على أنماط المعرفة حسب الإطار

Chat

تفاعل مع الـ minds الخاصة بك عبر إكمالات المحادثة.

• POST /api/v1/minds/{mindId}/completion — إرسال الرسائل والحصول على الاستجابات

Studies

أنشئ وأدِر AI studies لاستطلاع مجموعات من الـ minds.

• GET /api/v1/studies — عرض جميع الـ studies
• POST /api/v1/studies — إنشاء study جديد
• GET /api/v1/studies/{studyId} — الحصول على تفاصيل study مع سجل الرسائل
• POST /api/v1/studies/{studyId}/ask — طرح سؤال على جميع minds الـ study (SSE stream)
• POST /api/v1/studies/{studyId}/export — تصدير نتائج study كتقرير
• GET /api/v1/studies/{studyId}/export-status — فحص حالة مهمة التصدير
• GET /api/v1/studies/{studyId}/export-download — تنزيل PDF المُصدَّر

User

endpoints متعلقة بالمستخدم.

• GET /api/v1/auth/me — الحصول على المستخدم المصادق الحالي
• GET /api/v1/user/shareable-sparks — عرض الـ minds المتاحة للمشاركة

API Keys

أدِر مفاتيح API الخاصة بك للمصادقة.

• GET /api/v1/api-keys — عرض مفاتيح API الخاصة بك
• POST /api/v1/api-keys — إنشاء مفتاح API جديد
• DELETE /api/v1/api-keys/{keyId} — حذف مفتاح API

مثال سريع

إليك مثال سريع لإنشاء mind والمحادثة معه:

# 1. Create a mind (keywords mode)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Expert in digital marketing strategies",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["SEO", "content marketing", "social media", "analytics"]
  }'

# Response: { "data": { "id": "mind-id", ... }, "processing": { "queued": true, ... } }

# 2. Create a mind from social profile (clone mode)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Influencer Clone",
    "description": "AI trained on influencer social presence",
    "mode": "clone",
    "type": "creative",
    "discipline": "Social Media Marketing",
    "personaContext": "https://twitter.com/username"
  }'

# 3. Chat with the mind
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top social media trends for 2025?"
      }
    ]
  }'

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

• تعرّف على المصادقة
• استكشف Minds endpoints
• اقرأ عن إدارة المعرفة
• افهم Chat completions
• أنشئ Studies لاستطلاعات متعددة الـ minds
• راجع Latency والأداء
• اتصل عبر MCP Integration
• راجع Errors والحدود

حدود الباقات

يتوفر الوصول إلى API وMCP في الباقات المدفوعة المدعومة. عالج استجابات plan_limited و429 المنظمة بدلًا من تثبيت الحدود داخل التكامل. تظهر باقة Individual باسم "premium" في حمولات API.

تُنشأ القيم العامة الافتراضية أدناه من عقد حدود الباقات والوصول إلى الميزات نفسه المستخدم في المنتج. تتقدم التجاوزات الخاصة بالحساب أو بعقد Enterprise والظاهرة في المنتج على هذه القيم.

عرض الباقات

هل تحتاج إلى مساعدة؟

إذا كان لديك أسئلة أو تحتاج إلى دعم في API:

• راجع الدليل
• تواصل معنا عبر نموذج الملاحظات
• انضم إلى نقاشات مجتمعنا

سير عمل n8n

استخدم عقدة مجتمع Minds لـ n8n لإنشاء دراسات، ومعاينة خطط البحث، واسترجاع الدراسات والملخصات المحفوظة، أو عرض عملية لوكيل ذكاء اصطناعي. قم بتثبيت n8n-nodes-minds على n8n المستضاف ذاتياً وقم بتوصيل مفتاح Minds API. الحزمة منشورة على npm؛ والتحقق من n8n قيد المراجعة، لذا فهي غير متاحة بعد على n8n Cloud. راجع البحث وابدأه بشكل منفصل في Minds.

فوترة Stripe للوكلاء

استخدم دليل الفوترة المصادق عليه قبل اقتراح عملية شراء رصيد إجابات. يستخدم العملاء الجدد الدفع حسب الاستخدام؛ وقد تم إيقاف الاشتراكات والتجارب الجديدة لخطة Starter. تظل إدارة الاشتراكات الحالية في إعدادات فوترة Minds. اطلب من المشتري الموافقة على باقة الإجابات المحددة والمبلغ النهائي للدفع عبر Stripe.

بالنسبة لمساحة عمل جديدة تعمل بنظام الدفع حسب الاستخدام، يرجى تقديم بلد الفوترة الخاص بالمشتري عند قراءة الدليل وبدء عملية الدفع حتى يتم الحصول على الأسعار من حساب Stripe الصحيح. تظل أعداد الإجابات هي وحدة الشراء؛ ولكل باقة نفس سعر الوحدة. اقرأ الدليل مرة أخرى إذا تغير البلد.

ابدأ عملية الدفع باستخدام Idempotency-Key ثابت يتكون من 1–128 حرفًا أو رقمًا أو شرطة سفلية أو شرطة. احتفظ بنفس المفتاح والنص بعد انتهاء المهلة؛ سيتم رفض تغيير عملية الشراء تحت هذا المفتاح. أعد data.url حرفيًا إلى المشتري. لا يُعد عنوان URL الخاص بالدفع دليلاً على السداد: حيث يقوم تنفيذ Stripe الموقّع بتحديث رصيد الإجابات المشترك.

{
  "kind": "response_credits",
  "amountMinor": 10000,
  "priceId": "price_from_customTopUp",
  "billingCountry": "DE"
}

ينطبق MPP وx402 على الفواتير المفتوحة المملوكة للحساب بطريقة send_invoice، بعملة USD أو EUR وبحد أدنى 50 وحدة نقدية صغرى متبقية. يستمر التحصيل التلقائي عبر صفحة فاتورة Stripe. يحدد طلب الدفع الرصيد الفعلي مع الضرائب والخصومات. يتطلب MPP ملفاً تجارياً في حساب Stripe المالك. ويتطلب x402 أيضاً أهلية العملات المشفرة وخدمة تسهيل مهيأة؛ يدعم فواتير USD عبر Base USDC ويشترط امتداد ربط المسار mppx، فلا يمكن للمحافظ التي تفتقر إليه الدفع عبر هذا المسار.

احتفظ بـAuthorization: Bearer لهوية Minds وأرسل بيانات MPP في Payment-Authorization أو x402 في PAYMENT-SIGNATURE. يمكن لعملاء MPP الأصليين استخدام Authorization: Payment مع بيانات bearer الخاصة بـMinds في Minds-Authorization في هذا المسار فقط. لا تضع بيانات الدفع ضمن معاملات MCP المرئية للنموذج. أعد محاولة الدفع غير المؤكد ببياناته الأصلية؛ لا يجوز لبيانات جديدة إنشاء خصم ثانٍ. تحدد مصادقة Stripe وآلية Webhook الموقعة إتاحة الخدمة.

اكتشف خيارات الدفع عبر /openapi.json؛ يحدد رد 402 المبالغ الديناميكية. يعلن /.well-known/acp.json عن محول إتمام الشراء المستضاف تحت /api/acp بالإصدار 2026-04-17. أنشئ جلسة بسعر Stripe واحد في line_items وعملته currency وcapabilities: {}؛ ضع billingCountry وquantity لمقاعد الفريق وlegalAcceptance للاشتراك في metadata. تستخدم القراءة والتحديث والإكمال والإلغاء /checkout_sessions/{id} مع /complete أو /cancel. تتطلب طلبات POST مفتاح عدم التكرار. يقبل التحديث والإكمال محتوى فارغاً؛ أعد continue_url عند الحاجة إلى تدخل المشتري، ولا تعلن الإكمال إلا بعد تأكيد Stripe.

يتوفر اكتشاف UCP عبر /.well-known/ucp بالإصدار 2026-08-25، وإتمام الشراء عبر REST تحت /api/ucp باستخدام جلسات Stripe نفسها التي تستخدمها MCP وواجهة الفوترة. انشر ملف منصة متوافقًا واستخدم عميل Minds OAuth بوثيقة بيانات وصفية على أصل HTTPS نفسه؛ لا يمكن لمفاتيح API الشخصية ادعاء ملف منصة عشوائي. أرسل UCP-Agent: profile="https://your-platform.example/.well-known/ucp" مع كل طلب، وIdempotency-Key مع عمليات الكتابة. قائمة معالجات الدفع فارغة لأن المشتري يكمل الدفع عبر Stripe Checkout.

اشتراكات Webhook للجاهزية

استخدم مفتاح API أو اتصال OAuth المصادق عليه نفسه المستخدم للمورد. يعيد GET /api/v1/events الأحداث المسموح بها ومخططات الإدخال والحمولة الدقيقة. ينشئ POST /api/v1/events/subscribe اشتراكاً محدداً أو يجدده؛ ويوقفه POST /api/v1/events/unsubscribe بالحدث والمعلمات وعنوان الاستدعاء الأصلية دون إلغاء البحث. يتطلب الجمهور operationId والدراسة studyId وrunId. طرق MCP هي events/list وevents/subscribe وevents/unsubscribe ويكتشفها server/discover مع البروتوكول 2026-07-28.

{
  "name": "study.run.finished",
  "arguments": {
    "studyId": "163bcb31-6ca7-4fef-91bd-9b963a9dd39f",
    "runId": "663bcb31-6ca7-4fef-91bd-9b963a9dd39f"
  },
  "delivery": {
    "mode": "webhook",
    "url": "https://receiver.example/mcp-events",
    "secret": "whsec_<base64-encoded-signing-key>"
  },
  "cursor": null
}

يجب أن يعيد استدعاء HTTPS قيمة challenge من طلب التحقق الموقّع. تستخدم الطلبات رؤوس Standard Webhooks: webhook-id وwebhook-timestamp وwebhook-signature وX-MCP-Subscription-Id. يجب فك مفتاح whsec_ إلى 24–64 بايت. تُرفض العناوين الخاصة وإعادة التوجيه وبيانات الاعتماد في العنوان. يعيد فشل التحقق MCP -32015 مع سبب ولا يفعّل الاشتراك. يؤكد HTTP 2xx الاستلام؛ وتُعاد الأخطاء المؤقتة بمحاولات محدودة وتأخير أُسّي ومعرف حدث ثابت، بينما يوقف 410 و413 التسليم. أزل التكرار بحسب معرف الحدث قبل أي إجراء لاحق.

تتضمن الاستجابة id وrefreshBefore وcursor:null وtruncated:false. يطلب ttlMs مدة أقصر؛ ويمنح حذفه أو null المدة الافتراضية المحدودة حتى 86400000 مللي ثانية. يجدد نفس صاحب الاعتماد والاستدعاء والحدث والمعلمات المعرف نفسه. عند تبديل المفاتيح يُوقّع بالمفتاحين لفترة قصيرة. انتهاء المدة أو سحب الوصول يوقف التسليم. لا تحتوي الحمولة على اعتماد Bearer أو إجابات البحث.

شحن الإجابات بمبلغ مخصص

أدخل ميزانية بعملة الفوترة واطّلع على عدد الإجابات الكاملة والمبلغ الدقيق قبل الدفع، بالسعر والحد الأدنى نفسيهما لأصغر حزمة جاهزة. تُضاف الإجابات المشتراة إلى الرصيد الحالي ويمكن اختيارها للشحن التلقائي المصرّح به صراحةً.

responseCredits.customTopUp.priceId → priceId; amountMinor = EUR/USD × 100.

إعدادات الشحن التلقائي

يعرض الكتالوج مساحة العمل الافتراضية بوضع prepaid حتى قبل أول دفعة. الاستخدام المشمول صفر؛ يضيف طلب الإجابات المدفوع الوحدات المشتراة. يُؤكد الإلغاء في إعدادات الفوترة ويسري في نهاية الفترة المدفوعة.

اقرأ كتالوج الفوترة الحالي قبل طلب الشحن التلقائي. استخدم kind: auto_recharge والسعر الأساسي من responseCredits.customTopUp، وأرسل الميزانية وعتبة الرصيد والحد الشهري بأعداد صحيحة من أصغر وحدات العملة. أرسل Idempotency-Key لتعيد المحاولات جلسة الموافقة نفسها. تتضمن الاستجابة رابط إعداد Stripe؛ ولا يبدأ الخصم التلقائي حتى يكمل مسؤول الفوترة الجلسة. قد يؤدي تغيير العملة إلى تعارض إذا بقيت دفعة تلقائية محجوزة.

{
  "kind": "auto_recharge",
  "priceId": "price_from_customTopUp",
  "amountMinor": 10000,
  "thresholdAmountMinor": 500,
  "monthlyAmountLimit": 19992
}

responseCredits.customTopUp.priceId → priceId; amountMinor, thresholdAmountMinor, monthlyAmountLimit = EUR/USD × 100; monthlyAmountLimit: "none".

POST /api/v1/billing/checkout + Idempotency-Key / start_billing_checkout + idempotencyKey → Stripe Checkout mode=setup.