Groups API

Group 允许你将 AI mind(persona)组织成集合,用于 panel、协作工作和更便捷的管理。一个 group 可以包含你拥有或有权访问的任意 mind,并可通过 Panels API 同时调研多个 persona。

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

概念

列出 Group

获取已认证用户可见的所有 group,包括自有 group、公开 group,以及分享给你的 group。

Endpoint: GET /api/v1/groups

Headers:

Authorization: Bearer minds_your_api_key

响应

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

响应字段

请求示例

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

创建 Group

创建新的 group,可选择性地附带初始 mind 集合。

Endpoint: POST /api/v1/groups

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体

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

参数

响应

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

请求示例

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

错误响应

400 Bad Request - 名称缺失或 spark ID 无效

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

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

403 Forbidden - 达到计划限制

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

获取 Group 详情

获取特定 group 的详情,包括所有成员。

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

Headers:

Authorization: Bearer minds_your_api_key

响应

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

请求示例

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

错误响应

404 Not Found - Group 不存在或你无访问权限

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

更新 Group

更新 group 的名称。只有 group owner 才能更新 group。

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体

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

参数

响应

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

请求示例

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

错误响应

400 Bad Request - 名称缺失

404 Not Found - Group 不存在或你不是 owner

删除 Group

永久删除 group。只有 group owner 才能删除。所有 group 成员将被移除,但 spark 本身不会被删除。

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

Headers:

Authorization: Bearer minds_your_api_key

响应

Returns 204 No Content with an empty body on success.

请求示例

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

错误响应

404 Not Found - Group 不存在或你不是 owner

向 Group 添加成员

向 group 添加一个或多个 mind。你只能添加你拥有或有权访问的 mind。

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体

单个 spark:

{
  "sparkId": "spark-789"
}

多个 spark:

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

参数

注意: 你必须提供 sparkId 或 sparkIds 之一,但不能同时提供。

响应

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

请求示例

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

错误响应

400 Bad Request - 缺少 sparkId/sparkIds 或数组为空

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

403 Forbidden - 达到计划成员限制

{
  "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 不存在、你不是 owner,或一个或多个 spark 无法访问

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

从 Group 移除成员

将 mind 从 group 中移除。

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

Headers:

Authorization: Bearer minds_your_api_key

响应

Returns 204 No Content with an empty body on success.

请求示例

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

错误响应

404 Not Found - Group 不存在或你不是 owner

计划限制

不同订阅计划有不同的 group 限制:

达到计划限制时,你将收到 403 错误,附带升级相关详情。

工作流示例

下面是一个完整的创建与管理 group 的工作流:

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

错误码速查

下一步

• 创建 mind 以添加到你的 group
• 在 panel 中使用 group 进行多 spark 调研
• 了解 身份验证
• 查看 计划限制与错误