パネルAPI

パネルを使用すると、AIマインドのグループに質問を投げかけ、集計・構造化された回答を受け取ることができます。これは、市場調査シミュレーション、ペルソナベースのフィードバック収集、多角的な分析に役立ちます。

ベースURL: https://getminds.ai/api/v1 または https://api.getminds.ai/v1

概念

パネル一覧の取得

認証されたユーザーに属するすべてのパネルを取得します。

エンドポイント: GET /api/v1/panels

ヘッダー:

Authorization: Bearer minds_your_api_key

レスポンス

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

レスポンスフィールド

リクエスト例

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

パネルの作成

新しいパネルを作成します。オプションでマインドグループをアタッチできます。

エンドポイント: POST /api/v1/panels

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ

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

パラメータ

レスポンス

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

リクエスト例

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

エラーレスポンス

400 Bad Request - 名前が欠落しているか、グループIDが無効です

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

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

パネル詳細の取得

特定のパネルを、そのすべてのグループとメッセージ履歴とともに取得します。

エンドポイント: GET /api/v1/panels/{panelId}

ヘッダー:

Authorization: Bearer minds_your_api_key

レスポンス

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

リクエスト例

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

エラーレスポンス

403 Forbidden - このパネルへのアクセスは許可されていません

404 Not Found - パネルが存在しません

パネルへの質問

パネル内のすべてのマインドに質問を送信し、集計結果を含むストリーミングレスポンスを受け取ります。

エンドポイント: POST /api/v1/panels/{panelId}/ask

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ

基本的な質問:

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

添付ファイル付き:

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

パラメータ

レスポンス (Server-Sent Events)

このエンドポイントはServer-Sent Events (SSE) のストリームを返します。各イベントはtypeフィールドを持つJSONオブジェクトです。

質問の分類

処理の前に、システムは質問を自動的に以下の3つのタイプのいずれかに分類します:

定性的な質問の場合、回答は自動的にトピック（例：「プライバシーの懸念」、「コストの障壁」）にクラスタリングされます。各回答のvalueフィールドには、割り当てられたトピックが含まれます。

イベントタイプ

1. 開始イベント

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

処理の開始とマインドの総数を示します。

2. 分類イベント

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

質問がどのように分類されたかを示します。スケール質問の場合は検出された範囲、カテゴリカル質問の場合は検出された選択肢が含まれます。

3. 回答イベント

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

各マインドの個別の回答ごとに送信されます。スケール/カテゴリカル質問の場合、回答は評価/選択肢から始まり、その後に理由が続きます。

4. 集計イベント

{"type": "aggregating"}

AIがすべての回答を集計中であることを示します。定性的な質問の場合、これにはトピックのクラスタリングが含まれます。

5. 結果イベント

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

分類された回答を含む集計結果が含まれます。v1エンドポイントでは、結果が返される前にalignmentScoreと回答ごとのreliabilityScoreが計算されます（アライメントスコアリングを参照）。

6. 完了イベント

{"type": "done"}

ストリームが完了したことを示します。

出力データ構造

回答タイプの説明

スケール回答:

• value: 数値評価（例：「4」）
• message: 評価の簡単な理由
• groups[].value: グループ全体の平均評価

カテゴリカル回答:

• value: 選択された選択肢（例：「はい」、「選択肢A」）
• message: 選択の簡単な理由
• groups[].value: グループ内で最も一般的な選択肢

定性的回答:

• value: 割り当てられたトピック/テーマ（例：「プライバシーの懸念」、「コストの障壁」）
• message: 完全な回答テキスト
• groups[].value: グループ内の主要トピック
• トピックはすべての回答から自動的にクラスタリングされます（3〜6個のトピックが特定されます）

アライメントスコアリング

v1 APIのレスポンスでは、すべてのパネル回答に2つのスコアが含まれます:

