---
title: "Knowledge API"
description: "أضف المعرفة إلى الـ minds الخاصة بك من خلال الملفات أو الكلمات المفتاحية أو الروابط."
---

# Knowledge API

تدير هذه الواجهة المعرفة الخاصة بالـ mind داخل Minds.

أضف المعرفة إلى الـ minds الخاصة بك عبر ثلاث طرق: **File** أو **Keyword** أو **Link**. تُعالج المعرفة وتُضمَّن ويتم استرجاعها تلقائياً أثناء المحادثات.

**ملاحظة:** عمليات العرض والإضافة والحذف متاحة عبر v1 API. يتم أيضاً دعم إثراء المعرفة عبر البحث بالكلمات المفتاحية من خلال نفس endpoint الإضافة.

---

## List Knowledge Items

استرجع جميع عناصر المعرفة لـ mind.

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

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

**مثال:**

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

**الاستجابة:**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "description": "Company Employee Handbook 2025",
        "link": null,
        "filePath": "portfolio/user-id/1234567890_handbook.pdf",
        "isWatched": false,
        "createdAt": "2025-12-10T12:00:00.000Z",
        "updatedAt": "2025-12-10T12:00:00.000Z"
      }
    ],
    "total": 1
  }
}
```

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

<tbody>
  <tr>
    <td>
      <code>
        data.items
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      مصفوفة من كائنات عناصر المعرفة
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.total
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      العدد الإجمالي لعناصر المعرفة لهذا الـ mind
    </td>
  </tr>
</tbody>
</table>

---

## File Upload

ارفع المستندات أو الصور مباشرة إلى mind.

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

**Content-Type:** `multipart/form-data`

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

<tbody>
  <tr>
    <td>
      <code>
        file
      </code>
    </td>
    
    <td>
      file
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      الملف المراد رفعه (حد أقصى 50MB)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      وصف المحتوى
    </td>
  </tr>
</tbody>
</table>

**الصيغ المدعومة:**

- المستندات: PDF, DOCX, DOC, TXT, MD, RTF, CSV, JSON, XML
- الصور: JPG, JPEG, PNG, GIF, WEBP

**مثال:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -F "file=@./handbook.pdf" \
  -F "description=Company Employee Handbook 2025"
```

**الاستجابة:** `201 Created`

```json
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Company Employee Handbook 2025",
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "createdAt": "2025-12-10T12:00:00.000Z"
  }
}
```

---

## Keyword Search

أضف المعرفة بالبحث على الإنترنت عن كلمات مفتاحية. يبحث في Exa وYouTube، يستخرج المحتوى، ويضيفه إلى قاعدة معرفة الـ mind.

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

**Content-Type:** `application/json`

أرسل جسم JSON يحتوي على مصفوفة `keywords` (بدلاً من `link`/`file`) لتشغيل إثراء البحث على الإنترنت.

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

<tbody>
  <tr>
    <td>
      <code>
        keywords
      </code>
    </td>
    
    <td>
      string<span>
        
      </span>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      كلمات مفتاحية للبحث (حد أقصى 35)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        regeneratePrompt
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      No
    </td>
    
    <td>
      إعادة توليد نظام البرومبت بعد ذلك (الافتراضي: true)
    </td>
  </tr>
</tbody>
</table>

**مثال:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'
```

**الاستجابة:** `202 Accepted`

```json
{
  "success": true,
  "data": {
    "sparkId": "660e8400-e29b-41d4-a716-446655440000",
    "keywords": ["solar panel efficiency", "photovoltaic trends"],
    "queued": true,
    "regeneratePrompt": true,
    "message": "Knowledge enrichment queued with 2 keyword(s)."
  }
}
```

**ملاحظة:** هذا غير متزامن. تجري المعالجة في الخلفية وقد تستغرق عدة دقائق.

---

## Link

أضف المعرفة من URL. يدعم صفحات الويب وفيديوهات YouTube والأوراق البحثية.

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

**Content-Type:** `application/json`

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

<tbody>
  <tr>
    <td>
      <code>
        link
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      URL لمحتوى الويب
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      وصف المحتوى
    </td>
  </tr>
</tbody>
</table>

**مثال:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"link": "https://example.com/article", "description": "Industry trends article"}'
```

