Chat API

أرسل رسائل إلى الـ minds الخاصة بك واستقبل ردوداً مولّدة بالذكاء الاصطناعي. يدعم Chat API كلاً من الإكمالات عديمة الحالة (stateless) والحوارات متعددة الأدوار ذات الحالة (stateful) مع إدارة تلقائية لسجل الرسائل.

المحادثات ذات الحالة (موصى بها)

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

إنشاء محادثة

أنشئ محادثة جديدة ذات حالة مرتبطة بأحد الـ minds.

Endpoint: POST /api/v1/chats

اختر تحديدًا واحدًا غير فارغ فقط: mindId أو mindIds أو audienceIds. الجمع بينها يعيد 400؛ المصفوفة الاختيارية الفارغة لا تلغي تحديد Mind واحد. لا تؤثر حالة الأحرف في UUID وتُتجاهل المعرّفات المكررة. يقبل إنشاء المحادثة حتى 1 MiB من JSON بما في ذلك محارف الهروب؛ الطلب الأكبر يعيد 413 قبل عمليات قاعدة البيانات أو التحقق من استحقاقات الخطة. الاستجابات خاصة ولا تُخزّن مؤقتًا.

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

جسم الطلب:

{
  "name": "My Conversation",
  "mindId": "your-mind-id"
}

الاستجابة (201):

{
  "data": {
    "id": "601af953-3837-49c1-a31e-4fdbfa82ac04",
    "name": "My Conversation",
    "description": null,
    "createdAt": "2026-04-04T12:45:24.078Z",
    "minds": [
      {
        "id": "4774888e-0a03-40d7-979b-39b47c4c049c",
        "name": "Ada Lovelace",
        "discipline": "mathematician and computer scientist"
      }
    ]
  }
}

إرسال رسالة

أرسل رسالة إلى محادثة قائمة. يتعامل الخادم تلقائياً مع سجل المحادثة وضغط نافذة السياق والملخصات المتحركة.

Endpoint: POST /api/v1/chats/{chatId}/messages

تلتزم المحادثات مع Mind واحد أو عدة Minds بسياسة knowledge_only المحفوظة لكل Mind وبقيود البحث عبر الويب في مساحة العمل. يستخدم Mind المقيّد السؤال الحالي وشخصيته المدرّبة ومعرفة Mind ذات الصلة التي جرى استرجاعها؛ وتُستبعد الأدوات الداخلية وأدوات العميل وسياق المحادثة السابق ومصادر Study المنسوخة من سياق إجابته. تعرض الإجابة metadata.knowledgeRetrieval.status بقيمة grounded عند استرجاع أدلة ذات صلة، أو fallback عند عدم توفرها أو فشل الاسترجاع. وتعرض الردود متعددة Minds هذه الحالة بشكل منفصل في metadata لكل عنصر ضمن messages[].

إذن البحث عبر الويب في مساحة العمل مستقل عن knowledge_only: يؤدي تعطيله إلى إزالة أدوات البحث عبر الويب وتحليل الروابط، مع الاحتفاظ بالمواد المقدّمة وسجل المحادثة لدى Minds التي تستخدم auto. ينطبق سياق الإجابة المقيّد الموضح أعلاه على Minds التي تستخدم knowledge_only.

تستأنف الذاكرة المتجددة بعد معرّف آخر رسالة شملها الملخص، بدلًا من موضع قد يتغير عند تعديل سياق Study المنسوخ. تُستبعد صفوف الملخصات المولّدة من أدوار المحادثة، وتظل ملاحظات النظام التي كتبها المالك متاحة لمحادثات v1. تُهمَل نتيجة الخلفية إذا غيّر طلب آخر الملخص المحفوظ الذي استندت إليه.

إذا فشل التلخيص المتجدد أو لم يُرجع نصًا سرديًا، تحتفظ المعالجة البديلة بالملخص السابق والحقائق المخزنة الصالحة، ثم تضيف مقتطفًا موجزًا من الجزء الجديد. تتضمن المعالجة البديلة مقتطفات من 30 رسالة جديدة كحد أقصى في كل تحديث، ولا تسجل التغطية إلا حتى تلك الرسائل. تبقى الرسائل الأخرى مؤهلة لتحديث لاحق. يستخدم ضغط الطلب معرّف الرسالة المحفوظ لتجنب تكرار المقتطفات المغطاة، مع الاحتفاظ بالرسائل الحديثة والأدلة ذات الأولوية وسياق Study المنسوخ.

