Panels API

Panels, AI mind gruplarına sorular yöneltmenizi ve toplu, yapılandırılmış yanıtlar almanızı sağlar. Pazar araştırması simülasyonları, persona tabanlı geri bildirim toplama ve çok perspektifli analizler için idealdir.

Base URL: https://getminds.ai/api/v1 veya https://api.getminds.ai/v1

Kavramlar

Panelleri Listele

Kimliği doğrulanmış kullanıcıya ait tüm panelleri getirir.

Endpoint: GET /api/v1/panels

Headers:

Authorization: Bearer minds_your_api_key

Yanıt

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Consumer Research Panel",
      "flowMode": "panel",
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-10T14:30:00.000Z",
      "messageCount": 8,
      "groups": [
        {
          "id": "group-123",
          "name": "Gen Z Consumers",
          "sparkCount": 5,
          "sparks": [
            {
              "id": "spark-1",
              "name": "Emma",
              "discipline": "College Student",
              "profileImageUrl": "https://..."
            }
          ]
        }
      ]
    }
  ]
}

Yanıt Alanları

Örnek İstek

curl -X GET "https://getminds.ai/api/v1/panels" \
  -H "Authorization: Bearer minds_your_api_key"

Panel Oluştur

İsteğe bağlı mind gruplarıyla yeni bir panel oluşturur.

Endpoint: POST /api/v1/panels

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

İstek Gövdesi

{
  "name": "Product Feedback Panel",
  "groupIds": ["group-123", "group-456"]
}

Parametreler

Yanıt

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Product Feedback Panel",
    "flowMode": "panel",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "groups": [
      {
        "id": "group-123",
        "name": "Early Adopters",
        "sparks": [
          {
            "id": "spark-1",
            "name": "Alex",
            "discipline": "Tech Enthusiast",
            "profileImageUrl": "https://..."
          }
        ]
      }
    ]
  }
}

Örnek İstek

curl -X POST "https://getminds.ai/api/v1/panels" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Market Research Panel",
    "groupIds": ["group-123", "group-456"]
  }'

Hata Yanıtları

400 Bad Request - Eksik ad veya geçersiz group ID'leri

{
  "statusCode": 400,
  "message": "name is required"
}

{
  "statusCode": 404,
  "message": "Groups not found: 1f2e3d4c-..."
}

Panel Detaylarını Getir

Belirli bir paneli tüm grupları ve mesaj geçmişiyle birlikte getirir.

Endpoint: GET /api/v1/panels/{panelId}

Headers:

Authorization: Bearer minds_your_api_key

Yanıt

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Consumer Research Panel",
    "flowMode": "panel",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T14:30:00.000Z",
    "groups": [
      {
        "id": "group-123",
        "name": "Gen Z Consumers",
        "sparks": [
          {
            "id": "spark-1",
            "name": "Emma",
            "discipline": "College Student",
            "profileImageUrl": "https://..."
          }
        ]
      }
    ],
    "messages": [
      {
        "id": "msg-1",
        "role": "user",
        "content": "How important is sustainability when choosing products?",
        "metadata": {
          "groupIds": ["group-123"]
        },
        "createdAt": "2025-12-10T14:00:00.000Z"
      },
      {
        "id": "msg-2",
        "role": "assistant",
        "content": "How important is sustainability when choosing products?",
        "metadata": {
          "outputData": {
            "title": "How important is sustainability when choosing products?",
            "type": "scale",
            "groups": [
              {
                "group": "Gen Z Consumers",
                "value": "Very Important",
                "answers": [
                  {
                    "value": "9/10",
                    "persona": "Emma",
                    "discipline": "College Student",
                    "message": "Sustainability is a top priority for me..."
                  }
                ]
              }
            ]
          },
          "outputType": "bar"
        },
        "createdAt": "2025-12-10T14:00:30.000Z"
      }
    ]
  }
}

Örnek İstek

curl -X GET "https://getminds.ai/api/v1/panels/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer minds_your_api_key"

Hata Yanıtları

403 Forbidden - Bu panele erişim yetkisi yok

404 Not Found - Panel bulunamadı

Panel Sorusu Sor

Paneldeki tüm mind'lara soru gönderir ve toplu sonuçlarla birlikte akış halinde yanıt alır.

Endpoint: POST /api/v1/panels/{panelId}/ask

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

İstek Gövdesi

Temel soru:

{
  "question": "What features would make you switch to a competitor product?",
  "groupIds": ["group-123"]
}

Eklerle birlikte:

{
  "question": "Please review this product design and provide feedback",
  "attachments": [
    {
      "url": "https://example.com/design.pdf",
      "name": "Product Design v2",
      "type": "application/pdf"
    },
    {
      "path": "uploads/mockup.png",
      "name": "UI Mockup"
    }
  ],
  "links": [
    {
      "label": "https://competitor.com/product",
      "id": "link-1"
    }
  ],
  "keywords": [
    {
      "label": "sustainable packaging",
      "url": "https://example.com/article",
      "id": "keyword-1"
    }
  ]
}

Parametreler

Yanıt (Server-Sent Events)

Endpoint, Server-Sent Events (SSE) akışı döndürür. Her event, type alanı içeren bir JSON nesnesidir.

Soru Sınıflandırması

İşlem başlamadan önce sistem sorunuzu otomatik olarak üç türden birine sınıflandırır:

Nitel sorularda yanıtlar otomatik olarak konulara göre kümelenir (örn. "Gizlilik endişeleri", "Maliyet engelleri"). Her yanıtın value alanı, atanan konuyu içerir.

Event Türleri

1. Start Event

{"type": "start", "total": 10}

İşlemin başladığını ve toplam mind sayısını belirtir.

2. Classification Event

{
  "type": "classification",
  "classification": {
    "type": "scale",
    "scaleRange": [1, 5]
  }
}

Sorunun nasıl sınıflandırıldığını gösterir. Ölçek sorularında algılanan aralığı, kategorik sorularda algılanan seçenekleri içerir.

3. Answer Event

{
  "type": "answer",
  "sparkId": "spark-1",
  "sparkName": "Emma",
  "discipline": "College Student",
  "profileImageUrl": "https://...",
  "groupId": "group-123",
  "groupName": "Gen Z Consumers",
  "answer": "4\n\nI think this is a solid product but could improve..."
}

Her mind'ın bireysel yanıtı için gönderilir. Ölçek ve kategorik sorularda yanıt, puan veya seçimle başlar ve ardından gerekçe gelir.

4. Aggregating Event

{"type": "aggregating"}

AI'ın tüm yanıtları toplamaya başladığını belirtir. Nitel sorularda konu kümeleme de bu aşamada gerçekleşir.

5. Result Event

{
  "type": "result",
  "outputData": {
    "title": "What features would make you switch to a competitor product?",
    "type": "categorical",
    "classification": {
      "type": "categorical",
      "options": ["Yes", "No", "Maybe"]
    },
    "groups": [
      {
        "group": "Gen Z Consumers",
        "value": "Better Price",
        "alignmentScore": 82,
        "answers": [
          {
            "value": "Price",
            "persona": "Emma",
            "discipline": "College Student",
            "message": "I would switch if a competitor offered better pricing...",
            "imageUrl": "https://...",
            "reliabilityScore": 84
          }
        ]
      }
    ]
  },
  "outputType": "bar"
}

Sınıflandırılmış yanıtlarla birlikte toplu sonuçları içerir. alignmentScore ve yanıt başına reliabilityScore, v1 endpoint'lerinde sonuç döndürülmeden önce hesaplanır (bkz. Alignment scoring).

6. Done Event

{"type": "done"}

Akışın tamamlandığını belirtir.

Çıktı Veri Yapısı

Yanıt Türleri Açıklaması

Ölçek yanıtları:

• value: Sayısal puan (örn. "4")
• message: Puan için kısa gerekçe
• groups[].value: Grup genelinde ortalama puan

Kategorik yanıtlar:

• value: Seçilen seçenek (örn. "Yes", "Option A")
• message: Seçim için kısa gerekçe
• groups[].value: Grupta en çok seçilen seçenek

Nitel yanıtlar:

• value: Atanan konu/tema (örn. "Privacy concerns", "Cost barriers")
• message: Tam yanıt metni
• groups[].value: Grupta baskın konu
• Konular tüm yanıtlardan otomatik olarak kümelenir (3-6 konu belirlenir)

Alignment scoring

Her panel yanıtı, v1 API yanıtında iki skor içerir:

• groups[].answers[].reliabilityScore (0-100, tam sayı, isteğe bağlı): mind'ın yanıtının kendi systemPrompt'una ne kadar uygun olduğunu gösteren, mind başına skor. Bireysel spark sohbetlerinde kullanılan değerlendiriciyle yeniden hesaplandığından, v1 panel değeri tek mind reliabilityScore değerleriyle doğrudan karşılaştırılabilir.
• groups[].alignmentScore (0-100, tam sayı, isteğe bağlı): o grup için yanıt başına reliabilityScore ortalaması. Arayüz bunu grup başına Alignment göstergesi olarak sunar (High / Medium / Low).

