Panels API

Panels ermöglichen es, Gruppen von KI-Minds mit Fragen zu befragen und aggregierte, strukturierte Antworten zu erhalten. Das ist nützlich für Marktforschungssimulationen, persona-basiertes Feedback und Mehrperspektiven-Analysen.

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

Konzepte

Panels auflisten

Alle Panels des authentifizierten Nutzers abrufen.

Endpoint: GET /api/v1/panels

Headers:

Authorization: Bearer minds_your_api_key

Antwort

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

Antwortfelder

Beispielanfrage

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

Panel erstellen

Ein neues Panel mit optionalen Mind-Gruppen erstellen.

Endpoint: POST /api/v1/panels

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

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

Parameter

Antwort

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

Beispielanfrage

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

Fehlerantworten

400 Bad Request - Fehlender Name oder ungültige Gruppen-IDs

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

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

Panel-Details abrufen

Ein bestimmtes Panel mit allen Gruppen und dem Nachrichtenverlauf abrufen.

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

Headers:

Authorization: Bearer minds_your_api_key

Antwort

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

Beispielanfrage

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

Fehlerantworten

403 Forbidden - Kein Zugriff auf dieses Panel

404 Not Found - Panel existiert nicht

Panel-Frage stellen

Eine Frage an alle Minds im Panel senden und Streaming-Antworten mit aggregierten Ergebnissen erhalten.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

Einfache Frage:

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

Mit Anhängen:

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

Parameter

Antwort (Server-Sent Events)

Der Endpoint gibt einen Stream von Server-Sent Events (SSE) zurück. Jedes Event ist ein JSON-Objekt mit einem type-Feld.

Fragenklassifizierung

Vor der Verarbeitung klassifiziert das System die Frage automatisch in einen von drei Typen:

Bei qualitativen Fragen werden Antworten automatisch in Themen geclustert (z.B. "Datenschutzbedenken", "Kostenbarrieren"). Das value-Feld jeder Antwort enthält das zugewiesene Thema.

Event-Typen

1. Start Event

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

Signalisiert den Beginn der Verarbeitung mit der Gesamtanzahl der Minds.

2. Classification Event

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

Zeigt an, wie die Frage klassifiziert wurde. Bei Skalenfragen wird der erkannte Bereich angegeben, bei kategorialen Fragen die erkannten Optionen.

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

Wird für die individuelle Antwort jedes Minds gesendet. Bei Skalen- und kategorialen Fragen beginnt die Antwort mit der Bewertung bzw. Auswahl, gefolgt von der Begründung.

4. Aggregating Event

{"type": "aggregating"}

Zeigt an, dass die KI jetzt alle Antworten aggregiert. Bei qualitativen Fragen umfasst das das Themen-Clustering.

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

Enthält die aggregierten Ergebnisse mit klassifizierten Antworten. alignmentScore und der antwortbezogene reliabilityScore werden berechnet, bevor das Ergebnis auf v1-Endpoints zurückgegeben wird (siehe Alignment-Scoring).

6. Done Event

{"type": "done"}

Zeigt an, dass der Stream abgeschlossen ist.

Output-Datenstruktur

Antworttypen erklärt

Skalenantworten:

• value: Die numerische Bewertung (z.B. "4")
• message: Kurze Begründung für die Bewertung
• groups[].value: Durchschnittliche Bewertung in der Gruppe

Kategoriale Antworten:

• value: Die gewählte Option (z.B. "Yes", "Option A")
• message: Kurze Begründung für die Wahl
• groups[].value: Häufigste Wahl in der Gruppe

Qualitative Antworten:

• value: Zugewiesenes Thema (z.B. "Datenschutzbedenken", "Kostenbarrieren")
• message: Vollständiger Antworttext
• groups[].value: Dominantes Thema in der Gruppe
• Themen werden automatisch aus allen Antworten geclustert (3-6 identifizierte Themen)

Alignment-Scoring

Jede Panel-Antwort enthält zwei Scores in der v1-API-Antwort:

• groups[].answers[].reliabilityScore (0-100, Integer, optional): Score pro Mind, der angibt, wie charakterkonform die Antwort des Minds im Vergleich zu seinem eigenen systemPrompt ist. Berechnet durch erneute Auswertung der Antwort mit demselben Evaluator wie bei einzelnen Spark-Chats, sodass der v1-Panel-Wert direkt mit einzelnen reliabilityScore-Werten vergleichbar ist.
• groups[].alignmentScore (0-100, Integer, optional): Durchschnitt der reliabilityScore-Werte pro Antwort für diese Gruppe. Die UI zeigt das als Alignment-Indikator pro Gruppe an (High / Medium / Low).

