Knowledge API

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

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

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

List Knowledge Items

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

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

Headers:

Authorization: Bearer minds_your_api_key

مثال:

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

الاستجابة:

{
  "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
  }
}

File Upload

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

Endpoint: POST /api/v1/sparks/{sparkId}/knowledge

Content-Type: multipart/form-data

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

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

مثال:

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

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

{
  "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/sparks/{sparkId}/knowledge

Content-Type: application/json

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

مثال:

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

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

{
  "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/sparks/{sparkId}/knowledge

Content-Type: application/json

مثال:

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/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

{
  "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/sparks/{sparkId}/knowledge/{itemId}

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

جسم الطلب:

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

مثال:

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

الاستجابة:

{
  "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/sparks/{sparkId}/knowledge/enrich

هذا مكافئ لـ POST /api/v1/sparks/{sparkId}/knowledge مع جسم keywords. راجع Keyword Search للتفاصيل الكاملة.

مثال:

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/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/sparks/{sparkId}/knowledge/{itemId}

Headers:

Authorization: Bearer minds_your_api_key

مثال:

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

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

ما الذي يُحذف

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

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

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

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

الأخطاء

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

• المحادثة مع mind الخاص بك
• إنشاء minds
• أخطاء وحدود API