يميّز المشرف المشاركين بحسب معرّف Mind. تظل Minds التي تحمل اسم العرض نفسه مرشحين منفصلين، وتُطبَّق حدود الأدوار ومنع المتحدث نفسه من الرد مرتين متتاليتين بحسب المعرّف. قد ينهي المشرف النقاش قبل أن يجيب كل Mind.

تعيد حالات فشل التوليد غير المتوقعة خطأ 500 عامًا دون تفاصيل المزوّد، وتطلب رد الوحدات المحجوزة للإجابات الفاشلة. لا تُلغى الإجابات المولّدة سابقًا أو الرسائل المحفوظة. يظل الرفض الصريح بسبب قدرات النموذج 400 مع data.errorType: "unsupported_model_capability". في محادثات عدة Minds، لا يؤخر التلخيص الاختياري في الخلفية إجابة محفوظة بالفعل ولا يحولها إلى استجابة خطأ.

تخضع طلبات الرسائل أيضًا لحد JSON قدره 1 MiB؛ تجاوزه يعيد 413 قبل عمليات قاعدة البيانات أو التحقق من استحقاقات الخطة. الاستجابات خاصة ولا تُخزّن مؤقتًا. يمكن للمالك فقط إرسال الرسائل. تعيد مساحات العمل المُدارة التحقق من مساحة العمل الحالية وصلاحيات Minds/Audiences المرتبطة بكل طلب؛ سحب الوصول يعيد 404 قبل الحفظ أو الفوترة.

مثال الاستجابة أدناه خاص بـ Mind واحد. تعيد محادثات عدة Minds الحقل messages[]، ومحادثات Study الحقل outputData. استخدم role: "system" لحفظ ملاحظة سياقية دون توليد أو استهلاك حصة الرسائل؛ وتكون الاستجابة { messageId, role: "system" }.

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

جسم الطلب:

{
  "content": "What are the latest advancements in solar panel technology?"
}

اختيار النموذج في الدردشة ذات الحالة يتبع هذا الترتيب: تجاوز لكل طلب، ثم مزوّد الفريق المفضّل إذا كان مضبوطاً ومؤهلاً، ثم الافتراضي الخاص بالمنتج. في هذا الـ endpoint، تُرفض التجاوزات الجزئية بخطأ 400 Bad Request؛ أرسل model وprovider معاً أو احذف كليهما.

الاستجابة:

{
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency...",
  "messageId": "cmnkbsddh00033v01ptk9t4et"
}

مثال متعدد الأدوار

مع المحادثات ذات الحالة، ترسل فقط الرسالة الجديدة في كل مرة. يتذكر الخادم كل شيء:

# Step 1: Create a chat
CHAT=$(curl -s -X POST "https://getminds.ai/api/v1/chats" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Research Session", "mindId": "your-mind-id" }')

CHAT_ID=$(echo $CHAT | jq -r '.data.id')

# Step 2: Send messages (server manages history automatically)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "What are the top marketing trends?" }'

# Step 3: Follow up (the mind remembers the previous exchange)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Which of those would work best on a small budget?" }'

كيف تعمل داخلياً:

• يتم حفظ كل رسالة في قاعدة البيانات
• في المحادثات ذات Mind واحد وسجل طويل، تُحتفظ بأحدث 8 رسائل بكامل محتواها
• تستخدم الأدوار الأقدم الملخص المحفوظ عند توفره، مع مقتطفات من الرسائل التي لم تُغطَّ بعد
• تفقد الملخصات بعض التفاصيل؛ وقد يظل السجل الطويل جدًا أو الرسائل الكبيرة عرضة لبلوغ حدود سياق النموذج.

حذف محادثة

DELETE /api/v1/chats/{chatId}

يمكن للمالك فقط حذف المحادثة ورسائلها نهائيًا. تبقى Minds وAudiences متاحة. يعيد النجاح 204 بلا جسم استجابة؛ لا تحاول تحليله كـ JSON. تعيد بيانات الاعتماد المفقودة أو غير الصالحة 401، ومحادثة مالك آخر 403، والمحادثة غير الموجودة 404، بما في ذلك إذا حُذفت أو نُقلت ملكيتها قبل الكتابة النهائية. تستخدم استجابات الحذف Cache-Control: private, no-store.

إكمالات عديمة الحالة

للطلبات الفردية أو عندما ترغب في إدارة سجل المحادثة بنفسك.

إرسال رسالة

أرسل رسائل إلى mind واستقبل الاستجابات.

Endpoint: POST /api/v1/minds/{mindId}/completion

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

جسم الطلب

{
  "messages": [
    {
      "role": "user",
      "content": "What are the latest advancements in solar panel technology?"
    }
  ]
}

المعاملات

الاستجابة

{
  "messageId": "msg_550e840029b141d4a716446655440000",
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency, bifacial panels that capture light from both sides, and integrated storage systems...",
  "metadata": {
    "ragCitations": [
      {
        "id": "abc123",
        "displaySource": "Mind knowledge",
        "similarity": 0.89
      }
    ]
  }
}

مثال رسالة واحدة

اطرح سؤالاً واحداً:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top 3 marketing trends for 2025?"
      }
    ]
  }'

