Sparks API

أنشئ وأدِر AI minds (agents) برمجياً. الـ Minds هي مساعدات ذكاء اصطناعي قابلة للتخصيص ذات اختصاصات وشخصيات ومعارف محددة.

Base URL: https://getminds.ai/api/v1 أو https://api.getminds.ai/v1

Get Spark

استرجع mind واحداً بكامل التفاصيل بما في ذلك system prompt وإعدادات المشاركة وعدد عناصر المعرفة.

Endpoint: GET /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Expert",
    "description": "Experienced marketing director",
    "type": "expert",
    "discipline": "Marketing",
    "systemPrompt": "## Core Identity & Personality\n\nYou are a seasoned marketing director...",
    "tags": ["marketing", "b2b"],
    "isPublic": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null,
    "profileImageUrl": "https://...",
    "phoneNumber": null,
    "clonedVoiceStatus": null,
    "profitSplitOptIn": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z",
    "knowledgeItemCount": 12
  }
}

Response Fields

Example Request

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

Error Responses

400 Bad Request - صيغة معرّف spark غير صالحة

401 Unauthorized - مفتاح API غير صالح أو مفقود

403 Forbidden - لا وصول إلى هذا الـ mind

404 Not Found - الـ mind غير موجود

List Sparks

استرجع جميع الـ minds التابعة للمستخدم المصادَق.

Endpoint: GET /api/v1/sparks

Headers:

Authorization: Bearer minds_your_api_key

Query Parameters

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Expert",
      "description": "Experienced marketing director",
      "type": "expert",
      "discipline": "Marketing",
      "tags": ["marketing", "b2b"],
      "profileImageUrl": "https://...",
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 100,
    "offset": 0
  }
}

Response Fields

Example Request

curl -X GET "https://getminds.ai/api/v1/sparks?limit=10&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"

Create Spark

أنشئ AI mind جديداً بتهيئة مخصصة مستخدماً أوضاع تدريب مختلفة.

Endpoint: POST /api/v1/sparks

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

{
  "name": "My AI Expert",
  "description": "An expert in renewable energy",
  "mode": "keywords",
  "type": "expert",
  "discipline": "Renewable Energy",
  "keywords": ["solar", "wind energy", "sustainability", "green tech"],
  "personaContext": "Ada Lovelace, pioneering computer scientist",
  "contextLink": "https://example.com/profile",
  "tags": ["energy", "solar", "sustainability"],
  "profileImageUrl": "https://example.com/avatar.jpg"
}

Parameters

قيم Mode

يحدد مُعامل mode كيف سيُدرَّب الـ mind:

• keywords (الافتراضي) - درِّب الـ mind مستخدماً كلمات مفتاحية مفصولة بفواصل. سيجمع الذكاء الاصطناعي معلومات ذات صلة من مصادر متنوعة بناءً على هذه الكلمات المفتاحية لبناء قاعدة معرفة الـ mind.
  • الحقل المطلوب: keywords - مصفوفة كلمات مفتاحية/موضوعات
  • الأنسب لـ: الاختصاص العام في موضوعات أو نطاقات محددة
• clone - استنسخ أسلوب ومعرفة شخص بتقديم اسمه وسياقه. سيبحث الذكاء الاصطناعي ويبني ملفاً شاملاً يحاكي اختصاصه وأسلوب تواصله.
  • الحقل المطلوب: personaContext - الاسم وسياق موجز (مثل "Ada Lovelace, pioneering computer scientist")
  • الأنسب لـ: محاكاة أفراد محددين أو شخصيات تاريخية أو خبراء معروفين
• link - درِّب الـ mind مستخدماً محتوى من URL محدد. قدِّم رابطاً لملف شخصي أو portfolio أو موقع ويب، وسيُحلل الذكاء الاصطناعي ويستخرج المعلومات ذات الصلة.
  • الحقل المطلوب: contextLink - URL إلى مصدر المحتوى
  • الأنسب لـ: التدريب على مواقع محددة أو portfolios أو ملفات شخصية على الإنترنت
