---
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`

**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

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

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

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

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

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

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

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

```json
{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual 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 الخاص بك](/api/knowledge)
- [تحدَّث مع الـ mind الخاص بك](/api/chat)
- تعرّف على [الأخطاء والحدود](/api/errors)