Groups API

Gruppen ermöglichen es Ihnen, Ihre KI-Minds (Personas) in Sammlungen zu organisieren – für die Verwendung in Panels, kollaborative Arbeit und einfachere Verwaltung. Eine Gruppe kann beliebige Minds enthalten, die Sie besitzen oder auf die Sie Zugriff haben, und sie lässt sich verwenden, um mehrere Personas gleichzeitig über die Panels API zu befragen.

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

Konzepte

Gruppen auflisten

Ruft alle Gruppen ab, die für den authentifizierten Benutzer sichtbar sind – einschließlich eigener Gruppen, öffentlicher Gruppen und mit Ihnen geteilter Gruppen.

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

Response-Felder

Beispiel-Request

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

Gruppe erstellen

Erstellt eine neue Gruppe mit einer optionalen anfänglichen Auswahl von 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"]
}

Parameter

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

Beispiel-Request

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

Error Responses

400 Bad Request – Fehlender Name oder ungültige Spark-IDs

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

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

403 Forbidden – Plan-Limit erreicht

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

Gruppendetails abrufen

Ruft Details für eine bestimmte Gruppe inklusive aller Mitglieder ab.

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

Beispiel-Request

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

Error Responses

404 Not Found – Gruppe existiert nicht oder Sie haben keinen Zugriff

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

Gruppe aktualisieren

Aktualisiert den Namen einer Gruppe. Nur der Gruppen-Owner kann die Gruppe aktualisieren.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

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

Parameter

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

Beispiel-Request

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

Error Responses

400 Bad Request – Fehlender Name

404 Not Found – Gruppe nicht gefunden oder Sie sind nicht der Owner

Gruppe löschen

Löscht eine Gruppe dauerhaft. Nur der Gruppen-Owner kann eine Gruppe löschen. Alle Gruppenmitglieder werden entfernt, die Sparks selbst werden jedoch nicht gelöscht.

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

Headers:

Authorization: Bearer minds_your_api_key

Response

Returns 204 No Content with an empty body on success.

Beispiel-Request

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

Error Responses

404 Not Found – Gruppe nicht gefunden oder Sie sind nicht der Owner

Mitglieder zu Gruppe hinzufügen

Fügt einen oder mehrere Minds zu einer Gruppe hinzu. Sie können nur Minds hinzufügen, die Sie besitzen oder auf die Sie Zugriff haben.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

Einzelner Spark:

{
  "sparkId": "spark-789"
}

Mehrere Sparks:

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

Parameter

Hinweis: Sie müssen entweder sparkId oder sparkIds angeben, aber nicht beides.

Response

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

Beispiel-Request

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

Error Responses

400 Bad Request – Fehlende sparkId/sparkIds oder leeres Array

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

403 Forbidden – Plan-Mitgliederlimit erreicht

{
  "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 – Gruppe nicht gefunden, Sie sind nicht der Owner, oder ein oder mehrere Sparks sind nicht zugänglich

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

Mitglied aus Gruppe entfernen

Entfernt einen Mind aus einer Gruppe.

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.

Beispiel-Request

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

Error Responses

404 Not Found – Gruppe nicht gefunden oder Sie sind nicht der Owner

Plan-Limits

Unterschiedliche Abonnement-Pläne haben unterschiedliche Gruppen-Limits:

Wenn Sie Ihr Plan-Limit erreichen, erhalten Sie einen 403-Fehler mit Details zum Upgrade.

Workflow-Beispiel

Hier ist ein vollständiger Workflow zum Erstellen und Verwalten von Gruppen:

# 1. Eine Gruppe mit initialen Mitgliedern erstellen
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. Weitere Mitglieder zur Gruppe hinzufügen
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. Gruppendetails abrufen, um alle Mitglieder zu sehen
curl -X GET "https://getminds.ai/api/v1/groups/group-abc" \
  -H "Authorization: Bearer minds_your_api_key"

# 4. Gruppennamen aktualisieren
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. Ein Mitglied entfernen
curl -X DELETE "https://getminds.ai/api/v1/groups/group-abc/members/spark-3" \
  -H "Authorization: Bearer minds_your_api_key"

# 6. Die Gruppe in einem Panel verwenden
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. Alle Gruppen auflisten
curl -X GET "https://getminds.ai/api/v1/groups" \
  -H "Authorization: Bearer minds_your_api_key"

Error Codes – Übersicht

Nächste Schritte

• Minds erstellen, die Sie Ihren Gruppen hinzufügen können
• Gruppen in Panels verwenden für Multi-Spark-Umfragen
• Mehr zur Authentifizierung erfahren
• Plan-Limits und Fehler nachlesen