---
title: "Chat API"
description: "Chat completion'lar ve çok-turlu konuşmalar aracılığıyla mind'larınızla etkileşim kurun."
---

# 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:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

**Request Body:**

```json
{
  "name": "My Conversation",
  "sparkId": "your-mind-id"
}
```

<table>
<thead>
  <tr>
    <th>
      Parametre
    </th>
    
    <th>
      Tür
    </th>
    
    <th>
      Zorunlu
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Chat için görünen ad (varsayılan: "API Chat")
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sparkId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Sohbet edilecek mind. Atlanırsa, daha sonra bir mind atayın.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Opsiyonel açıklama
    </td>
  </tr>
</tbody>
</table>

**Response (201):**

```json
{
  "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:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

**Request Body:**

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

<table>
<thead>
  <tr>
    <th>
      Parametre
    </th>
    
    <th>
      Tür
    </th>
    
    <th>
      Zorunlu
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Evet
      </strong>
    </td>
    
    <td>
      Mesaj metni (alternatif olarak <code>
        message
      </code>
      
       kullanın)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Bu mesaj için kullanılan AI modelini geçersiz kılar. <code>
        provider
      </code>
      
       ile birlikte gönderilmelidir.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        provider
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Model override için AI sağlayıcısı: <code>
        openai
      </code>
      
      , <code>
        anthropic
      </code>
      
       veya <code>
        google
      </code>
      
      . <code>
        model
      </code>
      
       ile birlikte gönderilmelidir.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        endUserName
      </code>
    </td>
    
    <td>
      string|null
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Bu istek için gerçek son kullanıcının opsiyonel görünen adı. Atlanırsa, <code>
        null
      </code>
      
       ise veya boşsa, Minds kullanıcıya nötr şekilde hitap eder ve API key ya da hesap sahibinden ad çıkarımı yapmaz. Alias: <code>
        userDisplayName
      </code>
      
      , <code>
        userName
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

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

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

<table>
<thead>
  <tr>
    <th>
      Alan
    </th>
    
    <th>
      Tür
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Mind'ın yanıtı
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messageId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Kaydedilen mesajın benzersiz ID'si
    </td>
  </tr>
</tbody>
</table>

### Çok-Turlu Örnek

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

```bash
# 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-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
- 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/minds/{mindId}/completion`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### Request Body

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

### Parametreler

<table>
<thead>
  <tr>
    <th>
      Parametre
    </th>
    
    <th>
      Tür
    </th>
    
    <th>
      Zorunlu
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        messages
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Mesaj objeleri dizisi (<code>
        user
      </code>
      
      , <code>
        assistant
      </code>
      
       veya <code>
        tool
      </code>
      
      ). Atlanması veya boş dizi, mind'tan persona'ya uygun bir selamlama döndürür.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messages[].role
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Evet
      </strong>
    </td>
    
    <td>
      <code>
        "user"
      </code>
      
      , <code>
        "assistant"
      </code>
      
       veya <code>
        "tool"
      </code>
      
       değerlerinden biri
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messages[].content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Evet
      </strong>
    </td>
    
    <td>
      Mesaj metni (<code>
        tool
      </code>
      
       rolü için atlayın, bunun yerine <code>
        tool_call_id
      </code>
      
       + <code>
        content
      </code>
      
       kullanın)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Bu istek için kullanılan AI modelini geçersiz kılın. Aşağıdaki <a href="#model-override">
        model override
      </a>
      
      'a bakın.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        provider
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Model override için AI provider'ı: <code>
        openai
      </code>
      
      , <code>
        anthropic
      </code>
      
       veya <code>
        google
      </code>
      
      . Model adından mümkün olduğunda otomatik tespit edilir.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        endUserName
      </code>
    </td>
    
    <td>
      string|null
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Bu istek için gerçek son kullanıcının opsiyonel görünen adı. Atlanırsa, <code>
        null
      </code>
      
       ise veya boşsa, Minds kullanıcıya nötr şekilde hitap eder ve API key ya da hesap sahibinden ad çıkarımı yapmaz. Alias: <code>
        userDisplayName
      </code>
      
      , <code>
        userName
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        language
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Yanıt dili için ipucu. Desteklenenler: <code>
        en
      </code>
      
      , <code>
        de
      </code>
      
      , <code>
        es
      </code>
      
      , <code>
        fr
      </code>
      
      , <code>
        zh
      </code>
      
      , <code>
        tr
      </code>
      
      , <code>
        ar
      </code>
      
      , <code>
        ja
      </code>
      
      , <code>
        ko
      </code>
      
      . Güçlü persona'lar (örn. sabit bir ana dile sahip kamu figürlerinin klonları) kendi persona dillerinde yanıt vermeye devam edebilir.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        generateImage
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      <code>
        true
      </code>
      
       olduğunda, bağlamsal olarak uygunsa yanıt içinde AI görsel oluşturmayı etkinleştirir
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        response_format
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Yapılandırılmış çıktı iste. Aşağıdaki <a href="#structured-output">
        structured output
      </a>
      
      'a bakın.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tools
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Kullanıcı tanımlı tool tanımları dizisi. Aşağıdaki <a href="#tool-calling">
        tool calling
      </a>
      
      'e bakın.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_choice
      </code>
    </td>
    
    <td>
      string|object
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Tool calling davranışını kontrol eder. <a href="#tool-choice-modes">
        Tool choice modları
      </a>
      
      'na bakın.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parallel_tool_calls
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Turn başına birden fazla tool call'a izin verir (varsayılan: <code>
        true
      </code>
      
      ).
    </td>
  </tr>
</tbody>
</table>

### Response

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

<table>
<thead>
  <tr>
    <th>
      Alan
    </th>
    
    <th>
      Tür
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        messageId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Takip için benzersiz mesaj tanımlayıcısı
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Mind'ın yanıt metni (yapılandırılmış çıktı kullanıldığında JSON string)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parsed
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Ayrıştırılmış JSON objesi (yalnızca <code>
        response_format
      </code>
      
       kullanıldığında bulunur)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_calls
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Tool call istekleri dizisi (yalnızca kullanıcı tanımlı tool'lar çağrıldığında bulunur). Her birinde: <code>
        id
      </code>
      
      , <code>
        name
      </code>
      
      , <code>
        arguments
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Opsiyonel meta veri (citation'lar, görseller)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata.ragCitations
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Yanıtta kullanılan bilgi kaynakları ve web arama sonuçları
    </td>
  </tr>
</tbody>
</table>

## Tek Mesaj Örneği

Tek bir soru sorun:

```bash
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:

```bash
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:

```bash
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": "uploads/meeting-notes.docx",
              "name": "Strategy Meeting Notes"
            }
          ]
        }
      }
    ]
  }'
```

### Ek Formatı

Her ek objesi şunları destekler:

<table>
<thead>
  <tr>
    <th>
      Alan
    </th>
    
    <th>
      Tür
    </th>
    
    <th>
      Zorunlu
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır*
    </td>
    
    <td>
      Dosyaya harici URL (HTTP/HTTPS)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        path
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır*
    </td>
    
    <td>
      Supabase storage path (otomatik imzalı)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Dosya için görünen ad
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      MIME type (örn. <code>
        application/pdf
      </code>
      
      , <code>
        image/png
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Opsiyonel açıklama
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transcription
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Önceden transkribe edilmiş ses/video içeriği
    </td>
  </tr>
</tbody>
</table>

**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

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```bash
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:

```json
{
  "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.

```bash
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-4o-mini"
  }'
```

`model` belirtilmediğinde sunucu varsayılanı kullanılır.

### Provider'lar

<table>
<thead>
  <tr>
    <th>
      Provider
    </th>
    
    <th>
      Değer
    </th>
    
    <th>
      Örnek Modeller
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      OpenAI
    </td>
    
    <td>
      <code>
        openai
      </code>
    </td>
    
    <td>
      <code>
        gpt-5.6-sol
      </code>
      
      , <code>
        gpt-5.6-terra
      </code>
      
      , <code>
        gpt-5.6-luna
      </code>
      
      , <code>
        gpt-5.4
      </code>
      
      , <code>
        gpt-5-mini
      </code>
      
      , <code>
        gpt-4o
      </code>
      
      , <code>
        gpt-4o-mini
      </code>
      
      , <code>
        o3
      </code>
      
      , <code>
        o3-pro
      </code>
      
      , <code>
        o3-mini
      </code>
      
      , <code>
        o4-mini
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Anthropic
    </td>
    
    <td>
      <code>
        anthropic
      </code>
    </td>
    
    <td>
      <code>
        claude-fable-5
      </code>
      
      , <code>
        claude-opus-5
      </code>
      
      , <code>
        claude-sonnet-5
      </code>
      
      , <code>
        claude-haiku-4-5-20251001
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Google
    </td>
    
    <td>
      <code>
        google
      </code>
    </td>
    
    <td>
      <code>
        gemini-3.7-flash
      </code>
      
      , <code>
        gemini-3.5-flash-lite
      </code>
    </td>
  </tr>
</tbody>
</table>

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:

```json
{
  "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:

```bash
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:

```json
{
  "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:

```bash
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

<table>
<thead>
  <tr>
    <th>
      Tür
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      Varsayılan metin çıktısı (mevcut davranış)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        json_object
      </code>
    </td>
    
    <td>
      Şema doğrulaması olmadan geçerli JSON çıktısını zorlar
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        json_schema
      </code>
    </td>
    
    <td>
      Sağlanan şemaya uyan JSON çıktısını zorlar
    </td>
  </tr>
</tbody>
</table>

### JSON Schema Alanları

<table>
<thead>
  <tr>
    <th>
      Alan
    </th>
    
    <th>
      Tür
    </th>
    
    <th>
      Zorunlu
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Evet
      </strong>
    </td>
    
    <td>
      Şema için tanımlayıcı
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Şemanın neyi temsil ettiğinin açıklaması
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        schema
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      <strong>
        Evet
      </strong>
    </td>
    
    <td>
      JSON Schema tanımı
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        strict
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Hayır
    </td>
    
    <td>
      Katı şema uyumunu zorla (varsayılan: <code>
        true
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

### 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:**

```bash
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:**

```json
{
  "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:**

```bash
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:**

```json
{
  "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:

```json
{
  "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:**

<table>
<thead>
  <tr>
    <th>
      Alan
    </th>
    
    <th>
      Tür
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Fonksiyon adı. Benzersiz olmalı ve dahili tool'larla çakışmamalıdır.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Tool'un ne yaptığının ve ne zaman kullanılacağının açık açıklaması. Bu, mind'ın tool seçimini yönlendirir.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parameters
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Fonksiyon argümanlarını tanımlayan JSON Schema.
    </td>
  </tr>
</tbody>
</table>

**Opsiyonel alanlar:**

<table>
<thead>
  <tr>
    <th>
      Alan
    </th>
    
    <th>
      Tür
    </th>
    
    <th>
      Varsayılan
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        strict
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Argümanlar için katı şema doğrulamasını zorla.
    </td>
  </tr>
</tbody>
</table>

### Tool Choice Modları

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

<table>
<thead>
  <tr>
    <th>
      Değer
    </th>
    
    <th>
      Davranış
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        "auto"
      </code>
    </td>
    
    <td>
      Mind, tool'ları çağırıp çağırmayacağına karar verir (varsayılan)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        "required"
      </code>
    </td>
    
    <td>
      Mind, yanıt vermeden önce en az bir tool çağırmalıdır
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        "none"
      </code>
    </td>
    
    <td>
      Bu turn için tool calling'i devre dışı bırakır
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        {"name": "tool_name"}
      </code>
    </td>
    
    <td>
      Mind'ı belirli bir tool'u çağırmaya zorlar
    </td>
  </tr>
</tbody>
</table>

**Örnekler:**

```json
// 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:

```json
{
  "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:

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

### Tool Mesaj Formatı

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

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

<table>
<thead>
  <tr>
    <th>
      Alan
    </th>
    
    <th>
      Tür
    </th>
    
    <th>
      Zorunlu
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        role
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Evet
      </strong>
    </td>
    
    <td>
      <code>
        "tool"
      </code>
      
       olmalıdır
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_call_id
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Evet
      </strong>
    </td>
    
    <td>
      Asistan yanıtındaki tool call'dan gelen <code>
        id
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Evet
      </strong>
    </td>
    
    <td>
      Tool yürütme sonucu (tipik olarak JSON string)
    </td>
  </tr>
</tbody>
</table>

### Dahili vs Kullanıcı Tool'ları

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

<table>
<thead>
  <tr>
    <th>
      Dahili Tool
    </th>
    
    <th>
      Amaç
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET_SPARK_RAG
      </code>
    </td>
    
    <td>
      Mind'ın bilgi tabanında arama
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        WEB_SEARCH
      </code>
    </td>
    
    <td>
      Web'de arama
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GENERATE_IMAGE
      </code>
    </td>
    
    <td>
      AI ile görsel oluşturma
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DISPLAY_IMAGE
      </code>
    </td>
    
    <td>
      Mind'ın belleğinden görsel gösterme
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DOCUMENT_PROCESSING
      </code>
    </td>
    
    <td>
      Yüklenmiş dosyaları analiz etme
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ANALYZE_LINK
      </code>
    </td>
    
    <td>
      Web URL'lerini getirme ve analiz etme
    </td>
  </tr>
</tbody>
</table>

**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'ı:

```bash
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:**

```json
{
  "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.```json
❌ "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.```json
"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**:```json
"status": {
  "type": "string",
  "enum": ["pending", "active", "closed", "archived"]
}
```
4. **Doğrulama kısıtlamalarını ayarlayın**:```json
"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:```json
{
  "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:```json
{
  "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:**

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

## Response Formatları

### Metin Yanıtı

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

```json
{
  "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:

```json
{
  "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):

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

## En İyi Uygulamalar

### Spesifik Olun

```text
❌ "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

```text
✅ "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:

```text
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:

```text
✅ "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:

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

Desteklenmeyen provider:

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

Provider olmadan belirsiz model adı:

```json
{
  "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:

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

### 404 Not Found

Mind mevcut değil:

```json
{
  "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ı](/docs/api/latency) anlayın
- [Error'lar ve rate limit'ler](/docs/api/errors) hakkında bilgi edinin
- İlk [mind](/docs/api/minds)'ınızı oluşturun
- Yanıtları geliştirmek için [bilgi](/docs/api/knowledge) yükleyin
- [API genel bakışını](/docs/api/overview) okuyun