Chat API

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

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

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

إنشاء محادثة

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

Endpoint: POST /api/v1/chats

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

جسم الطلب:

{
  "name": "My Conversation",
  "sparkId": "your-spark-id"
}

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

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

إرسال رسالة

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

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

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", "sparkId": "your-spark-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?" }'

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

• يتم حفظ كل رسالة في قاعدة البيانات
• تُرسل آخر 8 رسائل في السياق الكامل
• تُضغط الرسائل الأقدم في ملخص LLM متحرك
• يمكن أن تستمر المحادثات لأسابيع/أشهر دون الوصول إلى حدود السياق

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

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

إرسال رسالة

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

Endpoint: POST /api/v1/sparks/{sparkId}/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": "Spark knowledge",
        "similarity": 0.89
      }
    ]
  }
}

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

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

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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/sparks/spark-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 في رسالة المستخدم:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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": "uploads/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": "uploads/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/sparks/spark-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/sparks/spark-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-4o-mini"
  }'

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

المزودون

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

بالنسبة للنماذج ذات الأسماء الغامضة، حدد provider صراحةً:

{
  "messages": [...],
  "model": "my-custom-fine-tune",
  "provider": "openai"
}

إذا تعذّر تحديد المزود، يُرجع API خطأ 400 Bad Request يطلب منك تحديده.

Structured Output

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

JSON Schema Mode

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

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

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

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

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

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

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

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

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

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

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

{
  "statusCode": 400,
  "statusMessage": "Spark 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

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

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

404 Not Found

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

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

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

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

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

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