Chat API

Mind'larınıza mesajlar gönderip AI tarafından oluşturulan yanıtlar alın. Chat API hem stateless completion'ları hem de otomatik geçmiş yönetimiyle stateful çok-turlu konuşmaları destekler.

Stateful Chat'ler (Önerilir)

Sunucunun geçmişi, bağlam sıkıştırmayı ve rolling summary'leri otomatik olarak yönettiği kalıcı konuşmalar oluşturun. Her istekle birlikte tüm mesaj geçmişini göndermeye gerek yoktur.

Chat Oluştur

Bir mind'a bağlı yeni bir stateful konuşma oluşturun.

Endpoint: POST /api/v1/chats

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body:

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

Response (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"
      }
    ]
  }
}

Mesaj Gönder

Mevcut bir chat'e mesaj gönderin. Sunucu konuşma geçmişini, bağlam penceresi sıkıştırmayı ve rolling summary'leri otomatik olarak yönetir.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body:

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

Stateful chat model seçimi şu sırayı kullanır: istek bazında override, yapılandırılmış ve uygun ise takımın tercih ettiği sağlayıcı, ardından ürün varsayılanı. Bu endpoint'te kısmi override'lar 400 Bad Request ile reddedilir; hem model hem provider gönderin veya ikisini de göndermeyin.

Response:

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

Çok-Turlu Örnek

Stateful chat'lerde her seferinde sadece yeni mesajı gönderirsiniz. Sunucu her şeyi hatırlar:

# Adım 1: Bir chat oluşturun
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')

# Adım 2: Mesajları gönderin (sunucu geçmişi otomatik olarak yönetir)
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?" }'

# Adım 3: Takip edin (mind önceki alışverişi hatırlar)
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?" }'

Arka planda nasıl çalışır:

• Her mesaj veritabanına kalıcı olarak kaydedilir
• Son 8 mesaj tam bağlamda gönderilir
• Daha eski mesajlar rolling LLM özetine sıkıştırılır
• Konuşmalar bağlam limitlerine takılmadan haftalarca/aylarca sürebilir

Stateless Completion'lar

Tek istekler için veya konuşma geçmişini kendiniz yönetmek istediğinizde.

Mesaj Gönder

Bir mind'a mesajlar gönderin ve yanıtlar alın.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

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

Parametreler

Response

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

Tek Mesaj Örneği

Tek bir soru sorun:

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?"
      }
    ]
  }'

Çok-Turlu Konuşma

Önceki mesajları dahil ederek konuşma bağlamını koruyun:

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?"
      }
    ]
  }'

Çok-Turlu Konuşmalar İçin İpuçları:

• Her istekte tüm konuşma geçmişini dahil edin
• Sıra önemlidir: mesajlar kronolojik sırada olmalıdır
• user ve assistant rolleri arasında alternatif yapın
• Son mesaj her zaman user'dan olmalıdır

Dosya Ek'leri

Mind'larınıza bağlam sağlamak için dosyalar, belgeler, görseller ve bağlantılar ekleyin. Mind'lar işlenmiş içeriği konuşmanın bir parçası olarak alır.

Dosya Ekleme

Kullanıcı mesajınızdaki metadata.attachedFiles dizisi üzerinden dosya ekleyin:

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"
            }
          ]
        }
      }
    ]
  }'

Ek Formatı

Her ek objesi şunları destekler:

Not: Her ikisini değil, url VEYA path sağlayın.

Desteklenen Dosya Türleri

Belgeler:

• PDF (.pdf) - Metin çıkarma + taranmış sayfalar için OCR
• Word (.docx) - Tam metin çıkarma
• Metin (.txt, .md) - Doğrudan metin içeriği
• CSV/Excel (.csv, .xlsx) - Tablo çıkarma

Görseller:

• PNG, JPG, WEBP - OCR + görsel analiz
• Görsel anlama için vision yetenekleri

Harici URL'ler:

• Firecrawl ile getirilen web sayfaları (JS rendering + ekran görüntüleri)
• Otomatik markdown dönüştürme

İşleme

Dosyalar mind'a gönderilmeden önce otomatik olarak işlenir:

1. İndirme - Dosyalar URL'den veya Supabase storage'dan getirilir
2. Çıkarma - İçerik çıkarılır (PDF'lerden metin, görsellerden OCR, vb.)
3. Enjeksiyon - İşlenmiş içerik konuşma bağlamına eklenir
4. Yanıt - Mind hem mesajınızı hem de dosya içeriğini görür

İşleme limitleri:

• Timeout: dosya başına 30 saniye
• Dosyalar paralel olarak işlenir
• Başarısız dosyalar zarif fallback mesajları gösterir

Çoklu Dosya Örneği

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

Konuşma Geçmişinde Dosya Ek'leri

Dosya ek'leri olan bir konuşmaya devam ederken, ek'lerle orijinal mesajı geçmişe dahil edin:

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

Not: Dosyalar yalnızca ilk eklendiğinde bir kez işlenir. Aynı konuşmadaki sonraki mesajlar zaten işlenmiş içeriği referans alır.

Web Bağlantıları

Web sayfaları ve harici içerik için url alanını kullanın:

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

Özellikle web sayfaları için:

• JavaScript ağırlıklı siteler Firecrawl ile render edilir
• Görsel bağlam için ekran görüntüleri yakalanır
• İçerik temiz markdown'a dönüştürülür

Error Yönetimi

Dosya işleme başarısız olursa:

• Mind, dosyanın eklendiğini ancak işlemenin başarısız olduğunu belirten bir fallback mesajı alır
• Konuşma normal şekilde devam eder
• Timeout hataları [Processing timeout - file may be too large] gösterir
• Diğer hatalar [Processing failed - file uploaded but analysis unavailable] gösterir

Bu, işleme başarısız olsa bile mind'ların denenmiş ek'lerin farkında olmasını sağlar.

İlk Mesaj (Selamlama)

Boş bir mesaj dizisi veya hiç mesaj göndermezseniz, mind kendini tanıtır:

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": []
  }'

Response:

{
  "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 parametresini geçirerek stateless bir completion isteği için kullanılan AI modelini opsiyonel olarak geçersiz kılabilirsiniz. Bu; benchmarking, maliyet optimizasyonu veya farklı model davranışlarını test etmek için faydalıdır. Stateful chat ve panel endpoint'leri override doğrulamasını daha sıkı yapar: model ve provider birlikte gönderilmelidir.

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 belirtilmediğinde sunucu varsayılanı kullanılır.

Provider'lar

Provider tarafından desteklenen herhangi bir model string'ini geçirebilirsiniz. Provider, yaygın model adı önekleriyle otomatik olarak tespit edilir (claude- → Anthropic, gemini- → Google, gpt-/o1/o3/o4 → OpenAI).

Belirsiz adlara sahip modeller için provider'ı açıkça belirtin:

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

Provider belirlenemezse, API belirtmenizi isteyen bir 400 Bad Request hatası döndürür.

Structured Output

response_format parametresini kullanarak belirli bir şemaya uyan garantili JSON yanıtları isteyin. Bu, OpenAI tarzı yapılandırılmış çıktı kalıbını izler ve konuşmalardan yapılandırılmış veri çıkarmak için faydalıdır.

JSON Schema Modu

Modeli şemanıza uyan geçerli JSON çıktısı üretmeye zorlayın:

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"]
        }
      }
    }
  }'

Response:

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

JSON Object Modu

Şema doğrulaması olmadan JSON çıktısını zorlayın:

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 Türleri

JSON Schema Alanları

Desteklenen Schema Özellikleri

Aşağıdaki JSON Schema özellikleri desteklenir:

• Türler: string, number, integer, boolean, array, object, null
• Kısıtlamalar: enum, minimum, maximum, minLength, maxLength, minItems, maxItems
• Yapı: properties, required, items, additionalProperties
• Meta veri: description (modeli yönlendirmek için kullanılır)

Notlar

• Tool'lar (RAG, web search, vb.) yapılandırılmış çıktıyla çalışır — mind, yapılandırılmış yanıtı oluşturmadan önce hâlâ bilgi tabanını arayabilir
• parsed alanı kolaylık için ayrıştırılmış JSON objesini içerir; content ham JSON string'i içerir
• Tüm büyük provider'lar (OpenAI, Anthropic, Google) yapılandırılmış çıktıyı destekler
• Karmaşık şemalar için modelin çıktısını yönlendirmek amacıyla description alanları eklemeyi düşünün

Tool Calling

