Panels API

Los paneles te permiten encuestar grupos de minds de IA con preguntas y recibir respuestas agregadas y estructuradas. Es ideal para simulaciones de investigación de mercado, recopilación de feedback basado en personas y análisis multiperspectiva.

URL base: https://getminds.ai/api/v1 o https://api.getminds.ai/v1

Conceptos

Listar paneles

Recupera todos los paneles del usuario autenticado.

Endpoint: GET /api/v1/panels

Headers:

Authorization: Bearer minds_your_api_key

Respuesta

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

Campos de la respuesta

Ejemplo de solicitud

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

Crear panel

Crea un nuevo panel con grupos de minds opcionales asociados.

Endpoint: POST /api/v1/panels

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Cuerpo de la solicitud

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

Parámetros

Respuesta

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

Ejemplo de solicitud

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

Respuestas de error

400 Bad Request - Falta el nombre o los IDs de grupo son inválidos

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

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

Obtener detalles del panel

Recupera un panel específico con todos sus grupos e historial de mensajes.

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

Headers:

Authorization: Bearer minds_your_api_key

Respuesta

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

Ejemplo de solicitud

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

Respuestas de error

403 Forbidden - Sin autorización para acceder a este panel

404 Not Found - El panel no existe

Hacer una pregunta al panel

Envía una pregunta a todos los minds del panel y recibe respuestas en streaming con resultados agregados.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Cuerpo de la solicitud

Pregunta básica:

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

Con archivos adjuntos:

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

Parámetros

Respuesta (Server-Sent Events)

El endpoint devuelve un stream de Server-Sent Events (SSE). Cada evento es un objeto JSON con un campo type.

Clasificación de preguntas

Antes de procesar, el sistema clasifica automáticamente tu pregunta en uno de tres tipos:

Para preguntas cualitativas, las respuestas se agrupan automáticamente en temas (p. ej., "Preocupaciones de privacidad", "Barreras de coste"). El campo value de cada respuesta contiene el tema asignado.

Tipos de eventos

1. Evento Start

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

Indica el inicio del procesamiento con el número total de minds.

2. Evento Classification

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

Indica cómo se clasificó la pregunta. Para preguntas de escala, incluye el rango detectado. Para preguntas categóricas, incluye las opciones detectadas.

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

Se envía con la respuesta individual de cada mind. Para preguntas de escala o categóricas, la respuesta comienza con la valoración o elección seguida del razonamiento.

4. Evento Aggregating

{"type": "aggregating"}

Indica que la IA está agregando todas las respuestas. Para preguntas cualitativas, esto incluye la agrupación por temas.

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

Contiene los resultados agregados con respuestas clasificadas. alignmentScore y reliabilityScore por respuesta se calculan antes de devolver el resultado en los endpoints v1 (ver Alignment scoring).

6. Evento Done

{"type": "done"}

Indica que el stream ha finalizado.

Estructura de datos de salida

Tipos de respuesta explicados

Respuestas de escala:

• value: La valoración numérica (p. ej., "4")
• message: Razonamiento breve para la valoración
• groups[].value: Valoración promedio del grupo

Respuestas categóricas:

• value: La opción elegida (p. ej., "Yes", "Option A")
• message: Razonamiento breve para la elección
• groups[].value: Opción más frecuente en el grupo

Respuestas cualitativas:

• value: Tema o tópico asignado (p. ej., "Privacy concerns", "Cost barriers")
• message: Texto completo de la respuesta
• groups[].value: Tema dominante en el grupo
• Los temas se agrupan automáticamente a partir de todas las respuestas (se identifican entre 3 y 6 temas)

Alignment scoring

Cada respuesta de panel incluye dos puntuaciones en la respuesta de la API v1:

• groups[].answers[].reliabilityScore (0-100, entero, opcional): puntuación por mind que mide qué tan fiel al personaje es la respuesta del mind respecto a su propio systemPrompt. Se calcula reevaluando la respuesta con el mismo evaluador usado en los chats individuales de Spark, por lo que el valor v1 del panel es directamente comparable con los valores de reliabilityScore de un solo mind.
• groups[].alignmentScore (0-100, entero, opcional): promedio del reliabilityScore por respuesta para ese grupo. La interfaz lo muestra como el indicador de Alignment por grupo (High / Medium / Low).

Bandas de etiquetas usadas por la interfaz (no están en el payload; se incluyen aquí para que los consumidores de la API puedan hacer la correspondencia):

Cuándo se omiten los campos: el evaluador omite respuestas donde el systemPrompt del mind tiene menos de 20 caracteres, donde el mensaje de respuesta está vacío, o cuando la llamada al evaluador falla. Si todas las respuestas de un grupo son omitidas, el alignmentScore de ese grupo también se omite.

Temporización: en los endpoints v1, la puntuación se ejecuta de forma síncrona antes de devolver la respuesta, por lo que las puntuaciones están presentes en el mismo payload que el resto de outputData. Esto añade algunos segundos de latencia sobre la generación del panel. Los consumidores que necesiten un resultado de panel más rápido sin Alignment deben evaluar en lote aguas abajo en lugar de depender de la puntuación inline.

Estado: esto es un sustituto temporal de una futura métrica de alineación de grupo (cercanía a hallazgos de investigación empírica). Los nombres de campo se conservarán cuando eso llegue; la semántica de alignmentScore puede cambiar.

File Attachments

Puedes adjuntar archivos, enlaces y palabras clave para proporcionar contexto a las preguntas del panel. Los minds recibirán el contenido procesado antes de responder.

Tipos de adjuntos

1. Archivos adjuntos (attachments)

Sube documentos, PDFs, imágenes y hojas de cálculo para análisis:

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

Formatos compatibles:

• Documentos: PDF, DOCX, TXT, MD
• Imágenes: PNG, JPG, WEBP (con OCR)
• Hojas de cálculo: CSV, XLSX

Fuentes de archivos:

• url: URL externa (se descarga y procesa)
• path: Ruta de almacenamiento en Supabase (se firma automáticamente y procesa)

2. Adjuntos de enlace (links)

Obtén y analiza páginas web (usa Firecrawl para sitios con JS intensivo y capturas de pantalla):

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

Características:

• Renderizado de JavaScript (Firecrawl)
• Captura de pantalla para contexto visual
• Extracción en Markdown
• Truncado automático de contenido (3000 caracteres por enlace si hay varios, 15000 si es uno solo)

3. Contexto de palabras clave (keywords)

Proporciona palabras clave con URLs de origen para contexto adicional:

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

Ejemplo completo con adjuntos

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

Procesamiento:

• Los archivos se analizan en paralelo (PDFs: extracción de texto; imágenes: OCR/visión)
• Los enlaces se obtienen con Firecrawl (renderizado JS y capturas de pantalla)
• El contenido se inyecta en el contexto de la pregunta para todos los minds
• Los adjuntos fallidos se gestionan con mensajes de respaldo

Consejos:

• Adjunta solo archivos relevantes (cada uno añade tiempo de procesamiento)
• Usa enlaces para contenido web dinámico
• Usa palabras clave para contexto web adicional
• Tiempo límite de procesamiento de archivos: 30 s por archivo
• Tiempo límite de obtención de enlaces: 15 s por URL

Ejemplo de solicitud

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

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

// Nota: Para solicitudes POST con SSE, usa fetch con 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);
    }
  }
}

Respuestas de error

400 Bad Request - Falta la pregunta o no hay grupos asociados

