Panels API

Les panels vous permettent d'interroger des groupes de minds IA avec des questions et de recevoir des réponses agrégées et structurées. Idéal pour les simulations d'études de marché, la collecte de feedback par persona et l'analyse multi-perspectives.

URL de base : https://getminds.ai/api/v1 ou https://api.getminds.ai/v1

Concepts

Lister les panels

Récupère tous les panels appartenant à l'utilisateur authentifié.

Endpoint : GET /api/v1/panels

Headers :

Authorization: Bearer minds_your_api_key

Réponse

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

Champs de la réponse

Exemple de requête

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

Créer un panel

Crée un nouveau panel avec des Mind Group optionnels attachés.

Endpoint : POST /api/v1/panels

Headers :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête

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

Paramètres

Réponse

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

Exemple de requête

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

Réponses d'erreur

400 Bad Request - Nom manquant ou identifiants de groupe invalides

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

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

Obtenir les détails d'un panel

Récupère un panel spécifique avec tous ses groupes et l'historique des messages.

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

Headers :

Authorization: Bearer minds_your_api_key

Réponse

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

Exemple de requête

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

Réponses d'erreur

403 Forbidden - Accès non autorisé à ce panel

404 Not Found - Le panel n'existe pas

Poser une question au panel

Envoie une question à tous les minds du panel et reçoit des réponses en streaming avec les résultats agrégés.

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

Headers :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête

Question simple :

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

Avec pièces jointes :

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

Paramètres

Réponse (Server-Sent Events)

L'endpoint retourne un flux de Server-Sent Events (SSE). Chaque événement est un objet JSON avec un champ type.

Classification de la question

Avant le traitement, le système classifie automatiquement votre question dans l'un des trois types suivants :

Pour les questions qualitatives, les réponses sont automatiquement regroupées par thèmes (ex. : "Préoccupations liées à la vie privée", "Freins liés au coût"). Le champ value de chaque réponse contient le thème attribué.

Types d'événements

1. Événement Start

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

Indique le début du traitement avec le nombre total de minds.

2. Événement Classification

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

Indique comment la question a été classifiée. Pour les questions de type scale, inclut la plage détectée. Pour les questions catégorielles, inclut les options détectées.

3. Événement Answer

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

Envoyé pour la réponse individuelle de chaque mind. Pour les questions scale/catégorielles, la réponse commence par la note ou le choix, suivi du raisonnement.

4. Événement Aggregating

{"type": "aggregating"}

Indique que l'IA agrège maintenant toutes les réponses. Pour les questions qualitatives, cela inclut le regroupement par thèmes.

5. Événement Result

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

Contient les résultats agrégés avec les réponses classifiées. alignmentScore et reliabilityScore par réponse sont calculés avant que le résultat soit retourné sur les endpoints v1 (voir Alignment scoring).

6. Événement Done

{"type": "done"}

Indique que le flux est terminé.

Structure des données de sortie

Types de réponses expliqués

Réponses scale :

• value : La note numérique (ex. : "4")
• message : Bref raisonnement justifiant la note
• groups[].value : Note moyenne du groupe

Réponses catégorielles :

• value : L'option choisie (ex. : "Yes", "Option A")
• message : Bref raisonnement justifiant le choix
• groups[].value : Choix le plus fréquent dans le groupe

Réponses qualitatives :

• value : Thème attribué (ex. : "Privacy concerns", "Cost barriers")
• message : Texte complet de la réponse
• groups[].value : Thème dominant dans le groupe
• Les thèmes sont automatiquement regroupés à partir de toutes les réponses (3 à 6 thèmes identifiés)

Alignment scoring

Chaque réponse de panel inclut deux scores dans la réponse de l'API v1 :