Label-Bänder der UI (nicht im Payload enthalten, hier zur Orientierung für API-Nutzer):

Wann Felder weggelassen werden: Der Evaluator überspringt Antworten, bei denen der systemPrompt des Minds kürzer als 20 Zeichen ist, die Antwortnachricht leer ist oder der Evaluator-Aufruf selbst fehlschlägt. Wenn jede Antwort in einer Gruppe übersprungen wird, wird auch der alignmentScore dieser Gruppe weggelassen.

Timing: Auf den v1-Endpoints läuft das Scoring synchron, bevor die Antwort zurückgegeben wird. Die Scores sind also im selben Payload wie der Rest von outputData enthalten. Das fügt der Panel-Generierung einige Sekunden Latenz hinzu. Wer ein schnelleres Panel-Ergebnis ohne Alignment benötigt, sollte die Auswertung nachgelagert im Batch durchführen, anstatt sich auf den Inline-Score zu verlassen.

Status: Dies ist ein vorläufiger Platzhalter für eine zukünftige Gruppen-Alignment-Metrik (Nähe zu empirischen Forschungsergebnissen). Die Feldnamen bleiben erhalten, wenn diese eingeführt wird; die Semantik von alignmentScore kann sich ändern.

Dateianhänge

Dateien, Links und Keywords können als Kontext für Panel-Fragen angehängt werden. Minds erhalten den verarbeiteten Inhalt, bevor sie antworten.

Anhangstypen

1. Dateianhänge (attachments)

Dokumente, PDFs, Bilder und Tabellen zur Analyse hochladen:

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

Unterstützte Formate:

• Dokumente: PDF, DOCX, TXT, MD
• Bilder: PNG, JPG, WEBP (mit OCR)
• Tabellen: CSV, XLSX

Dateiquellen:

• url: Externe URL (wird heruntergeladen und verarbeitet)
• path: Supabase-Speicherpfad (wird automatisch signiert und verarbeitet)

2. Link-Anhänge (links)

Webseiten abrufen und analysieren (nutzt Firecrawl für JS-lastige Seiten und Screenshots):

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

Funktionen:

• JavaScript-Rendering (Firecrawl)
• Screenshot-Erfassung für visuellen Kontext
• Markdown-Extraktion
• Automatische Inhaltskürzung (3000 Zeichen pro Link bei mehreren, 15000 bei einem einzelnen)

3. Keyword-Kontext (keywords)

Keywords mit Quell-URLs als zusätzlichen Kontext bereitstellen:

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

Vollständiges Beispiel mit Anhängen

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

Verarbeitung:

• Dateien werden parallel analysiert (PDFs: Textextraktion, Bilder: OCR/Vision)
• Links werden mit Firecrawl abgerufen (JS-Rendering und Screenshots)
• Inhalte werden für alle Minds in den Fragekontext eingefügt
• Fehlgeschlagene Anhänge werden mit Fallback-Nachrichten behandelt

Tipps:

• Nur relevante Dateien anhängen (jede erhöht die Verarbeitungszeit)
• Links für dynamische Webinhalte verwenden
• Keywords für zusätzlichen Web-Kontext nutzen
• Dateiverarbeitungs-Timeout: 30 Sekunden pro Datei
• Link-Abruf-Timeout: 15 Sekunden pro URL

Beispielanfrage

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

Beispiel: 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'
    }
  }
);

// Hinweis: Für POST-Anfragen mit SSE fetch mit ReadableStream verwenden
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);
    }
  }
}

Fehlerantworten

400 Bad Request - Fehlende Frage oder keine Gruppen zugeordnet

