Groups API

Groups allow you to organize your AI minds (personas) into collections for use in panels, collaborative work, and easier management. A group can contain any minds you own or have access to, and can be used to survey multiple personas at once via the Panels API.

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

Concepts

List Groups

Retrieve all groups visible to the authenticated user, including owned groups, public groups, and groups shared with you.

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 Fields

Example Request

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

Create Group

Create a new group with an optional initial set of 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"]
}

Parameters

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

Example 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 - Missing name or invalid spark IDs

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

{
  "statusCode": 404,
  "message": "One or more sparks not found or not accessible"
}

403 Forbidden - Plan limit reached

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

Get Group Details

Retrieve details for a specific group, including all its members.

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

Example Request

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

Error Responses

404 Not Found - Group does not exist or you don't have access

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

Update Group

Update a group's name. Only the group owner can update the group.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

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

Parameters

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

Example 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 - Missing name

404 Not Found - Group not found or you're not the owner

Delete Group

Delete a group permanently. Only the group owner can delete a group. All group members will be removed, but the sparks themselves are not deleted.

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

Headers:

Authorization: Bearer minds_your_api_key

Response

{
  "success": true
}

Example Request

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

Error Responses

404 Not Found - Group not found or you're not the owner

Add Members to Group

Add one or more minds to a group. You can only add minds that you own or have access to.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body

Single spark:

{
  "sparkId": "spark-789"
}

Multiple sparks:

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

Parameters

Note: You must provide either sparkId or sparkIds, but not both.

Response

{
  "success": true,
  "added": 3
}

Example 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 - Missing sparkId/sparkIds or empty array

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

403 Forbidden - Plan member limit reached

{
  "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 - Group not found, you're not the owner, or one or more sparks not accessible

{
  "statusCode": 404,
  "message": "One or more sparks not found or not accessible"
}

Remove Member from Group

Remove a mind from a group.

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

Headers:

Authorization: Bearer minds_your_api_key

Response

{
  "success": true
}

Example 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 - Group not found or you're not the owner

Plan Limits

Different subscription plans have different group limits:

When you reach your plan limit, you'll receive a 403 error with details about upgrading.

Workflow Example

Here is a complete workflow for creating and managing groups:

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

Error Codes Summary

Next Steps

• Create minds to add to your groups
• Use groups in panels for multi-spark surveys
• Learn about authentication
• Review plan limits and errors