• manual - أنشئ mind بدون تدريب تلقائي. ستقوم يدوياً بتهيئة جميع الإعدادات وإضافة المعرفة لاحقاً عبر knowledge API.
  • لا حقول إضافية مطلوبة
  • الأنسب لـ: التهيئات المخصصة عندما تريد تحكماً كاملاً في بيانات التدريب

معالجة تلقائية: عند استخدام keywords أو clone أو link، يعكس الـ backend نموذج Add Spark داخل المنتج — يشتق entity keywords (بمساعدة AI للـ clone/link) ويدرّب الـ mind بشكل غير متزامن. تابِع هذا التدريب عبر كتلة training في استجابة الإنشاء والـ endpoint المخصص الموضّح في دورة حياة تدريب الـ mind أدناه. وضع manual يتخطى هذه الأتمتة لتتمكن من تدريب الـ mind لاحقاً عبر Knowledge API.

قيم Type

• creative - للفنانين والمصممين والكتّاب والمحترفين الإبداعيين
• expert - للمتخصصين والمستشارين وخبراء النطاقات
• user - لـ user personas والعملاء والنماذج الأصلية للجمهور المستهدف

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My AI Expert",
    "description": "An expert in renewable energy",
    "type": "expert",
    "discipline": "Renewable Energy",
    "tags": ["energy", "solar", "sustainability"],
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z"
  },
  "training": {
    "status": "queued",
    "readyToChat": false,
    "message": "Queued for data collection",
    "startedAt": null,
    "completedAt": null,
    "error": null
  }
}

تُبلِّغ كتلة training عن دورة حياة الـ mind عند الإنشاء. تبدأ أوضاع keywords وclone وlink بحالة queued وتتدرّب في الخلفية؛ أما minds وضع manual فتعود بحالة completed مع readyToChat مضبوطة على true بالفعل. يوجد id الـ mind بمجرد عودة هذا الطلب، لكن لا يستطيع الـ mind الرد إلا عندما تكون readyToChat بقيمة true. راجع دورة حياة تدريب الـ mind أدناه لمعرفة كيفية الاستقصاء.

Example: Create Mind with Keywords Mode

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Experienced marketing director with expertise in B2B SaaS",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["B2B marketing", "SaaS", "growth marketing", "content strategy", "brand positioning", "ROI"],
    "tags": ["marketing", "b2b", "saas", "growth"]
  }'

Example: Create Mind with Clone Mode

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace AI",
    "description": "AI trained to emulate Ada Lovelace",
    "mode": "clone",
    "type": "expert",
    "discipline": "Computer Science Pioneer",
    "personaContext": "Ada Lovelace, pioneering computer scientist and mathematician, first computer programmer",
    "tags": ["computer science", "mathematics", "history"]
  }'

Example: Create Mind with Link Mode

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Voice Expert",
    "description": "Trained on company brand guidelines",
    "mode": "link",
    "type": "creative",
    "discipline": "Brand Strategy",
    "contextLink": "https://example.com/brand-guidelines",
    "tags": ["branding", "copywriting"]
  }'

Example: Create Mind with Manual Mode

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Assistant",
    "description": "Custom configured assistant",
    "mode": "manual",
    "type": "creative",
    "discipline": "General Assistant",
    "tags": ["custom"]
  }'

دورة حياة تدريب الـ mind

إنشاء الـ mind غير متزامن. يُرجِع POST /v1/sparks المُعرّف id فوراً، لكن في أوضاع keywords وclone وlink يظل الـ mind قيد التدريب في الخلفية. وجود id للـ mind لا يعني أن الـ mind جاهز — لا يستطيع الـ mind الرد إلا عندما تكون readyToChat بقيمة true. الاستثناء الوحيد هو وضع manual: تتخطى هذه minds جمع البيانات وتكون completed لحظة إنشائها.

استقصِ endpoint التدريب المخصص حتى يصبح الـ mind جاهزاً:

curl "https://getminds.ai/api/v1/sparks/{sparkId}/training" \
  -H "Authorization: Bearer minds_your_api_key"

{
  "status": "running",
  "readyToChat": false,
  "message": "Collecting knowledge...",
  "startedAt": "2025-12-10T12:00:01.000Z",
  "completedAt": null,
  "error": null
}

قيم الحالة

يُرجِع GET /v1/sparks/{id} أيضاً readyToChat (وtrainingStatus) مع بقية بيانات الـ mind، بحيث تخبرك قراءة واحدة بمن يكون الـ mind وهل يستطيع الرد بعد.

عند فشل التدريب

عندما تكون status بقيمة failed، تتضمن الاستجابة كائن error يحتوي على code وعلم retryable:

إعادة التدريب

إذا انتهى الـ mind بحالة failed (أو أردت ببساطة إعادة بناء mind بحالة completed)، أعِد تدريبه:

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/retrain" \
  -H "Authorization: Bearer minds_your_api_key"

يؤدي هذا إلى إعادة وضع الـ mind في قائمة الانتظار وإرجاع كتلة training جديدة مع status بقيمة queued. تعمل إعادة التدريب فقط على minds التي انتهت: الـ mind الذي ما زال queued أو running يُرجِع 409 Conflict لأن هناك جولة تدريب جارية بالفعل. بعد إعادة التدريب، استقصِ GET /v1/sparks/{id}/training مرة أخرى حتى تصبح readyToChat بقيمة true.

صور Profile

عندما تقدم profileImageUrl:

1. تُنزَّل الصورة من الـ URL الخارجي
2. تُرفَع إلى تخزين آمن
3. يُرجَع الـ URL المُخزَّن في الاستجابة

الصيغ المدعومة: JPG، PNG، GIF، WEBP

كيف يعمل التدريب

يُولِّد النظام تلقائياً system prompt ذكياً بناءً على الوضع والنوع والاختصاص الذي اخترته:

• وضع Keywords: يبني اختصاصاً حول الكلمات المفتاحية المُحددة
• وضع Clone: يبني ملفاً يحاكي أسلوب ومعرفة الشخص المحدد
• وضع Link: يستخرج المعرفة من الـ URL المُقدَّم
• وضع Manual: ينشئ مساعداً أساسياً ستدرِّبه بمعرفة مخصصة

يمكنك تعزيز الـ mind أكثر عبر رفع المعرفة بعد الإنشاء.

حدود الباقات

للباقات المختلفة حدود إنشاء minds مختلفة:

عند الوصول إلى الحد، ستتلقى خطأ 403 Forbidden:

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

Error Responses

400 Bad Request

مُعاملات مفقودة أو غير صالحة.

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

401 Unauthorized

مفتاح API غير صالح أو مفقود.

403 Forbidden

تم الوصول إلى حد الباقة.

500 Internal Server Error

خطأ من جهة الخادم (نادر).

Update Spark

حدِّث تهيئة mind موجود، بما في ذلك الاسم والوصف والـ system prompt والإعدادات الأخرى.

Endpoint: PUT /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

{
  "name": "Updated Name",
  "description": "Updated description",
  "type": "expert",
  "discipline": "Updated Discipline",
  "systemPrompt": "Custom system prompt instructions...",
  "tags": ["tag1", "tag2"],
  "isPublic": false
}

Parameters

System Prompt

يتيح لك حقل systemPrompt تخصيص كيف يتصرف الـ mind ويستجيب. هذا مفيد لـ:

• تخصيص الـ persona: تحديد سمات شخصية محددة أو أسلوب تواصل أو مجالات اختصاص
• تنسيق الاستجابة: توجيه الـ mind للاستجابة بصيغ محددة (مثل القوائم النقطية أو المرقمة)
• قيود النطاق: حصر الاستجابات في موضوعات أو منظورات محددة
• اللغة/النبرة: تحديد اللغة أو مستوى الرسمية أو نبرة الاستجابات

