Groups API

Los grupos te permiten organizar tus minds con IA (personas) en colecciones para usarlos en paneles, en trabajo colaborativo y para una gestión más sencilla. Un grupo puede contener cualquier mind que poseas o al que tengas acceso, y se puede usar para encuestar varias personas a la vez vía la Panels API.

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

Conceptos

Listar grupos

Recupera todos los grupos visibles para el usuario autenticado, incluyendo los grupos que posee, los grupos públicos y los grupos compartidos contigo.

Endpoint: GET /api/v1/groups

Headers:

Authorization: Bearer minds_your_api_key

Response

{
  "data": [
    {
      "id": "group-123",
      "name": "Gen Z Consumers",
      "sparkCount": 5,
      "sparks": [
        {
          "id": "spark-1",
          "name": "Emma",
          "discipline": "College Student",
          "profileImageUrl": "https://..."
        },
        {
          "id": "spark-2",
          "name": "Marcus",
          "discipline": "Social Media Manager",
          "profileImageUrl": "https://..."
        }
      ],
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-15T14:30:00.000Z",
      "isPublic": false,
      "currentMemberRole": "owner",
      "isSharedWithTeam": false,
      "isLinkSharingEnabled": false,
      "publicShareId": null
    }
  ]
}

Campos de la respuesta

Ejemplo de solicitud

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

Crear grupo

Crea un nuevo grupo con un conjunto inicial opcional de minds.

Endpoint: POST /api/v1/groups

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

{
  "name": "Product Beta Testers",
  "sparkIds": ["spark-1", "spark-2", "spark-3"]
}

Parámetros

Response

{
  "data": {
    "id": "group-456",
    "name": "Product Beta Testers",
    "sparkCount": 3,
    "sparks": [
      {
        "id": "spark-1",
        "name": "Alex",
        "discipline": "Early Adopter",
        "profileImageUrl": "https://..."
      },
      {
        "id": "spark-2",
        "name": "Jordan",
        "discipline": "Tech Enthusiast",
        "profileImageUrl": "https://..."
      },
      {
        "id": "spark-3",
        "name": "Taylor",
        "discipline": "UX Researcher",
        "profileImageUrl": "https://..."
      }
    ],
    "createdAt": "2025-12-16T10:00:00.000Z",
    "updatedAt": "2025-12-16T10:00:00.000Z",
    "isPublic": false,
    "isSharedWithTeam": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null,
    "currentMemberRole": "owner"
  }
}

Ejemplo de solicitud

curl -X POST "https://getminds.ai/api/v1/groups" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Personas",
    "sparkIds": ["spark-123", "spark-456"]
  }'

Respuestas de error

400 Bad Request - Falta el nombre o los IDs de spark no son válidos

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

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

403 Forbidden - Límite de plan alcanzado

{
  "statusCode": 403,
  "message": "Free plan allows 1 Group. Upgrade for more!",
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "groups",
    "currentPlan": "free",
    "limit": 1,
    "current": 1
  }
}

Obtener detalles del grupo

Recupera los detalles de un grupo específico, incluidos todos sus miembros.

Endpoint: GET /api/v1/groups/{groupId}

Headers:

Authorization: Bearer minds_your_api_key

Response

{
  "data": {
    "id": "group-123",
    "name": "Gen Z Consumers",
    "sparkCount": 5,
    "sparks": [
      {
        "id": "spark-1",
        "name": "Emma",
        "discipline": "College Student",
        "profileImageUrl": "https://...",
        "createdAt": "2025-10-01T08:00:00.000Z"
      },
      {
        "id": "spark-2",
        "name": "Marcus",
        "discipline": "Social Media Manager",
        "profileImageUrl": "https://...",
        "createdAt": "2025-10-05T09:30:00.000Z"
      }
    ],
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-15T14:30:00.000Z",
    "isPublic": false,
    "currentMemberRole": "owner",
    "isSharedWithTeam": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null
  }
}

Ejemplo de solicitud

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

Respuestas de error

404 Not Found - El grupo no existe o no tienes acceso

{
  "statusCode": 404,
  "message": "Group not found"
}

Actualizar grupo

Actualiza el nombre de un grupo. Solo el owner del grupo puede actualizarlo.

Endpoint: PUT /api/v1/groups/{groupId}

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

{
  "name": "Gen Z Early Adopters"
}

Parámetros

Response