Mind'ların konuşmalar sırasında özel fonksiyonlarınızı çağırmasına olanak tanıyın. Bu, OpenAI uyumlu function calling kalıbını izler ve harici tool'lar ve API'lerle mind'ların yeteneklerini genişletmenizi sağlar.

Nasıl Çalışır

1. Tool'ları tanımlayın: Adlar, açıklamalar ve JSON Schema parametreleriyle tool tanımlarını geçirin
2. Mind karar verir: Mind, konuşmaya dayanarak tool'larınızı ne zaman çağıracağına karar verir (veya tool_choice ile zorlarsınız)
3. API tool call'ları döndürür: Yanıt, tool adı ve oluşturulan argümanlarla tool_calls içerir
4. Tool'ları çalıştırın: Uygulamanızda tool'ları çalıştırır ve sonuçları alırsınız
5. Sonuçları geri gönderin: Tool sonuçlarını bir sonraki mesaja role: "tool" ile dahil edin
6. Mind yanıt verir: Mind, tool sonuçlarını nihai yanıtına entegre eder

Temel Örnek

Tool'lı istek:

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"]
        }
      }
    ]
  }'

Response:

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

Tool'u çalıştırın ve sonuçları geri gönderin:

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"]
        }
      }
    ]
  }'

Nihai yanıt:

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

Tool Tanım Şeması

Her tool şu yapıyı izlemelidir:

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

Zorunlu alanlar:

Opsiyonel alanlar:

Tool Choice Modları

tool_choice parametresini kullanarak mind'ın tool'ları ne zaman ve nasıl çağıracağını kontrol edin:

Örnekler:

// Mind'ın karar vermesine izin ver
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "auto"
}

// Belirli bir tool'u zorla
{
  "messages": [...],
  "tools": [...],
  "tool_choice": {
    "name": "search_database"
  }
}

// En az bir tool call gerekli
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "required"
}

Paralel Tool Call'lar

Varsayılan olarak, mind'lar verimlilik için tek bir turn'de birden fazla tool çağırabilir:

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

Paralel call'ları devre dışı bırakmak ve sıralı çalıştırmayı zorlamak için:

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

Tool Mesaj Formatı

Tool sonuçlarını geri gönderirken tool rolünü kullanın:

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

Dahili vs Kullanıcı Tool'ları

Minds, otomatik olarak yürütülen yerleşik sunucu tarafı tool'lara sahiptir:

Temel farklılıklar:

• Dahili tool'lar: Sunucu tarafında yürütülür, sonuçlar content ve metadata'ya dahil edilir. Asla tool_calls'ta döndürülmez.
• Kullanıcı tool'ları: Sizin yürütmeniz için tool_calls'ta döndürülür. Sonuçlar tool mesajları olarak geri gönderilmelidir.

Dahili tool'ları geçersiz kılamaz veya devre dışı bırakamazsınız. Kullanıcı tool'ları additive niteliktedir — mind'ın yeteneklerini genişletir.

Komple Çoklu-Tool Örneği

Birden fazla özel tool'a sahip bir legal assistant 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
  }'

Paralel tool call'larla yanıt:

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

En İyi Uygulamalar

1. Açık açıklamalar yazın: description alanı kritiktir. Her tool'un ne zaman ve neden kullanılacağı konusunda spesifik olun.

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

2. Parametre açıklamalarını kullanın: Mind'ın her parametrenin ne yaptığını anlamasına yardım edin.

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

3. Kısıtlı değerler için enum'lardan yararlanın:

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

4. Doğrulama kısıtlamalarını ayarlayın:

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

5. Strict modu etkinleştirin: Mind'ın geçerli argümanlar üretmesini sağlamak için strict: true (varsayılan) tutun.
6. Yapılandırılmış tool sonuçları döndürün: Ayrıştırmayı kolaylaştırmak için tool sonuçları için JSON kullanın:

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

7. Error'ları zarifçe yönetin: Tool sonucunda error ayrıntılarını döndürün:

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

Sınırlamalar

• İstek başına maksimum 128 tool
• Tool adları benzersiz olmalı ve dahili tool adlarıyla çakışmamalıdır
• Tool yürütme client tarafında gerçekleşir — tool'larınızı çalıştırmak ve güvenlik altına almak sizin sorumluluğunuzdur
• Mind'ın yanıt verebilmesi için tool sonuçları konuşma geçmişinde geri gönderilmelidir

