Groups API

Gruplar, AI mind'larınızı (persona) panellerde kullanmak, işbirlikçi çalışma ve daha kolay yönetim için koleksiyonlar halinde düzenlemenize olanak tanır. Bir grup, sahip olduğunuz veya erişiminiz olan herhangi bir mind'ı içerebilir ve Panels API aracılığıyla birden fazla personayı aynı anda ankete dahil etmek için kullanılabilir.

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

Kavramlar

Grupları Listele

Kimliği doğrulanmış kullanıcıya görünen tüm grupları al; sahip olunan gruplar, public gruplar ve sizinle paylaşılan gruplar dahil.

Endpoint: GET /api/v1/groups

Headers:

Authorization: Bearer minds_your_api_key

Yanıt

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

Yanıt Alanları

Örnek İstek

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

Grup Oluştur

İsteğe bağlı bir ilk mind seti ile yeni bir grup oluşturun.

Endpoint: POST /api/v1/groups

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

İstek Body

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

Parametreler

Yanıt

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

Örnek İstek

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

Hata Yanıtları

400 Bad Request - Eksik ad veya geçersiz spark ID'leri

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

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

403 Forbidden - Plan limitine ulaşıldı

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

Grup Detaylarını Al

Tüm üyeleri dahil olmak üzere belirli bir grup için ayrıntıları al.

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

Headers:

Authorization: Bearer minds_your_api_key

Yanıt

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

Örnek İstek

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

Hata Yanıtları

404 Not Found - Grup mevcut değil veya erişiminiz yok

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

Grup Güncelle

Bir grubun adını güncelleyin. Yalnızca grup sahibi grubu güncelleyebilir.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

İstek Body

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

Parametreler

Yanıt

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

Örnek İstek

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

Hata Yanıtları

400 Bad Request - Eksik ad

404 Not Found - Grup bulunamadı veya owner değilsiniz

Grup Sil

Bir grubu kalıcı olarak silin. Yalnızca grup sahibi bir grubu silebilir. Tüm grup üyeleri kaldırılır, ancak spark'ların kendileri silinmez.

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

Headers:

Authorization: Bearer minds_your_api_key

Yanıt

Returns 204 No Content with an empty body on success.

Örnek İstek

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

Hata Yanıtları

404 Not Found - Grup bulunamadı veya owner değilsiniz

Gruba Üye Ekle

Bir gruba bir veya daha fazla mind ekleyin. Yalnızca sahip olduğunuz veya erişiminiz olan mind'ları ekleyebilirsiniz.

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

İstek Body

Tek spark:

{
  "sparkId": "spark-789"
}

Çoklu spark:

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

Parametreler

Not: sparkId veya sparkIds'den birini sağlamalısınız, ancak ikisini birden değil.

Yanıt

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

Örnek İstek

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

Hata Yanıtları

400 Bad Request - Eksik sparkId/sparkIds veya boş dizi

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

403 Forbidden - Plan üye limitine ulaşıldı

{
  "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 - Grup bulunamadı, owner değilsiniz veya bir veya daha fazla spark erişilebilir değil

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

Gruptan Üye Kaldır

Bir mind'ı gruptan kaldırın.

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

Headers:

Authorization: Bearer minds_your_api_key

Yanıt

Returns 204 No Content with an empty body on success.

Örnek İstek

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

Hata Yanıtları

404 Not Found - Grup bulunamadı veya owner değilsiniz

Plan Limitleri

Farklı abonelik planlarının farklı grup limitleri vardır:

Plan limitinize ulaştığınızda, yükseltme ile ilgili ayrıntılar içeren bir 403 hatası alırsınız.

İş Akışı Örneği

Grupları oluşturmak ve yönetmek için eksiksiz bir iş akışı:

# 1. İlk üyelerle bir grup oluştur
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. Gruba daha fazla üye ekle
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. Tüm üyeleri görmek için grup detaylarını al
curl -X GET "https://getminds.ai/api/v1/groups/group-abc" \
  -H "Authorization: Bearer minds_your_api_key"

# 4. Grup adını güncelle
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. Bir üyeyi kaldır
curl -X DELETE "https://getminds.ai/api/v1/groups/group-abc/members/spark-3" \
  -H "Authorization: Bearer minds_your_api_key"

# 6. Grubu bir panelde kullan
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. Tüm grupları listele
curl -X GET "https://getminds.ai/api/v1/groups" \
  -H "Authorization: Bearer minds_your_api_key"

Hata Kodları Özeti

Sonraki Adımlar

• Gruplarınıza eklemek için mind oluşturun
• Çoklu spark anketleri için grupları panellerde kullanın
• Kimlik doğrulama hakkında bilgi edinin
• Plan limitleri ve hataları inceleyin