• groups[].answers[].reliabilityScore (0–100, 整数, オプション) , マインドの回答が、自身のsystemPromptに対してどれだけキャラクターに沿っているかを示すマインドごとのスコア。個々のsparkチャットで使用されるのと同じ評価器で回答を再評価して計算されるため、v1パネルの値は単一マインドのreliabilityScore値と直接比較可能です。
• groups[].alignmentScore (0–100, 整数, オプション) , そのグループの回答ごとのreliabilityScoreの平均。UIでは、グループごとのアライメント指標（高 / 中 / 低）として表示されます。

ラベル帯 UIで使用されるもの（ペイロードには含まれませんが、API利用者が一致させられるようにここに記載）:

フィールドが省略される場合: 評価器は、マインドのsystemPromptが20文字未満の場合、回答メッセージが空の場合、または評価器の呼び出し自体が失敗した場合に、その回答をスキップします。グループ内のすべての回答がスキップされた場合、そのグループのalignmentScoreも省略されます。

タイミング: v1エンドポイントでは、スコアリングはレスポンスが返される前に同期的に実行されるため、スコアはoutputDataの他の部分と同じペイロード内に存在します。これにより、パネル生成に加えて数秒のレイテンシが発生します。アライメントなしでより高速なパネル結果が必要な利用者は、インラインスコアに頼るのではなく、下流でバッチ評価を行うべきです。

ステータス: これは将来のグループアライメント指標（実証的研究結果との近さ）のための一時的な代替です。それが実装された際もフィールド名は維持されますが、alignmentScoreのセマンティクスは変更される可能性があります。

ファイル添付

ファイル、リンク、キーワードを添付して、パネルの質問にコンテキストを提供できます。Mindsは回答する前に、処理されたコンテンツを受け取ります。

添付ファイルの種類

1. ファイル添付 (attachments)

分析用にドキュメント、PDF、画像、スプレッドシートをアップロードします:

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

対応フォーマット:

• ドキュメント: PDF, DOCX, TXT, MD
• 画像: PNG, JPG, WEBP (OCR付き)
• スプレッドシート: CSV, XLSX

ファイルソース:

• url: 外部URL（ダウンロードして処理）
• path: Supabaseストレージパス（自動署名して処理）

2. リンク添付 (links)

Webページを取得して分析します（JSを多用するサイトにはFirecrawlを使用 + スクリーンショット）:

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

機能:

• JavaScriptレンダリング (Firecrawl)
• 視覚的コンテキストのためのスクリーンショットキャプチャ
• Markdown抽出
• コンテンツの自動切り捨て（複数の場合はリンクごとに3000文字、単一の場合は15000文字）

3. キーワードコンテキスト (keywords)

追加のコンテキストとして、ソースURL付きのキーワードを提供します:

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

添付ファイル付きの完全な例

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

処理:

• ファイルは並行して分析されます（PDF → テキスト抽出、画像 → OCR/ビジョン）
• リンクはFirecrawlで取得されます（JSレンダリング + スクリーンショット）
• コンテンツはすべてのマインドの質問コンテキストに挿入されます
• 失敗した添付ファイルは、フォールバックメッセージで適切に処理されます

ヒント:

• 関連ファイルのみを添付してください（それぞれ処理時間が追加されます）
• 動的なWebコンテンツにはリンクを使用してください
• 追加のWebコンテキストにはキーワードを使用してください
• ファイル処理タイムアウト: ファイルごとに30秒
• リンク取得タイムアウト: URLごとに15秒

リクエスト例

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

例: 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: For POST requests with SSE, use fetch with 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);
    }
  }
}

エラーレスポンス

400 Bad Request - 質問が欠落しているか、グループがアタッチされていません

