OverviewAuthenticationMindsKnowledgeChatLatencyErrors
Minds Team

グループAPI

AIペルソナを整理し、パネルを構築するためのマインドグループを作成・管理します。

グループを使用すると、AIマインド（ペルソナ）をコレクションに整理し、パネル、共同作業、管理を容易に行うことができます。グループには、所有しているマインドやアクセスできるマインドを含めることができ、パネルAPIを介して複数のペルソナを一度に調査するために使用できます。

ベースURL: https://getminds.ai/api/v1 または https://api.getminds.ai/v1

概念

概念説明
グループ一緒に整理されたAIマインドのコレクション（例："Z世代ユーザー"、"シニア開発者"）
グループメンバーグループに属するマインド
オーナーグループを作成し、完全な管理権を持つユーザー
プラン制限無料（1グループ、3メンバー）、プレミアム/チーム（無制限）

グループ一覧

認証されたユーザーが見ることのできるすべてのグループを取得します。これには、所有しているグループ、公開グループ、共有されたグループが含まれます。

エンドポイント: GET /api/v1/groups

ヘッダー:

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

レスポンスフィールド

フィールドタイプ説明
idstringユニークなグループ識別子
namestringグループ名
sparkCountnumberグループ内のマインドの数
sparksarrayすべてのグループメンバーの完全なマインド詳細
sparks[].idstringスパークID
sparks[].namestringスパーク名
sparks[].disciplinestringスパークの分野/役割
sparks[].profileImageUrlstringプロフィール画像のURL
createdAtstringISO 8601作成タイムスタンプ
updatedAtstringISO 8601最終更新タイムスタンプ
isPublicbooleanグループが公開されているかどうか
currentMemberRolestringあなたの役割: "owner", "admin", "member", "team_member", または "public_viewer"
isSharedWithTeambooleanあなたのチームと共有されているかどうか（オーナーのみ）
isLinkSharingEnabledbooleanリンク共有が有効かどうか（オーナーのみ）
publicShareIdstringリンク共有が有効な場合の公開共有ID（オーナーのみ）

例リクエスト

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

グループ作成

オプションの初期マインドセットを持つ新しいグループを作成します。

エンドポイント: POST /api/v1/groups

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ

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

パラメータ

パラメータタイプ必須説明
namestringはいグループの名前（最大255文字）
sparkIdsarrayいいえ初期メンバーとして追加するマインドIDの配列

レスポンス

{
  "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 - 名前が欠落しているか、無効なスパーク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
  }
}

グループ詳細取得

特定のグループの詳細を取得します。すべてのメンバーが含まれます。

エンドポイント: GET /api/v1/groups/{groupId}

ヘッダー:

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 - グループが存在しないか、アクセス権がありません

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

グループ更新

グループの名前を更新します。グループのオーナーのみが更新できます。

エンドポイント: PUT /api/v1/groups/{groupId}

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ

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

パラメータ

パラメータタイプ必須説明
namestringはいグループの新しい名前

レスポンス

{
  "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 - グループが見つからないか、オーナーではありません

グループ削除

グループを永久に削除します。グループのオーナーのみが削除できます。すべてのグループメンバーは削除されますが、スパーク自体は削除されません。

エンドポイント: DELETE /api/v1/groups/{groupId}

ヘッダー:

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 - グループが見つからないか、オーナーではありません

グループにメンバーを追加

1つ以上のマインドをグループに追加します。所有しているかアクセスできるマインドのみを追加できます。

エンドポイント: POST /api/v1/groups/{groupId}/members

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ

単一スパーク:

{
  "sparkId": "spark-789"
}

複数スパーク:

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

パラメータ

パラメータタイプ必須説明
sparkIdstringいいえ追加する単一マインドID
sparkIdsarrayいいえ追加するマインドIDの配列

注意: 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 - グループが見つからない、オーナーではない、または1つ以上のスパークにアクセスできない

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

グループからメンバーを削除

グループからマインドを削除します。

エンドポイント: DELETE /api/v1/groups/{groupId}/members/{sparkId}

ヘッダー:

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 - グループが見つからないか、オーナーではありません

プラン制限

異なるサブスクリプションプランには異なるグループ制限があります：

プラン最大グループ数グループあたりの最大メンバー数
無料13
プレミアム無制限無制限
チーム無制限無制限

プラン制限に達すると、アップグレードに関する詳細を含む403エラーが返されます。

ワークフロー例

グループを作成・管理するための完全なワークフローは以下の通りです：

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

エラーコードの概要

コード説明
400Bad Request - 必須フィールドが欠落しているか、無効なデータ
401Unauthorized - 無効または欠落したAPIキー
403Forbidden - プラン制限に達したか、変更する権限がない
404Not Found - グループまたはスパークが存在しないか、アクセスできない
500Internal Server Error - サーバー側のエラー

次のステップ