محادثة متعددة الأدوار

حافظ على سياق المحادثة بتضمين الرسائل السابقة:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top marketing trends?"
      },
      {
        "role": "assistant",
        "content": "The top trends are AI personalization, short-form video, and community building..."
      },
      {
        "role": "user",
        "content": "How can I implement AI personalization on a budget?"
      }
    ]
  }'

نصائح للمحادثات متعددة الأدوار:

• ضمّن سجل المحادثة الكامل في كل طلب
• الترتيب مهم: يجب أن تكون الرسائل بترتيب زمني
• تناوب بين دور user وassistant
• يجب أن تكون الرسالة الأخيرة دائماً من user

المرفقات

أرفق الملفات والمستندات والصور والروابط لتوفير سياق للـ minds. تستقبل الـ minds المحتوى المعالَج كجزء من المحادثة.

إرفاق الملفات

أضف الملفات عبر مصفوفة metadata.attachedFiles في رسالة المستخدم:

في طلبات الإكمال عديمة الحالة، استخدم ملفًا رفعته بنفسك، أو رابط ملف محادثة بتوقيع صالح، أو سياقًا تمت مشاركته عبر Study يملكها من رفع الملف. تُرجع ملفات مساحة العمل غير المصرح بها 403 Upload access denied (إطار خطأ في وضع البث). تحتفظ روابط HTTP(S) الخارجية برمز الوصول الخاص بها، ولا يُعاد توقيع مسار تخزين عشوائي. استبدل your-user-id في الأمثلة بمعرّف المستخدم الخاص بك واستخدم المسار الذي تعيده نقطة نهاية رفع الملفات.

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Please review this document and summarize the key points",
        "metadata": {
          "attachedFiles": [
            {
              "url": "https://example.com/quarterly-report.pdf",
              "name": "Q4 2025 Report",
              "type": "application/pdf"
            },
            {
              "path": "chat/your-user-id/meeting-notes.docx",
              "name": "Strategy Meeting Notes"
            }
          ]
        }
      }
    ]
  }'

تنسيق المرفق

يدعم كل كائن مرفق:

ملاحظة: قدّم إما url أو path، ولكن ليس كليهما.

أنواع الملفات المدعومة

المستندات:

• PDF (.pdf) — استخراج النص + OCR للصفحات الممسوحة ضوئياً
• Word (.docx) — استخراج النص الكامل
• Text (.txt, .md) — محتوى نصي مباشر
• CSV/Excel (.csv, .xlsx) — استخراج الجداول

الصور:

• PNG, JPG, WEBP — OCR + التحليل البصري
• قدرات الرؤية لفهم الصور

URLs خارجية:

• صفحات ويب يتم جلبها باستخدام Firecrawl (عرض JS + لقطات شاشة)
• تحويل تلقائي إلى Markdown

المعالجة

تتم معالجة الملفات تلقائياً قبل إرسالها إلى الـ mind:

1. التنزيل — تُجلب الملفات من URL أو من تخزين Supabase
2. الاستخراج — يُستخرج المحتوى (النص من PDF، OCR من الصور، إلخ)
3. الإدخال — يُضاف المحتوى المعالَج إلى سياق المحادثة
4. الاستجابة — يرى الـ mind رسالتك ومحتوى الملف معاً

حدود المعالجة:

• المهلة: 30 ثانية لكل ملف
• تُعالج الملفات بالتوازي
• تُظهر الملفات الفاشلة رسائل احتياطية أنيقة

مثال ملفات متعددة