{
  "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 - このパネルへのアクセスは許可されていません

404 Not Found - パネルが存在しません

モデルの上書き

デフォルトでは、パネルの回答は、チームの優先プロバイダーが設定され利用可能な場合はそれを使用し、そうでない場合は製品のデフォルトを使用します。リクエストごとにモデルとプロバイダーを上書きして、モデルファミリーを横断する実験を実行できます:

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

対応プロバイダー: openai、anthropic、google。パネルリクエストの場合、modelとproviderは一緒に送信する必要があります。一方のみが送信された場合、APIは400 Bad Requestを返します。リクエストごとの上書きは、チームのプロバイダー設定よりも優先されます。

多様性チェックの無効化

パネルオーケストレーターは、集計の前に、生成後の多様性を強制する再生成ループ（bigram自己類似性チェック、値の均質性検出、空バケットの充填）を実行します。これはパネルレシピのL4レイヤーです。

このレイヤーの貢献を分離したいアブレーションスタディやベンチマーク実行の場合は、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
  }'

このフラグを有効にすると、パネリストの回答は最初に生成されたまま返されます。回答が大幅に重複していても、2回目の再生成はトリガーされません。分類（L3）、sparkごとのRAG（L2）、集計（L5）は通常通り実行されます。コスト削減: 多様性チェックがフラグを立てたであろうsparkの数に応じて、パネルの質問あたりのLLM呼び出しが約5〜25%少なくなります。

使用場面: 手法の比較、オーケストレーションレイヤーのA/Bテスト、ベースラインの挙動の再現。本番環境のパネルでは、これをオフ（デフォルト）のままにしてください。

パネル結果のエクスポート

すべてのパネル結果の構造化レポートをMarkdown形式で生成します。

エンドポイント: POST /api/v1/panels/{panelId}/export

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ

{
  "format": "md"
}

パラメータ

レスポンス

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

レポート構造

生成されるレポートには以下が含まれます:

1. エグゼクティブサマリー - 主要な調査結果の2〜3パラグラフの概要
2. 方法論 - グループ、参加者、構造
3. 質問ごとの結果 - 主要なインサイトと引用を含むグループ横断比較
4. グループ横断分析 - グループ間のパターンと傾向
5. 結論と推奨事項 - 実用的なインサイト

リクエスト例

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

エラーレスポンス

403 Forbidden - このパネルへのアクセスは許可されていません

404 Not Found - パネルが存在しません

エクスポートステータスの確認

パネルエクスポートジョブのステータスを確認します。jobIdが指定されていない場合、最新のエクスポートのステータスを返します。

エンドポイント: GET /api/v1/panels/{panelId}/export-status

ヘッダー:

Authorization: Bearer minds_your_api_key

クエリパラメータ

レスポンス

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

ステータス値

リクエスト例

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

エラーレスポンス

403 Forbidden - このパネルへのアクセスは許可されていません

404 Not Found - パネルまたはジョブが存在しません

エクスポートのダウンロード

エクスポートされたパネルレポートをPDFファイルとしてダウンロードします。

エンドポイント: GET /api/v1/panels/{panelId}/export-download

ヘッダー:

Authorization: Bearer minds_your_api_key

クエリパラメータ

レスポンス

適切なヘッダーを持つPDFファイルを返します:

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

リクエスト例

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

エラーレスポンス

400 Bad Request - jobIdパラメータが欠落しているか、ジョブがまだ完了していません

403 Forbidden - このパネルへのアクセスは許可されていません

404 Not Found - パネルまたはジョブが存在しません

ワークフロー例

以下は、パネルを作成して使用するための完全なワークフローです:

# 1. Create spark groups first (using Sparks API)
# Assume you have created groups with IDs: group-genz, group-millennials

# 2. Create a panel with those groups
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"]
  }'

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

# 3. Ask questions to the 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. Ask another 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. Export the results as a report
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. Check export status (poll until completed)
curl -X GET "https://getminds.ai/api/v1/panels/panel-123/export-status" \
  -H "Authorization: Bearer minds_your_api_key"

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

# 7. Download the 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

エラーコードの概要

次のステップ

• マインドを作成してパネルグループを構成する
• 認証について学ぶ
• エラーと制限を確認する