{
  "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 - Sin autorización para acceder a este panel

404 Not Found - El panel no existe

Model Override

Por defecto, las respuestas del panel usan el proveedor preferido de tu equipo cuando está configurado y es elegible; si no, usan el valor predeterminado del producto. Puedes reemplazar el modelo y el proveedor por solicitud para ejecutar experimentos entre familias de modelos:

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

Proveedores compatibles: openai, anthropic, google. En solicitudes de panel, model y provider deben enviarse juntos. Si solo se envía uno, la API devuelve 400 Bad Request. Los overrides por solicitud tienen prioridad sobre la preferencia de proveedor del equipo.

Disable Diversity Check

El orquestador del panel ejecuta un bucle de regeneración forzada de diversidad tras la generación (verificación de auto-similitud de bigramas, detección de homogeneidad de valores, relleno de cubos vacíos) antes de la agregación. Esta es la capa L4 de la receta del panel.

Para estudios de ablación y ejecuciones de benchmark donde quieras aislar la contribución de esta capa, pasa 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
  }'

Con el flag activado, las respuestas de los panelistas se devuelven exactamente como se generaron inicialmente: no se activa ninguna regeneración en segunda pasada, aunque las respuestas se solapen considerablemente. La clasificación (L3), el RAG por Spark (L2) y la agregación (L5) siguen ejecutándose con normalidad. Ahorro de costes: entre un 5 y un 25% menos de llamadas LLM por pregunta de panel, según cuántos Sparks hubiera marcado la verificación de diversidad.

Cuándo usarlo: comparaciones de métodos, pruebas A/B de capas de orquestación, reproducción del comportamiento base. Los paneles en producción deben dejarlo desactivado (valor por defecto).

Exportar resultados del panel

Genera un informe estructurado de todos los resultados del panel en formato Markdown.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Cuerpo de la solicitud

{
  "format": "md"
}

Parámetros

Respuesta

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

Estructura del informe

El informe generado incluye:

1. Executive Summary - Resumen de 2 a 3 párrafos con los hallazgos clave
2. Methodology - Grupos, participantes y estructura
3. Results by Question - Comparación entre grupos con insights clave y citas
4. Cross-Group Analysis - Patrones y tendencias entre grupos
5. Conclusions & Recommendations - Insights accionables

Ejemplo de solicitud

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

Respuestas de error

403 Forbidden - Sin autorización para acceder a este panel

404 Not Found - El panel no existe

Verificar estado de exportación

Comprueba el estado de un trabajo de exportación del panel. Si no se proporciona jobId, devuelve el estado de la exportación más reciente.

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

Headers:

Authorization: Bearer minds_your_api_key

Parámetros de consulta

Respuesta

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

Valores de estado

Ejemplo de solicitud

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

Respuestas de error

403 Forbidden - Sin autorización para acceder a este panel

404 Not Found - El panel o el trabajo no existe

Descargar exportación

Descarga el informe exportado del panel como archivo PDF.

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

Headers:

Authorization: Bearer minds_your_api_key

Parámetros de consulta

Respuesta

Devuelve un archivo PDF con los headers correspondientes:

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

Ejemplo de solicitud

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

Respuestas de error

400 Bad Request - Falta el parámetro jobId o el trabajo aún no ha finalizado

403 Forbidden - Sin autorización para acceder a este panel

404 Not Found - El panel o el trabajo no existe

Ejemplo de flujo completo

Aquí tienes un flujo completo para crear y usar un panel:

# 1. Crea primero los grupos de Sparks (usando la Sparks API)
# Asume que has creado grupos con IDs: group-genz, group-millennials

# 2. Crea un panel con esos grupos
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"]
  }'

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

# 3. Haz preguntas al 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. Haz otra pregunta
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. Exporta los resultados como informe
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. Verifica el estado de la exportación (consulta hasta que esté completada)
curl -X GET "https://getminds.ai/api/v1/panels/panel-123/export-status" \
  -H "Authorization: Bearer minds_your_api_key"

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

# 7. Descarga el 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

Resumen de códigos de error

Próximos pasos

• Crea minds para poblar los grupos de tu panel
• Aprende sobre autenticación
• Revisa errores y límites