{
  "messages": [
    {
      "role": "user",
      "content": "Compare these two proposals and recommend which one to pursue",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/proposal-a.pdf",
            "name": "Proposal A - Cloud Migration",
            "type": "application/pdf"
          },
          {
            "url": "https://example.com/proposal-b.pdf",
            "name": "Proposal B - On-Prem Upgrade",
            "type": "application/pdf"
          },
          {
            "path": "chat/your-user-id/budget-analysis.xlsx",
            "name": "Budget Comparison"
          }
        ]
      }
    }
  ]
}

المرفقات في سجل المحادثة

عند متابعة محادثة تحتوي على مرفقات، ضمّن الرسالة الأصلية مع المرفقات في السجل:

{
  "messages": [
    {
      "role": "user",
      "content": "Analyze this sales data",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/sales-q4.csv",
            "name": "Q4 Sales Data"
          }
        ]
      }
    },
    {
      "role": "assistant",
      "content": "Based on the Q4 sales data, I can see that revenue increased by 23% compared to Q3..."
    },
    {
      "role": "user",
      "content": "What were the top 3 performing products?"
    }
  ]
}

ملاحظة: تُعالج الملفات مرة واحدة فقط عند إرفاقها لأول مرة. تشير الرسائل اللاحقة في نفس المحادثة إلى المحتوى الذي سبقت معالجته.

روابط الويب

لصفحات الويب والمحتوى الخارجي، استخدم حقل url:

{
  "messages": [
    {
      "role": "user",
      "content": "Summarize the key findings from this research paper",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://arxiv.org/pdf/2103.12345.pdf",
            "name": "AI Research Paper",
            "type": "application/pdf"
          }
        ]
      }
    }
  ]
}

بالنسبة لصفحات الويب تحديداً:

• تُعرض المواقع المعتمدة بكثرة على JavaScript باستخدام Firecrawl
• تُلتقط لقطات شاشة للسياق البصري
• يُحوَّل المحتوى إلى Markdown نظيف

معالجة الأخطاء

في حال فشل معالجة الملف:

• يستقبل الـ mind رسالة احتياطية تشير إلى أن الملف أُرفق ولكن المعالجة فشلت
• تستمر المحادثة بشكل طبيعي
• تُظهر أخطاء المهلة [Processing timeout - file may be too large]
• تُظهر الأخطاء الأخرى [Processing failed - file uploaded but analysis unavailable]

هذا يضمن أن الـ minds على دراية بمحاولات الإرفاق حتى لو فشلت المعالجة.

الرسالة الأولية (التحية)

إذا أرسلت مصفوفة رسائل فارغة أو لم ترسل رسائل، سيقدّم الـ mind نفسه:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": []
  }'

الاستجابة:

{
  "content": "Hi! I'm Sarah, a marketing director with 15 years of experience in B2B SaaS. I specialize in growth marketing and data-driven strategies. What can I help you with today?"
}

Model Override

يمكنك اختيارياً تجاوز نموذج الذكاء الاصطناعي المستخدم لطلب إكمال بلا حالة بتمرير معامل model. هذا مفيد للمقارنة المعيارية أو تحسين التكلفة أو اختبار سلوكيات نماذج مختلفة. تستخدم endpoints الدردشة ذات الحالة والـ panels تحققاً أكثر صرامة: يجب إرسال model وprovider معاً.

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are your thoughts on sustainable packaging?"
      }
    ],
    "model": "gpt-6-luna"
  }'

عندما لا يتم تحديد model، يُستخدم الافتراضي الخاص بالخادم.

المزودون

مرّر أحد النماذج المدرجة أعلاه. يُعاد توجيه المعرّفات المتقاعدة (انظر أدناه)، وأي نموذج آخر يُرجع 400 Bad Request. يتم اكتشاف المزود تلقائياً من بادئات أسماء النماذج الشائعة (claude- ← Anthropic، gemini- ← Google، gpt-/o1/o3/o4 ← OpenAI).

Your own model

لتشغيل نموذج مضبوط بدقة (fine-tune) أو نموذج مستضاف ذاتياً، يضيفه مسؤول الفريق بوصفه اتصال نموذج للفريق (بروتوكول OpenAI Chat Completions أو OpenAI Responses أو Anthropic Messages) ويتحقق منه. ثم أرسل معرّف الاتصال ورقم مراجعته الحالية بدلاً من model وprovider:

{
  "messages": [...],
  "modelConnection": { "id": "3f6c1e2a-5b7d-4c1e-9a0f-2d8e4b6a1c90", "revision": 3 }
}

يسرد GET /api/v1/model-connections اتصالات فريقك مع مراجعاتها وقدراتها المتحقَّق منها. يحتاج الاتصال إلى النص والبث، بالإضافة إلى المخرجات المنظمة عند إرسال response_format واستدعاء الأدوات عندما يستخدم الطلب أدوات. إذا فشلت نقطة الاتصال الخاصة بك، يفشل الطلب: لا ينتقل Minds أبداً إلى أحد نماذجه الخاصة. تُرفض الصور والوسائط الأخرى بالرمز MODEL_CONNECTION_MEDIA_UNVERIFIED. لا تقبل رسائل الدردشة ذات الحالة (/chats/{chatId}/messages) اتصالاً.

Structured Output

اطلب استجابات JSON مضمونة تطابق مخططاً محدداً باستخدام معامل response_format. يتبع ذلك نمط المخرجات المنظمة بأسلوب OpenAI وهو مفيد لاستخراج البيانات المنظمة من المحادثات.

JSON Schema Mode

أجبر النموذج على إخراج JSON صالح يطابق مخططك:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Analyze the sentiment of this text: I love this product, it exceeded all my expectations!"
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "sentiment_analysis",
        "description": "Sentiment analysis result",
        "schema": {
          "type": "object",
          "properties": {
            "sentiment": {
              "type": "string",
              "enum": ["positive", "negative", "neutral"]
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "keywords": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["sentiment", "confidence", "keywords"]
        }
      }
    }
  }'

الاستجابة:

{
  "content": "{\"sentiment\": \"positive\", \"confidence\": 0.95, \"keywords\": [\"love\", \"exceeded\", \"expectations\"]}",
  "parsed": {
    "sentiment": "positive",
    "confidence": 0.95,
    "keywords": ["love", "exceeded", "expectations"]
  }
}

JSON Object Mode

أجبر إخراج JSON دون التحقق من المخطط:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "List 3 marketing ideas as JSON"
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'

أنواع Response Format

حقول JSON Schema

ميزات المخطط المدعومة

يتم دعم ميزات JSON Schema التالية:

• الأنواع: string, number, integer, boolean, array, object, null
• القيود: enum, minimum, maximum, minLength, maxLength, minItems, maxItems
• البنية: properties, required, items, additionalProperties
• بيانات التعريف: description (يُستخدم لتوجيه النموذج)

ملاحظات

• تعمل الأدوات (RAG، البحث عبر الإنترنت، إلخ) مع المخرجات المنظمة — لا يزال بإمكان الـ mind البحث في قاعدة معرفته قبل توليد الاستجابة المنظمة
• يحتوي حقل parsed على كائن JSON المحلَّل للراحة؛ يحتوي content على سلسلة JSON الخام
• جميع المزودين الرئيسيين (OpenAI, Anthropic, Google) يدعمون المخرجات المنظمة
• للمخططات المعقدة، فكّر في إضافة حقول description لتوجيه إخراج النموذج

Tool Calling

مكّن الـ minds من استدعاء وظائفك المخصصة أثناء المحادثات. يتبع ذلك نمط استدعاء الوظائف المتوافق مع OpenAI ويتيح لك توسيع قدرات الـ minds بأدوات وواجهات برمجية خارجية.

كيف يعمل

1. تعريف الأدوات: مرّر تعريفات الأدوات مع الأسماء والأوصاف ومعاملات JSON Schema
2. الـ Mind يقرر: يحدد الـ mind متى يستدعي أدواتك بناءً على المحادثة (أو تُجبره باستخدام tool_choice)
3. API يُرجع tool calls: تتضمن الاستجابة tool_calls مع اسم الأداة والمعاملات المولّدة
4. تنفيذ الأدوات: تشغّل الأدوات في تطبيقك وتحصل على النتائج
5. إرسال النتائج مرة أخرى: ضمّن نتائج الأداة في الرسالة التالية مع role: "tool"
6. الـ Mind يستجيب: يدمج الـ mind نتائج الأداة في استجابته النهائية

مثال أساسي

طلب مع أدوات:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            },
            "units": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "Temperature units"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }'

الاستجابة:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_abc123",
      "name": "get_weather",
      "arguments": {
        "city": "Berlin",
        "units": "celsius"
      }
    }
  ]
}