{
  "data": {
    "id": "group-123",
    "name": "Gen Z Early Adopters",
    "sparkCount": 5,
    "sparks": [
      {
        "id": "spark-1",
        "name": "Emma",
        "discipline": "College Student",
        "profileImageUrl": "https://..."
      }
    ],
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-16T10:15:00.000Z",
    "isPublic": false,
    "isSharedWithTeam": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null,
    "currentMemberRole": "owner"
  }
}

Ejemplo de solicitud

curl -X PUT "https://getminds.ai/api/v1/groups/group-123" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Group Name"}'

Respuestas de error

400 Bad Request - Falta el nombre

404 Not Found - Grupo no encontrado o no eres el owner

Eliminar grupo

Elimina un grupo de forma permanente. Solo el owner del grupo puede eliminarlo. Se eliminarán todos los miembros del grupo, pero los sparks en sí no se eliminan.

Endpoint: DELETE /api/v1/groups/{groupId}

Headers:

Authorization: Bearer minds_your_api_key

Response

Returns 204 No Content with an empty body on success.

Ejemplo de solicitud

curl -X DELETE "https://getminds.ai/api/v1/groups/group-123" \
  -H "Authorization: Bearer minds_your_api_key"

Respuestas de error

404 Not Found - Grupo no encontrado o no eres el owner

Añadir miembros al grupo

Añade uno o varios minds a un grupo. Solo puedes añadir minds que poseas o a los que tengas acceso.

Endpoint: POST /api/v1/groups/{groupId}/members

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

Un solo spark:

{
  "sparkId": "spark-789"
}

Varios sparks:

{
  "sparkIds": ["spark-789", "spark-101", "spark-202"]
}

Parámetros

Nota: debes proporcionar sparkId o sparkIds, pero no ambos.

Response

{
  "data": {
    "added": 3
  }
}

Ejemplo de solicitud

curl -X POST "https://getminds.ai/api/v1/groups/group-123/members" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sparkIds": ["spark-789", "spark-101"]
  }'

Respuestas de error

400 Bad Request - Falta sparkId/sparkIds o array vacío

{
  "statusCode": 400,
  "message": "sparkId or sparkIds is required"
}

403 Forbidden - Límite de miembros del plan alcanzado

{
  "statusCode": 403,
  "message": "Free plan allows up to 3 Minds per Group. Upgrade for unlimited!",
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "groupMembers",
    "currentPlan": "free",
    "limit": 3,
    "current": 2,
    "requested": 2
  }
}

404 Not Found - Grupo no encontrado, no eres el owner, o uno o más sparks no accesibles

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

Eliminar miembro de un grupo

Elimina un mind de un grupo.

Endpoint: DELETE /api/v1/groups/{groupId}/members/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key

Response

Returns 204 No Content with an empty body on success.

Ejemplo de solicitud

curl -X DELETE "https://getminds.ai/api/v1/groups/group-123/members/spark-789" \
  -H "Authorization: Bearer minds_your_api_key"

Respuestas de error

404 Not Found - Grupo no encontrado o no eres el owner

Límites del plan

Los distintos planes de suscripción tienen distintos límites de grupos:

Cuando alcances el límite de tu plan, recibirás un error 403 con detalles sobre cómo actualizar.

Ejemplo de workflow

Aquí tienes un workflow completo para crear y gestionar grupos:

# 1. Create a group with initial members
curl -X POST "https://getminds.ai/api/v1/groups" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Research Group",
    "sparkIds": ["spark-1", "spark-2"]
  }'

# Response: { "data": { "id": "group-abc", ... } }

# 2. Add more members to the group
curl -X POST "https://getminds.ai/api/v1/groups/group-abc/members" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sparkIds": ["spark-3", "spark-4", "spark-5"]
  }'

# 3. Get group details to see all members
curl -X GET "https://getminds.ai/api/v1/groups/group-abc" \
  -H "Authorization: Bearer minds_your_api_key"

# 4. Update the group name
curl -X PUT "https://getminds.ai/api/v1/groups/group-abc" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "UX Research Panel"}'

# 5. Remove a member
curl -X DELETE "https://getminds.ai/api/v1/groups/group-abc/members/spark-3" \
  -H "Authorization: Bearer minds_your_api_key"

# 6. Use the group in a panel
curl -X POST "https://getminds.ai/api/v1/panels" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Feedback Panel",
    "groupIds": ["group-abc"]
  }'

# 7. List all groups
curl -X GET "https://getminds.ai/api/v1/groups" \
  -H "Authorization: Bearer minds_your_api_key"

Resumen de códigos de error

Siguientes pasos

• Crea minds para añadir a tus grupos
• Usa grupos en paneles para encuestas multi-spark
• Aprende sobre autenticación
• Revisa límites de plan y errores