패널 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"
    }
  ]
}

매개변수

응답 (서버 전송 이벤트)

엔드포인트는 서버 전송 이벤트(SSE) 스트림을 반환합니다. 각 이벤트는 type 필드를 가진 JSON 객체입니다.

질문 분류

처리하기 전에 시스템은 질문을 세 가지 유형 중 하나로 자동 분류합니다:

정성적 질문의 경우, 응답은 자동으로 주제별로 클러스터링됩니다 (예: "개인정보 보호 우려", "비용 장벽"). 각 응답의 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"
}

분류된 응답과 함께 집계된 결과를 포함합니다. alignmentScore 및 답변별 reliabilityScore는 v1 엔드포인트에서 결과가 반환되기 전에 계산됩니다 (얼라인먼트 스코어링 참조).

6. 완료 이벤트

{"type": "done"}

스트림이 완료되었음을 나타냅니다.

출력 데이터 구조

응답 유형 설명

척도 응답:

• value: 숫자 등급 (예: "4")
• message: 등급에 대한 간략한 근거
• groups[].value: 그룹 전체의 평균 등급

범주형 응답:

• value: 선택된 옵션 (예: "예", "옵션 A")
• message: 선택에 대한 간략한 근거
• groups[].value: 그룹에서 가장 일반적인 선택

정성적 응답:

• value: 할당된 주제/테마 (예: "개인정보 보호 우려", "비용 장벽")
• message: 전체 응답 텍스트
• groups[].value: 그룹의 지배적인 주제
• 주제는 모든 응답에서 자동으로 클러스터링됩니다 (3-6개 주제 식별)

얼라인먼트 스코어링

모든 패널 답변에는 v1 API 응답에 두 가지 점수가 포함됩니다:

• groups[].answers[].reliabilityScore (0–100, 정수, 선택 사항) , 마인드의 답변이 자체 systemPrompt에 얼마나 부합하는지에 대한 마인드별 점수입니다. 개별 스파크 채팅에 사용된 것과 동일한 평가자로 응답을 재평가하여 계산되므로, 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)

웹 페이지를 가져와 분석합니다 (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)
• 시각적 컨텍스트를 위한 스크린샷 캡처
• 마크다운 추출
• 자동 콘텐츠 잘라내기 (링크가 여러 개일 경우 링크당 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 렌더링 + 스크린샷)
• 콘텐츠는 모든 마인드의 질문 컨텍스트에 주입됩니다
• 실패한 첨부 파일은 폴백 메시지로 정상적으로 처리됩니다

팁:

• 관련 파일만 첨부하세요 (각각 처리 시간이 추가됩니다)
• 동적 웹 콘텐츠에는 링크를 사용하세요
• 추가 웹 컨텍스트에는 키워드를 사용하세요
• 파일 처리 시간 초과: 파일당 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를 반환합니다. 요청별 재정의는 팀 제공업체 선호 설정보다 우선합니다.

다양성 검사 비활성화

패널 오케스트레이터는 집계 전에 생성 후 다양성 강제 재생성 루프(바이그램 자기 유사성 검사, 가치 동질성 감지, 빈 버킷 채우기)를 실행합니다. 이것은 패널 레시피의 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), 스파크별 RAG(L2), 집계(L5)는 여전히 정상적으로 실행됩니다. 비용 절감: 다양성 검사가 플래그를 지정했을 스파크 수에 따라 패널 질문당 LLM 호출이 약 5–25% 감소합니다.

사용 시기: 방법 비교, 오케스트레이션 레이어의 A/B 테스트, 기준 행동 재현. 프로덕션 패널은 이 옵션을 꺼두어야 합니다(기본값).

패널 결과 내보내기

모든 패널 결과에 대한 구조화된 보고서를 마크다운 형식으로 생성합니다.

엔드포인트: 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

오류 코드 요약

다음 단계

• 마인드 생성하여 패널 그룹 채우기
• 인증에 대해 알아보기
• 오류 및 제한 검토하기