نفّذ الأداة وأرسل النتائج:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      },
      {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_abc123",
            "name": "get_weather",
            "arguments": {
              "city": "Berlin",
              "units": "celsius"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": 18, \"condition\": \"partly cloudy\", \"humidity\": 65}"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["city"]
        }
      }
    ]
  }'

الاستجابة النهائية:

{
  "content": "The current weather in Berlin is 18°C and partly cloudy, with 65% humidity."
}

مخطط تعريف الأداة

يجب أن تتبع كل أداة هذه البنية:

{
  "name": "tool_name",
  "description": "Clear description of when and how to use this tool",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "What this parameter does"
      }
    },
    "required": ["param1"]
  },
  "strict": true
}

الحقول المطلوبة:

الحقول الاختيارية:

Tool Choice Modes

تحكم في متى وكيف يستدعي الـ mind الأدوات باستخدام معامل tool_choice:

أمثلة:

// Let the mind decide
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "auto"
}

// Force a specific tool
{
  "messages": [...],
  "tools": [...],
  "tool_choice": {
    "name": "search_database"
  }
}

// Require at least one tool call
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "required"
}

Parallel Tool Calls

افتراضياً، يمكن للـ minds استدعاء أدوات متعددة في دور واحد لتحقيق الكفاءة:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "get_customer",
      "arguments": { "id": "CUST-001" }
    },
    {
      "id": "call_2",
      "name": "get_customer",
      "arguments": { "id": "CUST-002" }
    }
  ]
}

لتعطيل الاستدعاءات المتوازية وفرض التنفيذ التسلسلي:

{
  "messages": [...],
  "tools": [...],
  "parallel_tool_calls": false
}

تنسيق رسالة الأداة

عند إرسال نتائج الأداة مرة أخرى، استخدم دور tool:

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"result\": \"success\", \"data\": {...}}"
}

تأتي نتائج الأدوات بعد رسالة المساعد المطابقة، بما فيها tool_calls. استخدم معرّف الاستدعاء واسمه كما أُعيدا، وأرسل كل نتيجة مرة واحدة. تؤدي الوسائط غير الصالحة ومعرّفات الاستدعاء غير المعروفة وأسماء الأدوات غير المطابقة والنتائج المكررة ونتائج العميل المفقودة إلى 400 قبل التوليد.

الأدوات الداخلية مقابل أدوات المستخدم

يمتلك Minds أدوات مدمجة تعمل من جانب الخادم وتنفَّذ تلقائياً:

الفروقات الرئيسية:

• الأدوات الداخلية: تُنفَّذ من جانب الخادم، النتائج مضمَّنة في content وmetadata. لا تُرجع أبداً في tool_calls.
• أدوات المستخدم: تُرجع في tool_calls لتنفّذها أنت. يجب إرسال النتائج مرة أخرى كرسائل tool.

لا يمكنك تجاوز الأدوات الداخلية أو تعطيلها. أدوات المستخدم إضافية — فهي توسّع قدرات الـ mind.

مثال شامل بعدة أدوات

مساعد قانوني ذكي (mind) مع عدة أدوات مخصصة:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Create a new case for Schmidt vs. Mueller and search for similar precedents"
      }
    ],
    "tools": [
      {
        "name": "create_case",
        "description": "Create a new legal case in the system",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Case title (parties involved)"
            },
            "practice_area": {
              "type": "string",
              "enum": ["corporate", "litigation", "employment", "ip"],
              "description": "Legal practice area"
            },
            "client_id": {
              "type": "string",
              "description": "Client identifier"
            }
          },
          "required": ["title", "practice_area"]
        }
      },
      {
        "name": "search_precedents",
        "description": "Search legal database for similar cases",
        "parameters": {
          "type": "object",
          "properties": {
            "keywords": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Search keywords"
            },
            "practice_area": {
              "type": "string",
              "description": "Filter by practice area"
            },
            "max_results": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "description": "Maximum number of results"
            }
          },
          "required": ["keywords"]
        }
      }
    ],
    "parallel_tool_calls": true
  }'

استجابة باستدعاءات أدوات متوازية:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "create_case",
      "arguments": {
        "title": "Schmidt vs. Mueller",
        "practice_area": "litigation"
      }
    },
    {
      "id": "call_2",
      "name": "search_precedents",
      "arguments": {
        "keywords": ["Schmidt", "Mueller"],
        "practice_area": "litigation",
        "max_results": 10
      }
    }
  ]
}