Arayüzün kullandığı etiket bantları (payload'da yer almaz, API tüketicilerinin eşleştirmesi için buraya eklenmiştir):

Alanların atlandığı durumlar: Değerlendirici, mind'ın systemPrompt'u 20 karakterden kısaysa, yanıt mesajı boşsa veya değerlendirici çağrısı başarısız olursa yanıtı atlar. Bir gruptaki tüm yanıtlar atlanırsa o grubun alignmentScore'u da atlanır.

Zamanlama: v1 endpoint'lerinde puanlama, yanıt döndürülmeden önce senkron olarak çalışır; bu nedenle skorlar outputData'nın geri kalanıyla aynı payload'da yer alır. Panel oluşturmanın üzerine birkaç saniyelik gecikme ekler. Alignment olmadan daha hızlı panel sonucu isteyen tüketiciler, satır içi skora güvenmek yerine aşağı akışta toplu değerlendirme yapmalıdır.

Durum: Bu alan, gelecekteki bir grup hizalama metriğinin (ampirik araştırma bulgularına yakınlık) geçici bir yerini tutucusudur. Alan adları korunacaktır; alignmentScore'un semantiği değişebilir.

File Attachments

Panel sorularına bağlam sağlamak için dosya, bağlantı ve anahtar kelime ekleyebilirsiniz. Mind'lar yanıt vermeden önce işlenmiş içeriği alır.

Ek Türleri

1. Dosya Ekleri (attachments)

Analiz için belge, PDF, görsel ve elektronik tablo yükleyin:

{
  "question": "What improvements would you suggest for this product spec?",
  "attachments": [
    {
      "url": "https://example.com/product-spec.pdf",
      "name": "Product Specification v2.1",
      "type": "application/pdf"
    },
    {
      "path": "uploads/user-research.docx",
      "name": "User Research Findings"
    }
  ]
}

Desteklenen formatlar:

• Belgeler: PDF, DOCX, TXT, MD
• Görseller: PNG, JPG, WEBP (OCR ile)
• Elektronik tablolar: CSV, XLSX

Dosya kaynakları:

• url: Harici URL (indirilip işlenir)
• path: Supabase depolama yolu (otomatik imzalanıp işlenir)

2. Bağlantı Ekleri (links)

Web sayfalarını getirip analiz edin (JS ağırlıklı siteler için Firecrawl ve ekran görüntüsü kullanır):

{
  "question": "Compare our pricing to these competitors",
  "links": [
    { "label": "https://competitor-a.com/pricing", "id": "link-1" },
    { "label": "https://competitor-b.com/pricing", "id": "link-2" }
  ]
}

Özellikler:

• JavaScript render (Firecrawl)
• Görsel bağlam için ekran görüntüsü
• Markdown çıkarımı
• Otomatik içerik kısaltma (birden fazla bağlantıda bağlantı başına 3000 karakter, tek bağlantıda 15000)

3. Anahtar Kelime Bağlamı (keywords)

Ek bağlam için kaynak URL'leriyle anahtar kelimeler sağlayın:

{
  "question": "How can we improve sustainability?",
  "keywords": [
    {
      "label": "circular economy",
      "url": "https://en.wikipedia.org/wiki/Circular_economy",
      "id": "kw-1"
    },
    {
      "label": "carbon neutral packaging",
      "url": "https://example.com/carbon-neutral-guide",
      "id": "kw-2"
    }
  ]
}

Eklerle Birlikte Tam Örnek

curl -X POST "https://getminds.ai/api/v1/panels/panel-id/ask" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Based on this product design and competitor analysis, what features should we prioritize?",
    "groupIds": ["product-managers", "designers"],
    "attachments": [
      {
        "url": "https://example.com/product-design-v3.pdf",
        "name": "Product Design v3",
        "type": "application/pdf"
      }
    ],
    "links": [
      { "label": "https://competitor.com/features" }
    ],
    "keywords": [
      {
        "label": "user experience best practices",
        "url": "https://uxdesign.com/best-practices"
      }
    ]
  }'

İşleme süreci:

• Dosyalar paralel olarak analiz edilir (PDF'ler metin çıkarımı, görseller OCR/vision)
• Bağlantılar Firecrawl ile getirilir (JS render ve ekran görüntüsü)
• İçerik tüm mind'lar için soru bağlamına eklenir
• Başarısız ekler, yedek mesajlarla sorunsuz şekilde yönetilir

İpuçları:

• Yalnızca ilgili dosyaları ekleyin (her biri işleme süresi ekler)
• Dinamik web içeriği için bağlantı kullanın
• Ek web bağlamı için anahtar kelime kullanın
• Dosya işleme zaman aşımı: dosya başına 30 saniye
• Bağlantı getirme zaman aşımı: URL başına 15 saniye

Örnek İstek

curl -X POST "https://getminds.ai/api/v1/panels/550e8400-e29b-41d4-a716-446655440000/ask" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "On a scale of 1-10, how likely are you to recommend this product?"
  }'

Örnek: JavaScript EventSource

const eventSource = new EventSource(
  'https://getminds.ai/api/v1/panels/{panelId}/ask',
  {
    headers: {
      'Authorization': 'Bearer minds_your_api_key',
      'Content-Type': 'application/json'
    }
  }
);

// Not: SSE ile POST istekleri için fetch ve ReadableStream kullanın
const response = await fetch('https://getminds.ai/api/v1/panels/{panelId}/ask', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer minds_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    question: 'How satisfied are you with the current pricing?'
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6));
      console.log('Event:', event.type, event);
    }
  }
}

Hata Yanıtları

400 Bad Request - Eksik soru veya panele bağlı grup yok

{
  "statusCode": 400,
  "message": "question is required"
}

{
  "statusCode": 400,
  "message": "No groups attached to this panel"
}

{
  "statusCode": 400,
  "message": "No minds in panel groups"
}

403 Forbidden - Bu panele erişim yetkisi yok

404 Not Found - Panel bulunamadı

Model Override

Varsayılan olarak panel yanıtları, yapılandırılmış ve uygun ise takımınızın tercih ettiği sağlayıcıyı; aksi halde ürün varsayılanını kullanır. Model ailelerinde deney yapmak için istek bazında model ve sağlayıcıyı geçersiz kılabilirsiniz:

curl -X POST "https://getminds.ai/api/v1/panels/{panelId}/ask" \
  -H "Authorization: Bearer minds_…_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Rate this 1-5",
    "model": "gpt-4o",
    "provider": "openai"
  }'

Desteklenen sağlayıcılar: openai, anthropic, google. Panel isteklerinde model ve provider birlikte gönderilmelidir. Yalnızca biri gönderilirse API 400 Bad Request döndürür. İstek bazında override, takım sağlayıcı tercihinden önce gelir.

Çeşitlilik Kontrolünü Devre Dışı Bırakma

Panel orkestratörü, agregasyondan önce çeşitlilik zorunlu yeniden oluşturma döngüsü çalıştırır (bigram öz-benzerlik kontrolü, değer homojenliği tespiti, boş kova doldurma). Bu, panel tarifinin L4 katmanıdır.

Bu katmanın katkısını izole etmek istediğiniz ablasyon çalışmaları ve kıyaslama testleri için disableDiversityCheck: true parametresini geçin:

curl -X POST "https://getminds.ai/api/v1/panels/{panelId}/ask" \
  -H "Authorization: Bearer minds_…_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What features matter most to you?",
    "disableDiversityCheck": true
  }'

Bu bayrak etkinleştirildiğinde panelistlerin yanıtları, başlangıçta oluşturulduğu haliyle döndürülür. Yanıtlar yoğun biçimde örtüşse bile ikinci geçiş yeniden oluşturma tetiklenmez. Sınıflandırma (L3), spark başına RAG (L2) ve agregasyon (L5) normal şekilde çalışmaya devam eder. Maliyet tasarrufu: çeşitlilik kontrolünün işaretleyeceği spark sayısına bağlı olarak panel sorusu başına yaklaşık %5-25 daha az LLM çağrısı.

Ne zaman kullanılır: Yöntem karşılaştırmaları, orkestrasyon katmanlarının A/B testleri, temel davranışı yeniden üretme. Üretim panellerinde bu seçenek kapalı bırakılmalıdır (varsayılan).

Panel Sonuçlarını Dışa Aktar

Tüm panel sonuçlarının Markdown formatında yapılandırılmış raporunu oluşturur.

Endpoint: POST /api/v1/panels/{panelId}/export

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

İstek Gövdesi

{
  "format": "md"
}

Parametreler

Yanıt

{
  "data": {
    "format": "md",
    "content": "# Panel Report: Consumer Research Panel\n\n## Executive Summary\n\nThis panel survey gathered insights from 15 participants across 3 consumer groups...\n\n## Methodology\n\n- 3 groups, 15 participants\n- 5 questions asked\n\n## Results by Question\n\n### Q1: How important is sustainability when choosing products?\n\n**Type:** scale\n\n#### Gen Z Consumers (dominant: Very Important)\n\n..."
  }
}