• groups[].answers[].reliabilityScore (0-100, entier, optionnel) : score par mind mesurant dans quelle mesure la réponse est cohérente avec le persona du mind, évaluée par rapport à son propre systemPrompt. Calculé en réévaluant la réponse avec le même évaluateur que pour les chats individuels, ce qui rend la valeur v1 du panel directement comparable aux valeurs reliabilityScore d'un mind seul.
• groups[].alignmentScore (0-100, entier, optionnel) : moyenne des reliabilityScore par réponse pour ce groupe. L'interface l'affiche comme indicateur Alignment par groupe (High / Medium / Low).

Bandes de labels utilisées par l'interface (absentes du payload, incluses ici pour que les consommateurs de l'API puissent les reproduire) :

Quand les champs sont omis : l'évaluateur ignore les réponses dont le systemPrompt du mind fait moins de 20 caractères, dont le message de réponse est vide, ou lorsque l'appel à l'évaluateur échoue. Si toutes les réponses d'un groupe sont ignorées, l'alignmentScore de ce groupe est également omis.

Timing : sur les endpoints v1, le scoring s'exécute de façon synchrone avant que la réponse soit retournée. Les scores sont donc présents dans le même payload que le reste de outputData. Cela ajoute quelques secondes de latence en plus de la génération du panel. Les consommateurs qui ont besoin d'un résultat de panel plus rapide sans alignment peuvent évaluer en batch en aval plutôt que de s'appuyer sur le score inline.

Statut : il s'agit d'un substitut temporaire à une future métrique d'alignement de groupe (proximité avec les résultats de recherche empiriques). Les noms de champs seront préservés lors de cette évolution ; la sémantique de alignmentScore pourra changer.

File Attachments

Vous pouvez joindre des fichiers, des liens et des mots-clés pour fournir du contexte aux questions du panel. Les minds recevront le contenu traité avant de répondre.

Types de pièces jointes

1. Pièces jointes fichiers (attachments)

Importez des documents, PDFs, images et tableurs pour analyse :

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

Formats supportés :

• Documents : PDF, DOCX, TXT, MD
• Images : PNG, JPG, WEBP (avec OCR)
• Tableurs : CSV, XLSX

Sources de fichiers :

• url : URL externe (téléchargée et traitée)
• path : Chemin de stockage Supabase (signé et traité automatiquement)

2. Pièces jointes liens (links)

Récupère et analyse des pages web (utilise Firecrawl pour les sites JS-heavy + captures d'écran) :

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

Fonctionnalités :

• Rendu JavaScript (Firecrawl)
• Capture d'écran pour le contexte visuel
• Extraction Markdown
• Troncature automatique du contenu (3000 caractères par lien si plusieurs, 15000 si un seul)

3. Contexte par mots-clés (keywords)

Fournissez des mots-clés avec des URLs sources pour du contexte supplémentaire :

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

Exemple complet avec pièces jointes

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

Traitement :

• Les fichiers sont analysés en parallèle (PDFs : extraction de texte, images : OCR/vision)
• Les liens sont récupérés avec Firecrawl (rendu JS + captures d'écran)
• Le contenu est injecté dans le contexte de la question pour tous les minds
• Les pièces jointes en échec sont gérées proprement avec des messages de fallback

Conseils :

• Joignez uniquement les fichiers pertinents (chaque fichier allonge le temps de traitement)
• Utilisez les liens pour le contenu web dynamique
• Utilisez les mots-clés pour du contexte web supplémentaire
• Timeout de traitement des fichiers : 30s par fichier
• Timeout de récupération des liens : 15s par URL

Exemple de requête

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

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

// Note: Pour les requêtes POST avec SSE, utilisez fetch avec ReadableStream
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);
    }
  }
}

Réponses d'erreur

400 Bad Request - Question manquante ou aucun groupe attaché