أمثلة system prompts:

# Survey Response Expert
Du bist ein erfahrener Handwerker. Bei Umfragen antworte immer aus deiner
persönlichen Erfahrung, nicht mit allgemeinen Branchendurchschnittswerten.
Wähle bei Multiple-Choice-Fragen immer genau eine Option.

# Technical Expert
You are a senior software architect. Always provide concrete,
actionable advice. Include code examples when relevant.
Avoid vague statements.

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Name",
    "description": "Updated description",
    "type": "expert",
    "discipline": "Updated Discipline",
    "systemPrompt": "Custom system prompt...",
    "tags": ["tag1", "tag2"],
    "isPublic": false,
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-29T15:30:00.000Z"
  }
}

Example: Update System Prompt

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "Du bist ein erfahrener Handwerker im Sanitärbereich. Antworte immer aus deiner persönlichen Praxiserfahrung."
  }'

Example: Update Multiple Fields

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Plumber Expert",
    "description": "Expert plumber with 20 years of experience",
    "discipline": "Plumbing & Sanitary Installation",
    "tags": ["plumbing", "sanitary", "renovation"]
  }'

Error Responses

400 Bad Request - لا حقول صالحة للتحديث أو قيم حقول غير صالحة

401 Unauthorized - مفتاح API غير صالح أو مفقود

403 Forbidden - لا صلاحية لتحديث هذا الـ mind (يجب أن تكون المالك)

404 Not Found - الـ mind غير موجود

Get Spark Knowledge Patterns

استرجع أنماط التفكير والمعرفة المُنظَّمة حسب الإطار لـ mind محدد.

Endpoint: GET /api/v1/sparks/{sparkId}/knowledge/patterns

Headers:

Authorization: Bearer minds_your_api_key

بنية الاستجابة

يُرجع الـ endpoint أنماطاً مُجمَّعة حسب الأطر (مثل AOX Internal، OCEAN، DISC، إلخ)، مع methods وcompetencies تُظهر التكرارات والأدلة.