**الاستجابة:** `201 Created`

```json
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "link": "https://example.com/article",
    "description": "Industry trends article",
    "createdAt": "2025-12-10T12:00:00.000Z"
  }
}
```

**أنواع الروابط المدعومة:**

- صفحات الويب (يُستخرج المحتوى عبر الكشط)
- فيديوهات YouTube (تُستخرج النصوص تلقائياً)
- الأوراق البحثية (arxiv، إلخ)

---

## Watch (التحديث التلقائي)

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

تتم إدارة المراقبة من خلال واجهة المستخدم في المنتج. حالة المراقبة مرئية عند عرض عناصر المعرفة عبر API (حقل `isWatched`).

**ملاحظة:** المراقبة متاحة فقط للمعرفة المبنية على روابط، وليس الملفات أو عمليات البحث بالكلمات المفتاحية.

---

## Update Knowledge Item

حدّث وصف عنصر معرفة موجود.

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

**Headers:**

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

**جسم الطلب:**

```json
{
  "description": "Updated description for this knowledge item"
}
```

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

<tbody>
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      الوصف المحدث (يجب ألا يكون فارغاً)
    </td>
  </tr>
</tbody>
</table>

**مثال:**

```bash
curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}/knowledge/{itemId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated handbook description"}'
```

**الاستجابة:**

```json
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Updated handbook description",
    "link": null,
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "isWatched": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-15T08:30:00.000Z"
  }
}
```

### استجابات الخطأ

**400 Bad Request** — لا توجد حقول صالحة للتحديث أو وصف فارغ

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

**404 Not Found** — عنصر المعرفة أو الـ mind غير موجود

---

## Enrich via Keywords (اختصار)

اختصار مريح لإثراء المعرفة بناءً على الكلمات المفتاحية.

**Endpoint:** `POST /api/v1/minds/{mindId}/knowledge/enrich`

هذا مكافئ لـ `POST /api/v1/minds/{mindId}/knowledge` مع جسم `keywords`. راجع [Keyword Search](#keyword-search) للتفاصيل الكاملة.

**مثال:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge/enrich" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'
```

---

## Delete Knowledge Item

احذف عنصر معرفة وجميع البيانات المرتبطة به (embeddings، patterns، files) بشكل دائم.

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

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

**مثال:**

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

**الاستجابة:** `204 No Content` (جسم فارغ عند النجاح)

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

- سجل عنصر المعرفة
- جميع vector embeddings المرتبطة
- جميع الـ patterns المرتبطة
- الملف المرفوع من التخزين (إذا كان قائماً على ملف)

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

---

## كيف تعمل المعالجة

1. **الرفع** — يُخزَّن المحتوى ويُرجع API نجاحاً
2. **الاستخراج** — تستخرج المعالجة في الخلفية النص (الكشط، النصوص، OCR، الرؤية)
3. **التضمين** — يُحوَّل المحتوى إلى vector embeddings
4. **الاسترجاع** — أثناء المحادثة، تُسترجع المعرفة ذات الصلة تلقائياً عبر البحث الدلالي

---

## الأخطاء

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Message
    </th>
    
    <th>
      Cause
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        Link and description are required
      </code>
    </td>
    
    <td>
      حقول مطلوبة مفقودة
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        Keywords array is required
      </code>
    </td>
    
    <td>
      كلمات مفتاحية فارغة أو مفقودة
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        File too large
      </code>
    </td>
    
    <td>
      الملف يتجاوز حد 50MB
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        Can only watch link-based knowledge
      </code>
    </td>
    
    <td>
      محاولة مراقبة ملف
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      <code>
        Mind not found or access denied
      </code>
    </td>
    
    <td>
      معرّف Mind غير صالح أو لا يوجد وصول
    </td>
  </tr>
  
  <tr>
    <td>
      415
    </td>
    
    <td>
      <code>
        Unsupported Content-Type
      </code>
    </td>
    
    <td>
      ترويسة Content-Type خاطئة
    </td>
  </tr>
</tbody>
</table>

---

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

- [المحادثة مع mind الخاص بك](/docs/api/chat)
- [إنشاء minds](/docs/api/minds)
- [أخطاء وحدود API](/docs/api/errors)