Groups API

تتيح لك Groups تنظيم الـ AI minds (الشخصيات) الخاصة بك في مجموعات للاستخدام في الـ panels والعمل التعاوني وتسهيل الإدارة. يمكن أن تحتوي مجموعة على أي minds تملكها أو لديك وصول إليها، ويمكن استخدامها لاستطلاع عدة شخصيات مرة واحدة عبر Panels API.

Base URL: https://getminds.ai/api/v1 أو https://api.getminds.ai/v1

المفاهيم

List Groups

استرجع جميع المجموعات المرئية للمستخدم المصادق، بما في ذلك المجموعات المملوكة والمجموعات العامة والمجموعات المشاركة معك.

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"

Create Group

أنشئ مجموعة جديدة مع مجموعة أولية اختيارية من الـ minds.

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 غير صالحة

{
  "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 Group Details

استرجع تفاصيل مجموعة محددة، بما في ذلك جميع أعضائها.

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 — المجموعة غير موجودة أو ليس لديك صلاحية الوصول

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

Update 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 — المجموعة غير موجودة أو لست المالك

Delete Group

احذف مجموعة بشكل دائم. يمكن لمالك المجموعة فقط حذفها. ستُزال جميع أعضاء المجموعة، لكن الـ sparks نفسها لن تُحذف.

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 — المجموعة غير موجودة أو لست المالك

Add Members to Group

أضف mind واحد أو أكثر إلى مجموعة. يمكنك إضافة minds التي تملكها أو لديك وصول إليها فقط.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

جسم الطلب

spark واحد:

{
  "sparkId": "spark-789"
}

عدة sparks:

{
  "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 — المجموعة غير موجودة، أو لست المالك، أو أحد الـ sparks أو أكثر غير قابل للوصول

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

Remove Member from Group

أزِل mind من مجموعة.

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 — المجموعة غير موجودة أو لست المالك

حدود الباقات

تختلف حدود المجموعات باختلاف باقات الاشتراك:

عند الوصول إلى حد باقتك، ستتلقى خطأ 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"

ملخص رموز الأخطاء

الخطوات التالية

• أنشئ minds لإضافتها إلى مجموعاتك
• استخدم المجموعات في الـ panels لاستطلاعات متعددة الـ sparks
• تعرّف على authentication
• راجع حدود الباقة والأخطاء