{
  "success": true,
  "data": {
    "sparkId": "550e8400-e29b-41d4-a716-446655440000",
    "sparkName": "Marketing Expert",
    "totalPatterns": 47,
    "frameworks": [
      {
        "id": "aox-internal",
        "name": "AOX Internal Framework",
        "totalOccurrences": 32,
        "methods": [
          {
            "id": "strategic-thinking",
            "name": "Strategic Thinking",
            "description": "Ability to think strategically and plan long-term",
            "occurrences": 15,
            "competencies": [
              {
                "id": "market-analysis",
                "name": "Market Analysis",
                "description": "Understanding market dynamics and trends",
                "occurrences": 8,
                "evidence": [
                  {
                    "spark": "Market segmentation requires understanding customer pain points and aligning product features with specific needs...",
                    "portfolioItemId": "abc-123",
                    "createdAt": "2025-12-10T15:30:00.000Z"
                  },
                  {
                    "spark": "Competitive analysis shows that timing and positioning are critical for market entry...",
                    "portfolioItemId": "def-456",
                    "createdAt": "2025-12-10T14:20:00.000Z"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

فهم الاستجابة

• frameworks: مصفوفة الأطر التي تحتوي على أنماط الـ spark
  • totalOccurrences: إجمالي عدد الأنماط في هذا الإطار
  • methods: أساليب أو مناهج التفكير المُكتشفة
    • occurrences: عدد مرات ظهور هذا الـ method
    • competencies: مهارات محددة أو مجالات فرعية ضمن الـ method
      • occurrences: عدد أنماط هذا الـ competency
      • evidence: مصفوفة الاستشهادات/الاقتباسات المُثبِتة لهذا النمط
        • spark: الاقتباس الفعلي أو الرؤية من المحتوى
        • portfolioItemId: إشارة إلى المادة المصدر
        • createdAt: متى تم تحديد هذا النمط

Example Request

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}/knowledge/patterns" \
  -H "Authorization: Bearer minds_your_api_key"

حالات الاستخدام

• فهم اختصاص الـ mind: اطّلع على الـ methods والـ competencies التي تعلَّمها الـ mind
• ضمان الجودة: تحقق من استخراج الأنماط بشكل صحيح من بيانات التدريب
• فجوات المعرفة: حدِّد المجالات التي تحتاج إلى مزيد من بيانات التدريب
• مقارنة الأطر: قارن كيف يؤدي الـ mind عبر أطر مختلفة

Error Responses

401 Unauthorized - مفتاح API غير صالح أو مفقود

403 Forbidden - لا وصول إلى هذا الـ mind

404 Not Found - الـ mind غير موجود

Regenerate System Prompt

أعد توليد جميع مكونات الـ system prompt لـ spark مستخدماً قاعدة معرفته الحالية. يستخدم هذا نفس التوليد المدعوم بالذكاء الاصطناعي الذي يستخدمه زر "Generate All" في الواجهة.

Endpoint: POST /api/v1/sparks/{sparkId}/regenerate-prompt

Headers:

Authorization: Bearer minds_your_api_key

كيف يعمل

يحلل الـ endpoint قاعدة معرفة الـ mind (portfolio items، patterns، embeddings) ويُولِّد جميع مكونات الـ prompt:

لـ sparks من نوع user:

• Core Identity & Demographics
• Needs & Motivations
• Pain Points & Challenges
• Tone & Communication Style
• Goals & Desires
• Behavioral Patterns

لـ sparks من نوع expert:

• Core Identity & Personality
• Professional Expertise & Credentials
• Tone & Communication Style
• Professional Approach & Methods
• Domain Knowledge

لـ sparks من نوع creative:

• Core Identity & Personality
• Creative Philosophy & Values
• Tone & Communication Style
• Creative Approach & Methods
• Domain Expertise

Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Spark",
    "systemPrompt": "## Core Identity & Demographics\n\n...",
    "promptLength": 2847
  }
}

Example Request

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/regenerate-prompt" \
  -H "Authorization: Bearer minds_your_api_key"

حالات الاستخدام

• بعد إضافة معرفة: أعد توليد الـ prompt ليشمل عناصر المعرفة المُضافة حديثاً
• تنقيح الـ persona: أعد التوليد لتحديث الـ persona بناءً على أنماط المعرفة الحالية
• إعادة ضبط التخصيصات: امحُ التعديلات اليدوية وأعد توليد prompts جديدة من قاعدة المعرفة

Error Responses

401 Unauthorized - مفتاح API غير صالح أو مفقود

403 Forbidden - لا صلاحية لتعديل هذا الـ mind (يجب أن تكون المالك)

404 Not Found - الـ mind غير موجود

500 Internal Server Error - فشل توليد الـ prompt (مثل معرفة غير كافية)

Delete Spark

احذف mind نهائياً وكل البيانات المرتبطة بما فيها المعرفة وعناصر portfolio والملفات.

Endpoint: DELETE /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key

Response

يُرجع 204 No Content بجسم فارغ عند النجاح.

Example Request

curl -X DELETE "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

ما الذي يُحذَف

عند حذف mind، تُحذَف التالي نهائياً:

• الـ mind نفسه وجميع تهيئاته
• كل المعرفة وبيانات التدريب
• كل عناصر الـ portfolio والملفات المرتبطة
• كل سجل المحادثات والرسائل
• صور الـ profile والملفات المرفوعة

تحذير: لا يمكن التراجع عن هذا الإجراء.

Error Responses

400 Bad Request - صيغة معرّف spark غير صالحة

401 Unauthorized - مفتاح API غير صالح أو مفقود

403 Forbidden - لا صلاحية لحذف هذا الـ mind (يجب أن تكون المالك)

404 Not Found - الـ mind غير موجود

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

• ارفع المعرفة إلى الـ mind الخاص بك
• تحدَّث مع الـ mind الخاص بك
• تعرّف على الأخطاء والحدود