API Groups

Les groupes vous permettent d'organiser vos minds IA (personas) en collections pour les utiliser dans des panels, le travail collaboratif et une gestion simplifiée. Un groupe peut contenir n'importe quels minds que vous possédez ou auxquels vous avez accès, et peut être utilisé pour interroger plusieurs personas en même temps via l'API Panels.

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

Concepts

Lister les groupes

Récupère tous les groupes visibles par l'utilisateur authentifié, y compris les groupes possédés, publics et partagés avec vous.

Endpoint : GET /api/v1/groups

En-têtes :

Authorization: Bearer minds_your_api_key

Réponse

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

Champs de réponse

Exemple de requête

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

Créer un groupe

Crée un nouveau groupe avec un ensemble initial optionnel de minds.

Endpoint : POST /api/v1/groups

En-têtes :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête

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

Paramètres

Réponse

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

Exemple de requête

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

Réponses d'erreur

400 Bad Request — Nom manquant ou IDs de sparks invalides

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

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

403 Forbidden — Limite d'offre atteinte

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

Obtenir les détails d'un groupe

Récupère les détails d'un groupe spécifique, y compris tous ses membres.

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

En-têtes :

Authorization: Bearer minds_your_api_key

Réponse

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

Exemple de requête

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

Réponses d'erreur

404 Not Found — Le groupe n'existe pas ou vous n'y avez pas accès

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

Mettre à jour un groupe

Met à jour le nom d'un groupe. Seul le propriétaire du groupe peut le mettre à jour.

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

En-têtes :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête

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

Paramètres

Réponse

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

Exemple de requête

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

Réponses d'erreur

400 Bad Request — Nom manquant

404 Not Found — Groupe non trouvé ou vous n'en êtes pas le propriétaire

Supprimer un groupe

Supprime définitivement un groupe. Seul le propriétaire du groupe peut le supprimer. Tous les membres du groupe seront retirés, mais les sparks eux-mêmes ne sont pas supprimés.

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

En-têtes :

Authorization: Bearer minds_your_api_key

Réponse

Returns 204 No Content with an empty body on success.

Exemple de requête

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

Réponses d'erreur

404 Not Found — Groupe non trouvé ou vous n'en êtes pas le propriétaire

Ajouter des membres à un groupe

Ajoute un ou plusieurs minds à un groupe. Vous ne pouvez ajouter que des minds que vous possédez ou auxquels vous avez accès.

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

En-têtes :

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Corps de la requête

Un seul spark :

{
  "sparkId": "spark-789"
}

Plusieurs sparks :

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

Paramètres

Remarque : Vous devez fournir soit sparkId, soit sparkIds, mais pas les deux.

Réponse

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

Exemple de requête

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

Réponses d'erreur

400 Bad Request — sparkId/sparkIds manquant ou tableau vide

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

403 Forbidden — Limite de membres de l'offre atteinte

{
  "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 — Groupe non trouvé, vous n'en êtes pas le propriétaire, ou un ou plusieurs sparks ne sont pas accessibles

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

Retirer un membre d'un groupe

Retire un mind d'un groupe.

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

En-têtes :

Authorization: Bearer minds_your_api_key

Réponse

Returns 204 No Content with an empty body on success.

Exemple de requête

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

Réponses d'erreur

404 Not Found — Groupe non trouvé ou vous n'en êtes pas le propriétaire

Limites d'offre

Les différentes offres d'abonnement ont des limites de groupes différentes :

Lorsque vous atteignez la limite de votre offre, vous recevrez une erreur 403 avec les détails de mise à niveau.

Exemple de workflow

Voici un workflow complet pour créer et gérer des groupes :

# 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"

Résumé des codes d'erreur

Étapes suivantes

• Créer des minds à ajouter à vos groupes
• Utiliser des groupes dans des panels pour des sondages multi-sparks
• En savoir plus sur l'authentification
• Consulter les plan limits and errors