JSON Schema Desteği

parameters alanı standart JSON Schema özelliklerini destekler:

Türler:

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

Doğrulama:

• enum — Belirli değerlere kısıtla
• minimum, maximum — Sayısal sınırlar
• minLength, maxLength — String uzunluğu
• minItems, maxItems — Dizi boyutu
• pattern — Regex doğrulaması
• format — String formatları (örn. "date-time", "email", "uri")

Yapı:

• properties — Obje özellikleri
• required — Zorunlu alanlar
• items — Dizi öğesi şeması
• additionalProperties — Ekstra özelliklere izin ver/verme

Gelişmiş doğrulama ile örnek:

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

Nasıl Çalışır

1. Bağlam Yükleme

Bir mesaj gönderdiğinizde, mind:

• Sistem prompt'unu ve yapılandırmasını yükler
• Bilgi tabanını ilgili bilgi için otomatik olarak arar
• Konuşma geçmişini dikkate alır

2. İşleme

Mind:

• Mesajınızı bağlam içinde analiz eder
• Yanıtları, citation'larla alınan bilgiye dayandırır
• Gerekirse ek tool'lara erişir (web search, görsel üretme, vb.)
• Kişiliğiyle uyumlu bir yanıt formüle eder

3. Yanıt Üretme

Mind:

• Uzmanlığını yansıtan bir yanıt üretir
• Bilgi tabanı veya web kaynakları kullanılırken citation'ları dahil eder
• Opsiyonel meta veri ile (citation'lar, görseller, vb.) mesajı döndürür

Meta Veri

Yanıtlar ek meta veri içerebilir:

Görseller

Bir mind görseller ürettiğinde veya gösterdiğinde:

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

Knowledge Citation'ları

Bir mind bilgi tabanından veya web aramadan bilgi aldığında:

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

Citation Alanları:

• id - Kaynak için benzersiz tanımlayıcı
• displaySource - İnsan tarafından okunabilir kaynak adı veya URL
• similarity - Kaynağın sorguyla ne kadar iyi eşleştiğini gösteren ilgililik skoru (0-1)

Mind'lar yanıt vermeden önce bilgi tabanlarını otomatik olarak arar ve yanıtlarını belirli kaynaklara dayandırırken citation'ları dahil eder.

Erişim Kontrolü

Şu mind'larla sohbet edebilirsiniz:

• Sahip olduklarınız - Oluşturduğunuz mind'lar
• Erişiminiz olanlar - Ekip üyeleri tarafından sizinle paylaşılan mind'lar
• Üyesi olduğunuz - Ait olduğunuz ekip workspace'lerindeki mind'lar
• Public mind'lar - Herkese açık mind'lar

Yetkisiz mind'lara erişim girişimi şunu döndürür:

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

Response Formatları

Metin Yanıtı

Çoğu yanıt düz metindir:

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

Yapılandırılmış Yanıt

Bazı mind'lar yapılandırılmış içerik döndürebilir:

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

Meta Veri ile Boş Yanıt

Bazen yalnızca meta veri döndürülür (örn. görsel üretme için):

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

En İyi Uygulamalar

Spesifik Olun

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

Bağlam Sağlayın

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

Takip Soruları Kullanın

Konuşma belleğinden yararlanın:

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

Bilgiyi Referans Gösterin

Bilgi yüklediyseniz, onu referans gösterin:

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

Error Yanıtları

400 Bad Request

Eksik veya geçersiz spark ID:

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

Desteklenmeyen provider:

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

Provider olmadan belirsiz model adı:

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

401 Unauthorized

Geçersiz API key.

403 Forbidden

Spark'a erişim reddedildi:

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

404 Not Found

Spark mevcut değil:

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

Kullanım Notları

• v1 API kimliği doğrulanmış hesap başına yapılandırılabilir sınır uygular (varsayılan dakikada 300 istek)
• RateLimit-Limit ve RateLimit-Remaining başlıklarını okuyun, 429 sonrasında Retry-After değerine uyun
• Üretim istekleri yoğun olduğundan paralel completion sayısını sınırlayın

Sonraki Adımlar

• latency ve performansı anlayın
• Error'lar ve rate limit'ler hakkında bilgi edinin
• İlk mind'ınızı oluşturun
• Yanıtları geliştirmek için bilgi yükleyin
• API genel bakışını okuyun