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

Tam olarak bir boş olmayan seçim yapın: mindId, mindIds veya audienceIds. Karışık seçimler 400 döndürür; boş bir isteğe bağlı dizi tek Mind seçimini geçersiz kılmaz. UUID harf büyüklüğü önemli değildir ve yinelenen kimlikler yok sayılır. Sohbet oluşturma, kaçış karakterleri dahil en fazla 1 MiB JSON kabul eder. Daha büyük istekler veritabanı veya plan hakkı işlemlerinden önce 413 döndürür. Yanıtlar özeldir ve önbelleğe alınmaz.

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body:

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

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

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

Tek veya çok Mind içeren sohbetler, her Mind’ın kayıtlı knowledge_only politikasına ve çalışma alanının web araştırması kısıtlamalarına uyar. Kısıtlı Mind mevcut soruyu, eğitilmiş personasını ve getirilen ilgili Mind bilgisini kullanır; dahili araçlar, istemci araçları, önceki sohbet bağlamı ve kopyalanmış Study kaynakları yanıt bağlamına dahil edilmez. İlgili kanıt getirildiğinde yanıtta metadata.knowledgeRetrieval.status değeri grounded, kanıt bulunmadığında veya getirme başarısız olduğunda fallback olur. Çok Mind içeren yanıtlarda bu durum her messages[] öğesinin metadata alanında ayrı ayrı bildirilir.

Çalışma alanının web araştırması izni knowledge_only politikasından ayrıdır: izin kapatıldığında web araması ve bağlantı analizi araçları kaldırılır, ancak auto kullanan Minds için sağlanan materyal ve konuşma geçmişi korunur. Yukarıdaki kısıtlı yanıt bağlamı, knowledge_only kullanan Minds için geçerlidir.

Artımlı bellek, kopyalanan Study bağlamı değişince kayabilecek bir konum yerine son kapsanan mesajın ID’sinden sonra devam eder. Üretilen özet satırları konuşma turlarına dahil edilmez; sahibin yazdığı sistem notları v1 sohbetlerinde kullanılabilir. Başka bir istek temel alınan kayıtlı özeti değiştirmişse arka plan sonucu kaydedilmez.

Artımlı özetleme başarısız olursa veya anlatı metni döndürmezse, yedek işlem önceki özeti ve geçerli kayıtlı bilgileri korur, ardından yeni konuşma bölümünün kısa bir dökümünü ekler. Yedek işlem her güncellemede yeni kapsanan en fazla 30 mesajdan alıntı içerir ve yalnızca bu mesajlara kadar ilerler. Kalan mesajlar sonraki güncellemeler için bekler. İstek sıkıştırması, kapsanan alıntıları yinelememek için kayıtlı mesaj kimliğini kullanırken son mesajları, öncelikli kanıtları ve kopyalanmış Study bağlamını korur.

Moderatör katılımcıları Mind ID ile tanımlar. Görünen adları aynı olan Minds ayrı adaylar olarak kalır; tur sınırları ve art arda konuşma kontrolleri ID bazında uygulanır. Moderatör, her Mind yanıt vermeden tartışmayı sonlandırabilir.

Beklenmeyen üretim hataları sağlayıcı ayrıntıları olmadan genel bir 500 döndürür; başarısız yanıtlar için ayrılan birimlerin iadesi istenir. Önceden üretilen yanıtlar ve kaydedilen mesajlar geri alınmaz. Model yeteneği nedeniyle açık ret, data.errorType: "unsupported_model_capability" ile 400 olarak kalır. Çok Mind’lı sohbetlerde isteğe bağlı arka plan özetleme, kaydedilmiş yanıtı geciktirmez veya hataya dönüştürmez.

Mesaj isteklerinde de 1 MiB JSON sınırı vardır; aşan istekler veritabanı veya plan hakkı işlemlerinden önce 413 döndürür. Yanıtlar özeldir ve önbelleğe alınmaz. Yalnızca sohbet sahibi yazabilir. Yönetilen çalışma alanları her istekte mevcut çalışma alanını ve bağlı Mind/Audience izinlerini yeniden doğrular; iptal edilen erişim kayıt veya ücretlendirmeden önce 404 döndürür.

