---
title: "Minds API"
description: "أنشئ وأدِر AI minds برمجياً بتهيئات وشخصيات مخصصة."
---

# Minds API

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

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

## Get Mind

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

**Endpoint:** `GET /api/v1/minds/{mindId}`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Response

```json
{
  "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

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      المعرّف الفريد للـ mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      اسم الـ mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      وصف الـ mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        creative
      </code>
      
       أو <code>
        expert
      </code>
      
       أو <code>
        user
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      مجال الاختصاص
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        systemPrompt
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      الـ system prompt الكامل الذي يحدد سلوك الـ mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      وسوم التصنيف
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPublic
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      ما إذا كان الـ mind متاحاً للعامة
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isLinkSharingEnabled
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      ما إذا كانت مشاركة الروابط مفعَّلة
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        publicShareId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      معرّف المشاركة للوصول العام (null إذا لم يُشارَك)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profileImageUrl
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      URL صورة الـ avatar
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        phoneNumber
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      رقم الهاتف المرتبط (null إذا لا يوجد)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        clonedVoiceStatus
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      حالة استنساخ الصوت (null إذا لم يُستنسَخ)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profitSplitOptIn
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      ما إذا كان تقسيم الأرباح مفعَّلاً
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        knowledgeItemCount
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      عدد عناصر المعرفة المرفقة
    </td>
  </tr>
</tbody>
</table>

### Example Request

```bash
curl -X GET "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key"
```

### Error Responses

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

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

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

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

---

## List Minds

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

**Endpoint:** `GET /api/v1/minds`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Query Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        search
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      —
    </td>
    
    <td>
      تصفية الـ minds بالاسم أو الوصف أو الاختصاص (غير حساس لحالة الأحرف)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        limit
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      100
    </td>
    
    <td>
      الحد الأقصى لعدد الـ minds المُرجَعة (1–100)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        offset
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      0
    </td>
    
    <td>
      عدد الـ minds التي يجب تخطيها للترقيم
    </td>
  </tr>
</tbody>
</table>

### Response

```json
{
  "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

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      مصفوفة كائنات الـ mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.total
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      إجمالي عدد الـ minds المطابقة للاستعلام
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.limit
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      الحد الأقصى للنتائج في الصفحة
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.offset
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      عدد النتائج المتخطاة
    </td>
  </tr>
</tbody>
</table>

### Example Request

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

## Create Mind

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

**Endpoint:** `POST /api/v1/minds`

لإعادة المحاولة بأمان، أرسل الترويسة الاختيارية `X-Minds-Idempotency-Key` (من 1 إلى 128 حرفًا)، واستخدم المفتاح نفسه ومحتوى الطلب نفسه بعد انتهاء المهلة. تُربط المفاتيح بالمالك الذي تمت مصادقة هويته. ما دام الـMind الأصلي موجودًا، فإن إعادة استخدام مفتاحه تعيد ذلك الـMind بالحالة HTTP `200` حتى عند المحاولة لاحقًا، ولا تحدّثه. استخدم مفتاحًا جديدًا لإنشاء Mind آخر (HTTP `201`). تُرفض المفاتيح التي تتجاوز 128 حرفًا بالحالة `400` بدلًا من اقتطاعها.

تطبق مساحات العمل المُدارة أذونات الإنشاء الحالية على كل طلب، بما في ذلك إعادة المحاولة. تنتمي Minds الجديدة إلى مساحة العمل هذه. لا يمكن لمفتاح إعادة المحاولة إرجاع Mind من مساحة عمل مُدارة أخرى؛ يعيد هذا الطلب `404`. إذا كان الإنشاء معطلاً أو كانت مساحة العمل غير نشطة، يُعاد `403` قبل الإنشاء.

**Headers:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### Request Body

```json
{
  "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

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        نعم
      </strong>
    </td>
    
    <td>
      اسم الـ mind (2-100 حرفاً)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        نعم
      </strong>
    </td>
    
    <td>
      مجال اختصاص الـ mind (مثل "Marketing" أو "Engineering")
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mode
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      وضع التدريب: <code>
        keywords
      </code>
      
       أو <code>
        clone
      </code>
      
       أو <code>
        link
      </code>
      
       أو <code>
        manual
      </code>
      
      . الافتراضي: <code>
        keywords
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      نوع الـ mind: <code>
        creative
      </code>
      
       أو <code>
        expert
      </code>
      
       أو <code>
        user
      </code>
      
      . الافتراضي: <code>
        creative
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      وصف غرض الـ mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        keywords
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      مشروط
    </td>
    
    <td>
      مصفوفة كلمات مفتاحية (مطلوبة إذا كان <code>
        mode
      </code>
      
       هو <code>
        keywords
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        personaContext
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      مشروط
    </td>
    
    <td>
      اسم/سياق الشخص المُراد محاكاته (مطلوب إذا كان <code>
        mode
      </code>
      
       هو <code>
        clone
      </code>
      
      ؛ يُستخدم أيضاً لاشتقاق الكلمات المفتاحية تلقائياً)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contextLink
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      مشروط
    </td>
    
    <td>
      URL إلى الملف الشخصي/المحتوى (مطلوب إذا كان <code>
        mode
      </code>
      
       هو <code>
        link
      </code>
      
      ؛ يقوم الخادم بكشطه لاشتقاق الكلمات المفتاحية)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      مصفوفة وسوم للتصنيف (حد أقصى 20 وسماً)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profileImageUrl
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      URL خارجي لصورة الـ avatar (سيتم تنزيلها وتخزينها)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        generateImage
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      عند <code>
        true
      </code>
      
      ، يُفعِّل توليد صورة profile بالذكاء الاصطناعي في الخلفية
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cloneVoice
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      عند <code>
        true
      </code>
      
      ، يُفعِّل استنساخ الصوت عبر بحث YouTube (تجريبي)
    </td>
  </tr>
</tbody>
</table>

### قيم 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 Mind داخل المنتج — يشتق entity keywords (بمساعدة AI للـ `clone`/`link`) ويدرّب الـ mind بشكل غير متزامن. تابِع هذا التدريب عبر كتلة `training` في استجابة الإنشاء والـ endpoint المخصص الموضّح في **دورة حياة تدريب الـ mind** أدناه. وضع `manual` يتخطى هذه الأتمتة لتتمكن من تدريب الـ mind لاحقاً عبر Knowledge API.

### قيم Type

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

### Response

```json
{
  "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

```bash
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": "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

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -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

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -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

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -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/minds` المُعرّف `id` فوراً، لكن في أوضاع `keywords` و`clone` و`link` يظل الـ mind قيد التدريب في الخلفية. **وجود id للـ mind لا يعني أن الـ mind جاهز** — لا يستطيع الـ mind الرد إلا عندما تكون `readyToChat` بقيمة `true`. الاستثناء الوحيد هو وضع `manual`: تتخطى هذه minds جمع البيانات وتكون `completed` لحظة إنشائها.

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

```bash
curl "https://getminds.ai/api/v1/minds/{mindId}/training" \
  -H "Authorization: Bearer minds_your_api_key"
```

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

### قيم الحالة

<table>
<thead>
  <tr>
    <th>
      الحالة
    </th>
    
    <th>
      المعنى
    </th>
    
    <th>
      <code>
        readyToChat
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        queued
      </code>
    </td>
    
    <td>
      التدريب في قائمة الانتظار لكنه لم يبدأ بعد.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        running
      </code>
    </td>
    
    <td>
      الـ mind يجمع المعرفة بنشاط ويبني شخصيته (persona).
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        completed
      </code>
    </td>
    
    <td>
      انتهى التدريب. الـ mind جاهز للمحادثة.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        failed
      </code>
    </td>
    
    <td>
      لم يكتمل التدريب. افحص <code>
        error
      </code>
      
       وأعد التدريب إذا كان قابلاً لإعادة المحاولة.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

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

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

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

<table>
<thead>
  <tr>
    <th>
      رمز الخطأ
    </th>
    
    <th>
      المعنى
    </th>
    
    <th>
      <code>
        retryable
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        COLLECTION_FAILED
      </code>
    </td>
    
    <td>
      تعذّر إكمال جمع المعرفة.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PROFILE_GEN_FAILED
      </code>
    </td>
    
    <td>
      تعذّر توليد ملف الشخصية (persona).
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TIMEOUT
      </code>
    </td>
    
    <td>
      تجاوز التدريب ميزانيته الزمنية فتوقّف.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        INTERNAL
      </code>
    </td>
    
    <td>
      حدث خطأ داخلي غير متوقع.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

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

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

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/retrain" \
  -H "Authorization: Bearer minds_your_api_key"
```

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

## صور Profile

عندما تقدم `profileImageUrl`:

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

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

يتطلب تنزيل الصور الخارجية عنوان HTTP(S) عاماً لصورة نقطية. تُرفض عناوين الشبكات الخاصة، بما فيها أهداف إعادة التوجيه، ومحتويات SVG. يقتصر التنزيل على 50 MiB و30 ثانية. إذا فشل التنزيل أو التخزين، يُنشأ Mind باستخدام العنوان الأصلي؛ إرجاع عنوان URL لا يثبت أن الصورة خُزنت.

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

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

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

يمكنك تعزيز الـ mind أكثر عبر [رفع المعرفة](/docs/api/knowledge) بعد الإنشاء.

## حدود الباقات

راجع [جدول حدود الباقات المُنشأ](/docs/api/overview) للاطلاع على القيم العامة الحالية. قد تختلف التجاوزات التعاقدية، وعلى عمليات التكامل استخدام `data.limit` و`data.current` من استجابة `PLAN_LIMIT` مصادق عليها. تظهر باقة Individual باسم `"premium"` في حمولات API.

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

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

## Error Responses

### 400 Bad Request

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

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

### 401 Unauthorized

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

### 403 Forbidden

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

### 500 Internal Server Error

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

## Update Mind

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

**Endpoint:** `PUT /api/v1/minds/{mindId}`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### Request Body

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

### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      اسم الـ mind (2-100 حرفاً)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      وصف غرض الـ mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      النوع: <code>
        creative
      </code>
      
       أو <code>
        expert
      </code>
      
       أو <code>
        user
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      مجال اختصاص الـ mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        systemPrompt
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      system prompt مخصص يحدد سلوك الـ mind وشخصيته
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      مصفوفة وسوم للتصنيف (حد أقصى 20 وسماً)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPublic
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      لا
    </td>
    
    <td>
      ما إذا كان الـ mind متاحاً للعامة
    </td>
  </tr>
</tbody>
</table>

### System Prompt

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

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

**أمثلة system prompts:**

```text
# 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.
```

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

### Response

```json
{
  "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

```bash
curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}" \
  -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

```bash
curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}" \
  -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 Mind Knowledge Patterns

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

**Endpoint:** `GET /api/v1/minds/{mindId}/knowledge/patterns`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

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

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

```json
{
  "success": true,
  "data": {
    "mindId": "550e8400-e29b-41d4-a716-446655440000",
    "mindName": "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": [
                  {
                    "mind": "Market segmentation requires understanding customer pain points and aligning product features with specific needs...",
                    "portfolioItemId": "abc-123",
                    "createdAt": "2025-12-10T15:30:00.000Z"
                  },
                  {
                    "mind": "Competitive analysis shows that timing and positioning are critical for market entry...",
                    "portfolioItemId": "def-456",
                    "createdAt": "2025-12-10T14:20:00.000Z"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}
```

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

- **frameworks**: مصفوفة الأطر التي تحتوي على أنماط الـ mind

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

### Example Request

```bash
curl -X GET "https://getminds.ai/api/v1/minds/{mindId}/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 لـ mind مستخدماً قاعدة معرفته الحالية. يستخدم هذا نفس التوليد المدعوم بالذكاء الاصطناعي الذي يستخدمه زر "Generate All" في الواجهة.

**Endpoint:** `POST /api/v1/minds/{mindId}/regenerate-prompt`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### كيف يعمل

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

لـ minds من نوع **user**:

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

لـ minds من نوع **expert**:

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

لـ minds من نوع **creative**:

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

### Response

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

### Example Request

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/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 Mind

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

**Endpoint:** `DELETE /api/v1/minds/{mindId}`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Response

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

### Example Request

```bash
curl -X DELETE "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key"
```

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

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

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

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

### Error Responses

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

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

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

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

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

- [ارفع المعرفة إلى الـ mind الخاص بك](/docs/api/knowledge)
- [تحدَّث مع الـ mind الخاص بك](/docs/api/chat)
- تعرّف على [الأخطاء والحدود](/docs/api/errors)