{
  "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 - Kein Zugriff auf dieses Panel

404 Not Found - Panel existiert nicht

Model Override

Standardmäßig verwenden Panel-Antworten die bevorzugte Provider-Einstellung deines Teams, wenn sie konfiguriert und berechtigt ist, andernfalls den Produktstandard. Modell und Provider können pro Request überschrieben werden, um Experimente über Modellfamilien hinweg durchzuführen:

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

Unterstützte Anbieter: openai, anthropic, google. Für Panel-Requests müssen model und provider zusammen gesendet werden. Wird nur einer der Werte gesendet, gibt die API 400 Bad Request zurück. Per-Request-Overrides haben Vorrang vor der Team-Provider-Präferenz.

Diversity Check deaktivieren

Der Panel-Orchestrator führt nach der Generierung eine diversitätserzwingende Regenerierungsschleife durch (Bigram-Selbstähnlichkeitsprüfung, Werthomogenitätserkennung, Empty-Bucket-Fill), bevor die Aggregation erfolgt. Das ist die L4-Schicht des Panel-Rezepts.

Für Ablationsstudien und Benchmark-Läufe, bei denen der Beitrag dieser Schicht isoliert werden soll, disableDiversityCheck: true übergeben:

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

Mit aktiviertem Flag werden Panelisten-Antworten exakt so zurückgegeben, wie sie initial generiert wurden. Es wird kein zweiter Regenerierungsdurchlauf ausgelöst, auch wenn sich Antworten stark überschneiden. Klassifizierung (L3), Spark-spezifisches RAG (L2) und Aggregation (L5) laufen weiterhin normal. Kosteneinsparung: ca. 5-25% weniger LLM-Aufrufe pro Panel-Frage, je nachdem, wie viele Sparks der Diversity Check markiert hätte.

Wann verwenden: Methodenvergleiche, A/B-Tests von Orchestrierungsschichten, Reproduktion von Baseline-Verhalten. Produktions-Panels sollten diesen Parameter deaktiviert lassen (Standard).

Panel-Ergebnisse exportieren

Einen strukturierten Bericht aller Panel-Ergebnisse im Markdown-Format generieren.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

{
  "format": "md"
}

Parameter

Antwort

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

Berichtsstruktur

Der generierte Bericht enthält:

1. Executive Summary - Überblick über die wichtigsten Erkenntnisse in 2-3 Absätzen
2. Methodology - Gruppen, Teilnehmer und Struktur
3. Results by Question - Gruppenübergreifender Vergleich mit zentralen Erkenntnissen und Zitaten
4. Cross-Group Analysis - Muster und Trends über Gruppen hinweg
5. Conclusions & Recommendations - Handlungsrelevante Erkenntnisse

Beispielanfrage

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

Fehlerantworten

403 Forbidden - Kein Zugriff auf dieses Panel

404 Not Found - Panel existiert nicht

Export-Status prüfen

Den Status eines Panel-Export-Jobs prüfen. Wird keine jobId angegeben, wird der Status des letzten Exports zurückgegeben.

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

Headers:

Authorization: Bearer minds_your_api_key

Query-Parameter

Antwort

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

Status-Werte

Beispielanfrage

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

Fehlerantworten

403 Forbidden - Kein Zugriff auf dieses Panel

404 Not Found - Panel oder Job existiert nicht

Export herunterladen

Den exportierten Panel-Bericht als PDF-Datei herunterladen.

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

Headers:

Authorization: Bearer minds_your_api_key

Query-Parameter

Antwort

Gibt eine PDF-Datei mit entsprechenden Headers zurück:

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

Beispielanfrage

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

Fehlerantworten

400 Bad Request - Fehlender jobId-Parameter oder Job noch nicht abgeschlossen

403 Forbidden - Kein Zugriff auf dieses Panel

404 Not Found - Panel oder Job existiert nicht

Workflow-Beispiel

Ein vollständiger Workflow zum Erstellen und Verwenden eines Panels:

# 1. Zuerst Spark-Gruppen erstellen (über die Sparks API)
# Annahme: Gruppen mit den IDs group-genz und group-millennials wurden erstellt

# 2. Panel mit diesen Gruppen erstellen
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"]
  }'

# Antwort: { "data": { "id": "panel-123", ... } }

# 3. Fragen an das Panel stellen
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. Weitere Frage stellen
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. Ergebnisse als Bericht exportieren
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. Export-Status prüfen (bis "completed" pollen)
curl -X GET "https://getminds.ai/api/v1/panels/panel-123/export-status" \
  -H "Authorization: Bearer minds_your_api_key"

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

# 7. PDF herunterladen
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

Fehlercodes-Übersicht

Nächste Schritte

• Minds erstellen, um Panel-Gruppen zu befüllen
• Mehr über Authentifizierung erfahren
• Fehler und Limits im Überblick