أفضل الممارسات

1. اكتب أوصافاً واضحة: حقل description بالغ الأهمية. كن محدداً بشأن متى ولماذا تُستخدم كل أداة.

   ❌ "description": "Search database"
   ✅ "description": "Search the legal precedents database for similar cases based on keywords and practice area"
   

2. استخدم أوصاف المعاملات: ساعد الـ mind على فهم ما يفعله كل معامل.

   "case_id": {
     "type": "string",
     "description": "Unique case identifier in format CASE-YYYY-NNNN"
   }
   

3. استفد من enums للقيم المقيدة:

   "status": {
     "type": "string",
     "enum": ["pending", "active", "closed", "archived"]
   }
   

4. اضبط قيود التحقق:

   "priority": {
     "type": "integer",
     "minimum": 1,
     "maximum": 5,
     "description": "Priority level (1=lowest, 5=highest)"
   }
   

5. فعّل الوضع الصارم: احتفظ بـ strict: true (الافتراضي) لضمان أن الـ mind يولّد معاملات صالحة.
6. أرجع نتائج أدوات منظمة: استخدم JSON لنتائج الأدوات لجعلها سهلة التحليل:

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": true, \"case_id\": \"CASE-2026-001\", \"created_at\": \"2026-03-30T23:00:00Z\"}"
   }
   

7. تعامل مع الأخطاء بسلاسة: أرجع تفاصيل الخطأ في نتيجة الأداة:

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": false, \"error\": \"Case already exists\", \"error_code\": \"DUPLICATE_CASE\"}"
   }
   

القيود

• 128 أداة كحد أقصى لكل طلب
• يجب أن تكون أسماء الأدوات فريدة ولا تتعارض مع أسماء الأدوات الداخلية
• يحدث تنفيذ الأدوات من جانب العميل — أنت مسؤول عن تشغيل وتأمين أدواتك
• يجب إرسال نتائج الأدوات مرة أخرى في سجل المحادثة حتى يستجيب الـ mind

دعم JSON Schema

يدعم حقل parameters ميزات JSON Schema القياسية:

الأنواع:

• string, number, integer, boolean, array, object, null

التحقق:

• enum — تقييد بقيم محددة
• minimum, maximum — حدود رقمية
• minLength, maxLength — طول السلسلة
• minItems, maxItems — حجم المصفوفة
• pattern — تحقق بتعبير نمطي
• format — تنسيقات السلاسل (مثل "date-time", "email", "uri")

البنية:

• properties — خصائص الكائن
• required — الحقول المطلوبة
• items — مخطط عناصر المصفوفة
• additionalProperties — السماح/منع خصائص إضافية

مثال بتحقق متقدم:

{
  "name": "schedule_meeting",
  "description": "Schedule a meeting with a client",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "date": {
        "type": "string",
        "format": "date-time",
        "description": "Meeting date and time in ISO 8601 format"
      },
      "attendees": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        },
        "minItems": 1,
        "maxItems": 20
      },
      "duration_minutes": {
        "type": "integer",
        "minimum": 15,
        "maximum": 480,
        "description": "Meeting duration (15-480 minutes)"
      }
    },
    "required": ["title", "date", "attendees"]
  }
}

كيف يعمل

1. تحميل السياق

عند إرسالك رسالة، يقوم الـ mind بـ:

• تحميل نظام البرومبت والتهيئة الخاصة به
• البحث تلقائياً في قاعدة معرفته عن المعلومات ذات الصلة
• أخذ سجل المحادثة بعين الاعتبار

2. المعالجة

الـ mind:

• يحلّل رسالتك في سياقها
• يُؤسّس الاستجابات على المعرفة المسترجَعة مع الاقتباسات
• يصل إلى أدوات إضافية (البحث عبر الإنترنت، توليد الصور، إلخ) عند الحاجة
• يصيغ استجابة تتماشى مع شخصيته

3. توليد الاستجابة

الـ mind:

• يولّد استجابة تعكس خبرته
• يتضمن اقتباسات عند استخدام قاعدة المعرفة أو مصادر الويب
• يُرجع الرسالة مع بيانات تعريف اختيارية (اقتباسات، صور، إلخ)

Metadata

يمكن أن تتضمن الاستجابات بيانات تعريف إضافية:

الصور

عندما يولّد الـ mind أو يعرض صوراً:

