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

응답 필드

필드유형설명
id문자열고유한 그룹 식별자
name문자열그룹 이름
sparkCount숫자그룹 내 마인드 수
sparks배열모든 그룹 구성원의 전체 마인드 세부정보
sparks[].id문자열스파크 ID
sparks[].name문자열스파크 이름
sparks[].discipline문자열스파크 분야/역할
sparks[].profileImageUrl문자열프로필 이미지 URL
createdAt문자열ISO 8601 생성 타임스탬프
updatedAt문자열ISO 8601 마지막 업데이트 타임스탬프
isPublic불리언그룹이 공개적으로 보이는지 여부
currentMemberRole문자열귀하의 역할: "owner", "admin", "member", "team_member", 또는 "public_viewer"
isSharedWithTeam불리언귀하의 팀과 공유되었는지 여부 (소유자 전용)
isLinkSharingEnabled불리언링크 공유가 활성화되었는지 여부 (소유자 전용)
publicShareId문자열링크 공유가 활성화된 경우 공개 공유 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"]
}

매개변수

매개변수유형필수설명
name문자열예그룹 이름 (최대 255자)
sparkIds배열아니오초기 구성원으로 추가할 마인드 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 잘못된 요청 - 이름이 누락되었거나 유효하지 않은 스파크 ID

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

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

403 금지됨 - 플랜 한도 초과

{
  "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 찾을 수 없음 - 그룹이 존재하지 않거나 접근할 수 없음

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

매개변수

매개변수유형필수설명
name문자열예그룹의 새 이름

응답

{
  "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 잘못된 요청 - 이름이 누락됨

404 찾을 수 없음 - 그룹을 찾을 수 없거나 소유자가 아님

그룹 삭제

그룹을 영구적으로 삭제합니다. 그룹 소유자만 그룹을 삭제할 수 있습니다. 모든 그룹 구성원이 제거되지만 스파크 자체는 삭제되지 않습니다.

엔드포인트: 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 찾을 수 없음 - 그룹을 찾을 수 없거나 소유자가 아님

그룹에 구성원 추가

하나 이상의 마인드를 그룹에 추가합니다. 소유하거나 접근할 수 있는 마인드만 추가할 수 있습니다.

엔드포인트: 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"]
}

매개변수

매개변수유형필수설명
sparkId문자열아니오추가할 단일 마인드 ID
sparkIds배열아니오추가할 마인드 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 잘못된 요청 - sparkId/sparkIds가 누락되었거나 빈 배열

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

403 금지됨 - 플랜 구성원 한도 초과

{
  "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 찾을 수 없음 - 그룹을 찾을 수 없거나 소유자가 아니거나 하나 이상의 스파크에 접근할 수 없음

{
  "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 찾을 수 없음 - 그룹을 찾을 수 없거나 소유자가 아님

플랜 한도

다양한 구독 플랜은 서로 다른 그룹 한도를 가지고 있습니다:

플랜최대 그룹 수그룹당 최대 구성원 수
무료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"

오류 코드 요약

코드설명
400잘못된 요청 - 필수 필드 누락 또는 유효하지 않은 데이터
401인증되지 않음 - 유효하지 않거나 누락된 API 키
403금지됨 - 플랜 한도 초과 또는 수정 권한 없음
404찾을 수 없음 - 그룹 또는 스파크가 존재하지 않거나 접근할 수 없음
500내부 서버 오류 - 서버 측 오류

다음 단계