Aşağıdaki yanıt örneği tek Mind içindir. Çok Mind’lı sohbetler messages[], Study sohbetleri outputData döndürür. Üretim veya mesaj kotası kullanımı olmadan bağlam notu kaydetmek için role: "system" kullanın; yanıt { messageId, role: "system" } olur.

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", "mindId": "your-mind-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
• Geçmişi uzun olan tek Mind sohbetlerinde en son 8 mesaj tam içerikle korunur
• Eski turlar, varsa kayıtlı özeti ve henüz kapsanmayan mesajların alıntılarını kullanır
• Özetler ayrıntı kaybeder; çok uzun geçmişler veya büyük mesajlar yine de modelin bağlam sınırlarına ulaşabilir.

Sohbet silme

DELETE /api/v1/chats/{chatId}

Yalnızca sahibi sohbeti ve mesajlarını kalıcı olarak silebilir. Minds ve Audiences korunur. Başarılı yanıt gövdesiz 204 döndürür; JSON olarak ayrıştırmayın. Eksik veya geçersiz kimlik bilgileri 401, başka birine ait sohbet 403, bulunamayan sohbet ise 404 döndürür. Son yazma işleminden önce silinen veya devredilen sohbet de 404 döndürür. Yanıtlarda Cache-Control: private, no-store kullanılır.

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/minds/{mindId}/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": "Mind knowledge",
        "similarity": 0.89
      }
    ]
  }
}

Tek Mesaj Örneği

Tek bir soru sorun:

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

Çok-Turlu Konuşma

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

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

Ç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:

Durumsuz completion isteklerinde kendi yüklediğiniz dosyayı, geçerli imzalı bir sohbet dosyası URL’sini veya yükleyenin Study’si üzerinden paylaşılan bağlamı kullanın. Yetkisiz çalışma alanı dosyaları 403 Upload access denied döndürür (akış modunda hata olayı olarak). Harici HTTP(S) URL’leri kendi erişim belirtecini korur; rastgele bir depolama yolu yeniden imzalanmaz. Örneklerdeki your-user-id değerini kendi kullanıcı kimliğinizle değiştirin ve yükleme uç noktasının döndürdüğü yolu kullanın.

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

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": "chat/your-user-id/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/minds/mind-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/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 belirtilmediğinde sunucu varsayılanı kullanılır.

Provider'lar

Yukarıda listelenen modellerden birini geçirin. Kullanımdan kaldırılan ID'ler yönlendirilir (aşağıya bakın); diğer tüm modeller 400 Bad Request döndürür. Provider, yaygın model adı önekleriyle otomatik olarak tespit edilir (claude- → Anthropic, gemini- → Google, gpt-/o1/o3/o4 → OpenAI).

Your own model

Fine-tune edilmiş veya kendi barındırdığınız bir modeli çalıştırmak için bir ekip yöneticisi onu ekip model bağlantısı olarak ekler (OpenAI Chat Completions, OpenAI Responses veya Anthropic Messages protokolü) ve doğrular. Ardından model ve provider yerine bağlantının ID'sini ve güncel sürümünü gönderin:

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

GET /api/v1/model-connections, ekibinizin bağlantılarını sürümleri ve doğrulanmış yetenekleriyle listeler. Bağlantı metin ve streaming gerektirir; response_format gönderdiğinizde yapılandırılmış çıktı, istek araç kullandığında ise araç çağrısı da gerekir. Uç noktanız başarısız olursa istek de başarısız olur: Minds hiçbir zaman kendi modellerinden birine geçmez. Görseller ve diğer medya MODEL_CONNECTION_MEDIA_UNVERIFIED ile reddedilir. Stateful chat mesajları (/chats/{chatId}/messages) bağlantı kabul etmez.

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

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

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

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\": {...}}"
}

Araç sonuçları, tool_calls alanını içeren ilgili asistan mesajından sonra gelmelidir. Döndürülen çağrı kimliğini ve adını kullanın ve her sonucu yalnızca bir kez gönderin. Bozuk argümanlar, bilinmeyen çağrı kimlikleri, eşleşmeyen araç adları yinelenen sonuçlar ve eksik istemci sonuçları üretimden önce 400 döndürür.

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/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
  }'

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": "Mind 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 Mind ID:

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

Mind'a erişim reddedildi:

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

404 Not Found

Mind mevcut değil:

{
  "statusCode": 404,
  "statusMessage": "Mind 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