{
  "content": "Here are some logo concepts...",
  "metadata": {
    "images": [
      {
        "id": "img_123",
        "url": "https://...",
        "filename": "Logo Concept 1",
        "description": "Modern minimalist logo with blue gradient",
        "source": "generated"
      }
    ]
  }
}

اقتباسات المعرفة

عندما يسترجع الـ mind معلومات من قاعدة معرفته أو من بحث الويب:

{
  "content": "Based on recent research, solar panel efficiency has improved significantly...",
  "metadata": {
    "ragCitations": [
      {
        "id": "9bf44ab0-9d83-42ec-b941-c0ab7610e949",
        "displaySource": "Mind knowledge",
        "similarity": 0.85
      },
      {
        "id": "external-web-123",
        "displaySource": "https://example.com/solar-research",
        "similarity": 0.92
      }
    ]
  }
}

حقول الاقتباس:

• id — المعرّف الفريد للمصدر
• displaySource — اسم المصدر القابل للقراءة أو الـ URL
• similarity — درجة الملاءمة (0-1) تشير إلى مدى تطابق المصدر مع الاستعلام

تبحث الـ minds تلقائياً في قاعدة معرفتها قبل الرد وتُدرج الاقتباسات عند تأسيس إجاباتها على مصادر محددة.

التحكم في الوصول

يمكنك المحادثة مع الـ minds التي:

• تملكها — الـ minds التي أنشأتها
• لديك وصول إليها — الـ minds المشاركة معك من قِبل أعضاء الفريق
• أنت عضو فيها — الـ minds في مساحات عمل الفرق التي تنتمي إليها
• الـ minds العامة — الـ minds التي يمكن الوصول إليها علناً

محاولة الوصول إلى الـ minds غير المصرح بها تُرجع:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

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

استجابة نصية

معظم الاستجابات نص عادي:

{
  "content": "Based on current trends, I recommend focusing on..."
}

استجابة منظمة

قد تُرجع بعض الـ minds محتوى منظماً:

{
  "content": "Here's my analysis:\n\n1. Trend: AI Personalization\n   - Impact: High\n   - Timeline: 6-12 months\n\n2. Trend: Short-form Video\n   - Impact: Very High\n   - Timeline: Immediate"
}

استجابة فارغة مع metadata

أحياناً تُرجع metadata فقط (مثلاً لتوليد الصور):

{
  "content": "",
  "metadata": {
    "images": [...]
  }
}

أفضل الممارسات

كن محدداً

❌ "Tell me about marketing"
✅ "What are the most cost-effective digital marketing channels for a B2B SaaS startup with a $5K monthly budget?"

قدّم السياق

✅ "We're launching a sustainable fashion brand targeting Gen Z. What social media strategy would you recommend?"

استخدم المتابعات

استفد من ذاكرة المحادثة:

User: "What are the top trends?"
Assistant: "The top trends are..."
User: "Which of these would work best for a small budget?"
Assistant: "For a small budget, I'd focus on..."

اشر إلى المعرفة

إذا كنت قد رفعت معرفة، أشر إليها:

✅ "Based on our brand guidelines, what tone should we use for this campaign?"

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

400 Bad Request

Mind ID مفقود أو غير صالح:

{
  "statusCode": 400,
  "statusMessage": "Mind ID is required"
}

مزود غير مدعوم:

{
  "statusCode": 400,
  "statusMessage": "Unsupported provider: 'invalid'. Supported providers: openai, anthropic, google."
}

اسم نموذج غامض دون مزود:

{
  "statusCode": 400,
  "statusMessage": "Cannot auto-detect provider for model 'my-model'. Please specify a 'provider' parameter (openai, anthropic, or google)."
}

401 Unauthorized

مفتاح API غير صالح.

403 Forbidden

تم رفض الوصول إلى الـ Mind:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 Not Found

الـ Mind غير موجود:

{
  "statusCode": 404,
  "statusMessage": "Mind not found"
}

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

• يفرض v1 API حداً قابلاً للضبط لكل حساب مصادق عليه (300 طلب في الدقيقة افتراضياً)
• اقرأ RateLimit-Limit وRateLimit-Remaining والتزم بـRetry-After بعد 429
• حدّ طلبات completion المتوازية لأنها كثيفة الموارد

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

• افهم latency والأداء
• تعرّف على errors وrate limits
• أنشئ أول mind لك
• ارفع knowledge لتحسين الاستجابات
• اقرأ API overview