Rapor Yapısı

Oluşturulan rapor şunları içerir:

1. Executive Summary - Temel bulgulara genel bakış (2-3 paragraf)
2. Methodology - Gruplar, katılımcılar ve yapı
3. Results by Question - Temel içgörüler ve alıntılarla gruplar arası karşılaştırma
4. Cross-Group Analysis - Gruplar genelindeki örüntüler ve eğilimler
5. Conclusions & Recommendations - Uygulanabilir içgörüler

Örnek İstek

curl -X POST "https://getminds.ai/api/v1/panels/550e8400-e29b-41d4-a716-446655440000/export" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "md"
  }'

Hata Yanıtları

403 Forbidden - Bu panele erişim yetkisi yok

404 Not Found - Panel bulunamadı

Dışa Aktarma Durumunu Kontrol Et

Panel dışa aktarma işinin durumunu kontrol eder. jobId sağlanmazsa en son dışa aktarma işinin durumunu döndürür.

Endpoint: GET /api/v1/panels/{panelId}/export-status

Headers:

Authorization: Bearer minds_your_api_key

Sorgu Parametreleri

Yanıt

{
  "data": {
    "status": "completed",
    "downloadUrl": "/api/v1/panels/{panelId}/export-download?jobId=job-123"
  }
}

Durum Değerleri

Örnek İstek

curl -X GET "https://getminds.ai/api/v1/panels/{panelId}/export-status?jobId=job-123" \
  -H "Authorization: Bearer minds_your_api_key"

Hata Yanıtları

403 Forbidden - Bu panele erişim yetkisi yok

404 Not Found - Panel veya iş bulunamadı

Dışa Aktarmayı İndir

Dışa aktarılan panel raporunu PDF dosyası olarak indirir.

Endpoint: GET /api/v1/panels/{panelId}/export-download

Headers:

Authorization: Bearer minds_your_api_key

Sorgu Parametreleri

Yanıt

Uygun başlıklarla birlikte PDF dosyası döndürür:

• Content-Type: application/pdf
• Content-Disposition: attachment; filename="Panel-Report.pdf"

Örnek İstek

curl -X GET "https://getminds.ai/api/v1/panels/{panelId}/export-download?jobId=job-123" \
  -H "Authorization: Bearer minds_your_api_key" \
  -o panel-report.pdf

Hata Yanıtları

400 Bad Request - Eksik jobId parametresi veya iş henüz tamamlanmadı

403 Forbidden - Bu panele erişim yetkisi yok

404 Not Found - Panel veya iş bulunamadı

İş Akışı Örneği

Panel oluşturma ve kullanma için eksiksiz bir iş akışı:

# 1. Önce spark grupları oluşturun (Sparks API kullanarak)
# group-genz ve group-millennials ID'leriyle gruplar oluşturduğunuzu varsayın

# 2. Bu gruplarla bir panel oluşturun
curl -X POST "https://getminds.ai/api/v1/panels" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Pricing Research",
    "groupIds": ["group-genz", "group-millennials"]
  }'

# Yanıt: { "data": { "id": "panel-123", ... } }

# 3. Panele soru sorun
curl -X POST "https://getminds.ai/api/v1/panels/panel-123/ask" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What price point would you consider fair for this product?"
  }'

# 4. Başka bir soru sorun
curl -X POST "https://getminds.ai/api/v1/panels/panel-123/ask" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How does this compare to competitor pricing?"
  }'

# 5. Sonuçları rapor olarak dışa aktarın
curl -X POST "https://getminds.ai/api/v1/panels/panel-123/export" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"format": "md"}'

# 6. Dışa aktarma durumunu kontrol edin (tamamlanana kadar sorgulayın)
curl -X GET "https://getminds.ai/api/v1/panels/panel-123/export-status" \
  -H "Authorization: Bearer minds_your_api_key"

# Yanıt: { "data": { "status": "completed", "downloadUrl": "/api/v1/panels/panel-123/export-download?jobId=..." } }

# 7. PDF'i indirin
curl -X GET "https://getminds.ai/api/v1/panels/panel-123/export-download?jobId=job-123" \
  -H "Authorization: Bearer minds_your_api_key" \
  -o panel-report.pdf

Hata Kodları Özeti

Sonraki Adımlar

• Panel gruplarını doldurmak için mind oluşturun
• Kimlik doğrulama hakkında bilgi edinin
• Hatalar ve limitler sayfasını inceleyin