{
  "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 - Accès non autorisé à ce panel

404 Not Found - Le panel n'existe pas

Model Override

Par défaut, les réponses de panel utilisent le fournisseur préféré de votre équipe lorsqu'il est configuré et éligible, sinon la valeur par défaut du produit. Vous pouvez remplacer le modèle et le fournisseur par requête pour mener des expériences sur différentes familles de modèles :

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

Fournisseurs supportés : openai, anthropic, google. Pour les requêtes de panel, model et provider doivent être envoyés ensemble. Si un seul des deux est envoyé, l'API renvoie 400 Bad Request. Les surcharges par requête sont prioritaires sur la préférence de fournisseur d'équipe.

Disable Diversity Check

L'orchestrateur du panel exécute une boucle de régénération avec contrôle de diversité après génération (vérification d'auto-similarité bigramme, détection d'homogénéité des valeurs, remplissage des buckets vides) avant l'agrégation. Il s'agit de la couche L4 de la recette du panel.

Pour les études d'ablation et les runs de benchmark où vous souhaitez isoler la contribution de cette couche, passez disableDiversityCheck: true :

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

Avec ce flag activé, les réponses des panélistes sont retournées exactement telles que générées initialement : aucune régénération en second passage n'est déclenchée, même si les réponses se recoupent fortement. La classification (L3), le RAG par spark (L2) et l'agrégation (L5) continuent de s'exécuter normalement. Économie de coût : environ 5 à 25% d'appels LLM en moins par question de panel, selon le nombre de sparks que le contrôle de diversité aurait signalés.

Quand l'utiliser : comparaisons de méthodes, tests A/B des couches d'orchestration, reproduction du comportement de référence. Les panels en production doivent laisser cette option désactivée (par défaut).

Exporter les résultats du panel

Génère un rapport structuré de tous les résultats du panel au format Markdown.

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

Headers :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête

{
  "format": "md"
}

Paramètres

Réponse

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

Structure du rapport

Le rapport généré comprend :

1. Executive Summary - Synthèse des principaux résultats en 2 à 3 paragraphes
2. Methodology - Groupes, participants et structure
3. Results by Question - Comparaison inter-groupes avec insights clés et citations
4. Cross-Group Analysis - Tendances et patterns entre les groupes
5. Conclusions & Recommendations - Insights actionnables

Exemple de requête

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

Réponses d'erreur

403 Forbidden - Accès non autorisé à ce panel

404 Not Found - Le panel n'existe pas

Vérifier le statut d'un export

Vérifie le statut d'un job d'export de panel. Si aucun jobId n'est fourni, retourne le statut de l'export le plus récent.

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

Headers :

Authorization: Bearer minds_your_api_key

Paramètres de requête

Réponse

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

Valeurs de statut

Exemple de requête

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

Réponses d'erreur

403 Forbidden - Accès non autorisé à ce panel

404 Not Found - Le panel ou le job n'existe pas

Télécharger un export

Télécharge le rapport de panel exporté sous forme de fichier PDF.

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

Headers :

Authorization: Bearer minds_your_api_key

Paramètres de requête

Réponse

Retourne un fichier PDF avec les headers appropriés :

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

Exemple de requête

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

Réponses d'erreur

400 Bad Request - Paramètre jobId manquant ou job pas encore terminé

403 Forbidden - Accès non autorisé à ce panel

404 Not Found - Le panel ou le job n'existe pas

Exemple de workflow complet

Voici un workflow complet pour créer et utiliser un panel :

# 1. Créez d'abord des groupes de sparks (via l'API Sparks)
# On suppose que vous avez créé des groupes avec les IDs : group-genz, group-millennials

# 2. Créez un panel avec ces groupes
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"]
  }'

# Réponse : { "data": { "id": "panel-123", ... } }

# 3. Posez des questions au panel
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. Posez une autre question
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. Exportez les résultats sous forme de rapport
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. Vérifiez le statut de l'export (interrogez jusqu'à completed)
curl -X GET "https://getminds.ai/api/v1/panels/panel-123/export-status" \
  -H "Authorization: Bearer minds_your_api_key"

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

# 7. Téléchargez le PDF
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

Récapitulatif des codes d'erreur

Prochaines étapes

• Créez des minds pour alimenter vos groupes de panel
• Découvrez l'authentification
• Consultez les erreurs et limites