Sparks API

AI mind'ları (ajanlar) programatik olarak oluşturun ve yönetin. Mind'lar, belirli uzmanlık, kişilik ve bilgiye sahip özelleştirilebilir AI asistanlardır.

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

Spark Al

System prompt, paylaşım ayarları ve bilgi öğesi sayısı dahil olmak üzere tam ayrıntılarla tek bir mind alın.

Endpoint: GET /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key

Yanıt

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Expert",
    "description": "Experienced marketing director",
    "type": "expert",
    "discipline": "Marketing",
    "systemPrompt": "## Core Identity & Personality\n\nYou are a seasoned marketing director...",
    "tags": ["marketing", "b2b"],
    "isPublic": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null,
    "profileImageUrl": "https://...",
    "phoneNumber": null,
    "clonedVoiceStatus": null,
    "profitSplitOptIn": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z",
    "knowledgeItemCount": 12
  }
}

Yanıt Alanları

Örnek İstek

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

Hata Yanıtları

400 Bad Request - Geçersiz spark ID formatı

401 Unauthorized - Geçersiz veya eksik API key

403 Forbidden - Bu mind'a erişim yok

404 Not Found - Mind mevcut değil

Spark'ları Listele

Kimliği doğrulanmış kullanıcıya ait tüm mind'ları al.

Endpoint: GET /api/v1/sparks

Headers:

Authorization: Bearer minds_your_api_key

Sorgu Parametreleri

Yanıt

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Expert",
      "description": "Experienced marketing director",
      "type": "expert",
      "discipline": "Marketing",
      "tags": ["marketing", "b2b"],
      "profileImageUrl": "https://...",
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 100,
    "offset": 0
  }
}

Yanıt Alanları

Örnek İstek

curl -X GET "https://getminds.ai/api/v1/sparks?limit=10&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"

Spark Oluştur

Farklı eğitim modlarını kullanarak özel yapılandırmayla yeni bir AI mind oluşturun.

Endpoint: POST /api/v1/sparks

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

İstek Body

{
  "name": "My AI Expert",
  "description": "An expert in renewable energy",
  "mode": "keywords",
  "type": "expert",
  "discipline": "Renewable Energy",
  "keywords": ["solar", "wind energy", "sustainability", "green tech"],
  "personaContext": "Ada Lovelace, pioneering computer scientist",
  "contextLink": "https://example.com/profile",
  "tags": ["energy", "solar", "sustainability"],
  "profileImageUrl": "https://example.com/avatar.jpg"
}

Parametreler

Mode Değerleri

mode parametresi, mind'ınızın nasıl eğitileceğini belirler:

• keywords (varsayılan) - Mind'ınızı virgülle ayrılmış anahtar kelimeler kullanarak eğitin. AI, mind'ın bilgi tabanını oluşturmak için bu anahtar kelimelere dayalı çeşitli kaynaklardan ilgili bilgileri toplayacaktır.
  • Zorunlu alan: keywords - Anahtar kelimeler/konular dizisi
  • En uygun: Belirli konular veya alanlarda genel uzmanlık için
• clone - Bir kişinin tarzını ve bilgisini adlarını ve bağlamlarını sağlayarak klonlayın. AI, uzmanlıklarını ve iletişim tarzlarını taklit eden kapsamlı bir profil araştıracak ve oluşturacaktır.
  • Zorunlu alan: personaContext - Ad ve kısa bağlam (örn. "Ada Lovelace, pioneering computer scientist")
  • En uygun: Belirli kişileri, tarihi figürleri veya tanınmış uzmanları taklit etmek için
• link - Mind'ınızı belirli bir URL'den alınan içerikle eğitin. Bir profile, portfolyoya veya web sitesine bağlantı sağlayın; AI ilgili bilgileri analiz edip çıkaracaktır.
  • Zorunlu alan: contextLink - İçerik kaynağına URL
  • En uygun: Belirli web sitelerinden, portföylerden veya çevrimiçi profillerden eğitim için
• manual - Otomatik eğitim olmadan bir mind oluşturun. Tüm ayarları manuel olarak yapılandıracak ve daha sonra knowledge API aracılığıyla bilgi ekleyeceksiniz.
  • Ek alan gerekmez
  • En uygun: Eğitim verileri üzerinde tam kontrol istediğiniz özel yapılandırmalar için

Otomatik işleme: keywords, clone veya link kullandığınızda, backend ürün içi Add Spark formunu yansıtır — entity anahtar kelimelerini türetir (clone/link için AI destekli) ve mind'ı asenkron olarak eğitir. Bu eğitimi, oluşturma yanıtındaki training bloğu ve aşağıdaki Mind eğitim yaşam döngüsü bölümünde açıklanan özel uç nokta üzerinden izleyin. manual modu bu otomasyonu atlar, böylece mind'ı daha sonra Knowledge API aracılığıyla eğitebilirsiniz.

Type Değerleri

• creative - Sanatçılar, tasarımcılar, yazarlar ve yaratıcı profesyoneller için
• expert - Uzmanlar, danışmanlar ve alan uzmanları için
• user - Kullanıcı personaları, müşteriler ve hedef kitle arketipleri için

Yanıt

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My AI Expert",
    "description": "An expert in renewable energy",
    "type": "expert",
    "discipline": "Renewable Energy",
    "tags": ["energy", "solar", "sustainability"],
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z"
  },
  "training": {
    "status": "queued",
    "readyToChat": false,
    "message": "Queued for data collection",
    "startedAt": null,
    "completedAt": null,
    "error": null
  }
}

training bloğu, mind'ın oluşturma anındaki yaşam döngüsünü bildirir. keywords, clone ve link modları queued olarak başlar ve arka planda eğitilir; manual mind'lar readyToChat zaten true olacak şekilde completed döner. Bir mind'ın id'si bu çağrı döndüğü anda vardır, ancak mind yalnızca readyToChat true olduğunda yanıt verebilir. Yoklama için aşağıdaki Mind eğitim yaşam döngüsü bölümüne bakın.

Örnek: Keywords Modu ile Mind Oluştur

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Experienced marketing director with expertise in B2B SaaS",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["B2B marketing", "SaaS", "growth marketing", "content strategy", "brand positioning", "ROI"],
    "tags": ["marketing", "b2b", "saas", "growth"]
  }'

Örnek: Clone Modu ile Mind Oluştur

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace AI",
    "description": "AI trained to emulate Ada Lovelace",
    "mode": "clone",
    "type": "expert",
    "discipline": "Computer Science Pioneer",
    "personaContext": "Ada Lovelace, pioneering computer scientist and mathematician, first computer programmer",
    "tags": ["computer science", "mathematics", "history"]
  }'

Örnek: Link Modu ile Mind Oluştur

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Voice Expert",
    "description": "Trained on company brand guidelines",
    "mode": "link",
    "type": "creative",
    "discipline": "Brand Strategy",
    "contextLink": "https://example.com/brand-guidelines",
    "tags": ["branding", "copywriting"]
  }'

Örnek: Manual Modu ile Mind Oluştur

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Assistant",
    "description": "Custom configured assistant",
    "mode": "manual",
    "type": "creative",
    "discipline": "General Assistant",
    "tags": ["custom"]
  }'

Mind eğitim yaşam döngüsü

Bir mind oluşturmak asenkrondur. POST /v1/sparks hemen bir id döndürür, ancak keywords, clone ve link modlarında mind hâlâ arka planda eğitilmektedir. Bir mind'ın id'sinin var olması, mind'ın hazır olduğu anlamına gelmez — mind yalnızca readyToChat true olduğunda yanıt verebilir. Tek istisna manual modudur: bu mind'lar veri toplamayı atlar ve oluşturuldukları anda completed olur.

Mind hazır olana kadar özel eğitim uç noktasını yoklayın:

curl "https://getminds.ai/api/v1/sparks/{sparkId}/training" \
  -H "Authorization: Bearer minds_your_api_key"

{
  "status": "running",
  "readyToChat": false,
  "message": "Collecting knowledge...",
  "startedAt": "2025-12-10T12:00:01.000Z",
  "completedAt": null,
  "error": null
}

Durum değerleri

GET /v1/sparks/{id} de mind'ın geri kalanıyla birlikte readyToChat (ve trainingStatus) döndürür; böylece tek bir okuma size hem mind'ın kim olduğunu hem de henüz yanıt verip veremeyeceğini söyler.

Eğitim başarısız olduğunda

status failed olduğunda, yanıt bir code ve bir retryable bayrağı içeren bir error nesnesi içerir:

Yeniden eğitim

Bir mind failed ile biterse (ya da yalnızca completed bir mind'ı yeniden oluşturmak isterseniz) onu yeniden eğitin:

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/retrain" \
  -H "Authorization: Bearer minds_your_api_key"

Bu, mind'ı yeniden kuyruğa alır ve status değeri queued olan yeni bir training bloğu döndürür. Yeniden eğitim yalnızca tamamlanmış mind'larda çalışır: hâlâ queued veya running olan bir mind, zaten bir eğitim çalışması sürdüğü için 409 Conflict döndürür. Yeniden eğitimden sonra, readyToChat true olana kadar GET /v1/sparks/{id}/training'i tekrar yoklayın.

Profil Resimleri

Bir profileImageUrl sağladığınızda:

1. Resim harici URL'den indirilir
2. Güvenli depolamaya yüklenir
3. Saklanan URL yanıtta döndürülür

Desteklenen formatlar: JPG, PNG, GIF, WEBP

Eğitim Nasıl Çalışır

Sistem, seçtiğiniz mod, tip ve disipline dayalı olarak akıllı bir system prompt'u otomatik olarak oluşturur:

• Keywords modu: Belirttiğiniz anahtar kelimeler etrafında uzmanlık oluşturur
• Clone modu: Belirtilen kişinin tarzını ve bilgisini taklit eden bir profil oluşturur
• Link modu: Sağlanan URL'den bilgi çıkarır
• Manual modu: Özel bilgi ile eğiteceğiniz temel bir asistan oluşturur

Mind'ınızı oluşturduktan sonra bilgi yükleyerek daha da geliştirebilirsiniz.

Plan Limitleri

Farklı planların farklı mind oluşturma limitleri vardır:

Limitinize ulaştığınızda, 403 Forbidden hatası alırsınız:

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

Hata Yanıtları

400 Bad Request

Eksik veya geçersiz parametreler.

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

401 Unauthorized

Geçersiz veya eksik API key.

403 Forbidden

Plan limitine ulaşıldı.

500 Internal Server Error

Sunucu tarafı hata (nadir).

Spark Güncelle

Ad, açıklama, system prompt ve diğer ayarlar dahil olmak üzere mevcut bir mind'ın yapılandırmasını güncelleyin.

Endpoint: PUT /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

İstek Body

{
  "name": "Updated Name",
  "description": "Updated description",
  "type": "expert",
  "discipline": "Updated Discipline",
  "systemPrompt": "Custom system prompt instructions...",
  "tags": ["tag1", "tag2"],
  "isPublic": false
}

Parametreler

System Prompt

systemPrompt alanı, mind'ınızın nasıl davranacağını ve yanıt vereceğini özelleştirmenize olanak tanır. Bu şunlar için kullanışlıdır:

• Persona özelleştirme: Belirli kişilik özellikleri, iletişim tarzı veya uzmanlık alanları tanımlama
• Yanıt formatı: Mind'a belirli formatlarda yanıt vermesini söyleme (örn. madde işaretleri, numaralı listeler)
• Alan kısıtlamaları: Yanıtları belirli konular veya bakış açılarıyla sınırlama
• Dil/ton: Yanıtların dilini, resmiyet düzeyini veya tonunu ayarlama

Örnek system prompt'lar:

# Survey Response Expert
Du bist ein erfahrener Handwerker. Bei Umfragen antworte immer aus deiner
persönlichen Erfahrung, nicht mit allgemeinen Branchendurchschnittswerten.
Wähle bei Multiple-Choice-Fragen immer genau eine Option.

# Technical Expert
You are a senior software architect. Always provide concrete,
actionable advice. Include code examples when relevant.
Avoid vague statements.

Yanıt

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Name",
    "description": "Updated description",
    "type": "expert",
    "discipline": "Updated Discipline",
    "systemPrompt": "Custom system prompt...",
    "tags": ["tag1", "tag2"],
    "isPublic": false,
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-29T15:30:00.000Z"
  }
}

Örnek: System Prompt Güncelle

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "Du bist ein erfahrener Handwerker im Sanitärbereich. Antworte immer aus deiner persönlichen Praxiserfahrung."
  }'

Örnek: Birden Fazla Alanı Güncelle

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Plumber Expert",
    "description": "Expert plumber with 20 years of experience",
    "discipline": "Plumbing & Sanitary Installation",
    "tags": ["plumbing", "sanitary", "renovation"]
  }'

Hata Yanıtları

400 Bad Request - Güncellenecek geçerli alan yok veya geçersiz alan değerleri

401 Unauthorized - Geçersiz veya eksik API key

403 Forbidden - Bu mind'ı güncelleme izni yok (owner olmalısınız)

404 Not Found - Mind mevcut değil

Spark Bilgi Örüntülerini Al

Belirli bir mind için düşünme örüntülerini ve çerçeveye göre düzenlenmiş bilgiyi al.

Endpoint: GET /api/v1/sparks/{sparkId}/knowledge/patterns

Headers:

Authorization: Bearer minds_your_api_key

Yanıt Yapısı

Endpoint, çerçevelere göre gruplandırılmış örüntüleri döndürür (örn. AOX Internal, OCEAN, DISC, vb.), yöntemler ve yetkinlikler, görülme sayılarını ve kanıtları gösterir.

{
  "success": true,
  "data": {
    "sparkId": "550e8400-e29b-41d4-a716-446655440000",
    "sparkName": "Marketing Expert",
    "totalPatterns": 47,
    "frameworks": [
      {
        "id": "aox-internal",
        "name": "AOX Internal Framework",
        "totalOccurrences": 32,
        "methods": [
          {
            "id": "strategic-thinking",
            "name": "Strategic Thinking",
            "description": "Ability to think strategically and plan long-term",
            "occurrences": 15,
            "competencies": [
              {
                "id": "market-analysis",
                "name": "Market Analysis",
                "description": "Understanding market dynamics and trends",
                "occurrences": 8,
                "evidence": [
                  {
                    "spark": "Market segmentation requires understanding customer pain points and aligning product features with specific needs...",
                    "portfolioItemId": "abc-123",
                    "createdAt": "2025-12-10T15:30:00.000Z"
                  },
                  {
                    "spark": "Competitive analysis shows that timing and positioning are critical for market entry...",
                    "portfolioItemId": "def-456",
                    "createdAt": "2025-12-10T14:20:00.000Z"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Yanıtı Anlamak

• frameworks: Spark'ın örüntülerini içeren çerçevelerin dizisi
  • totalOccurrences: Bu çerçevedeki toplam örüntü sayısı
  • methods: Tespit edilen düşünme yöntemleri veya yaklaşımları
    • occurrences: Bu yöntemin kaç kez göründüğü
    • competencies: Yöntem içindeki belirli beceriler veya alt alanlar
      • occurrences: Bu yetkinlik için örüntü sayısı
      • evidence: Bu örüntüyü gösteren alıntıların/kanıtların dizisi
        • spark: İçerikten gerçek alıntı veya öngörü
        • portfolioItemId: Kaynak materyale referans
        • createdAt: Bu örüntünün ne zaman tespit edildiği

Örnek İstek

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}/knowledge/patterns" \
  -H "Authorization: Bearer minds_your_api_key"

Kullanım Senaryoları

• Mind uzmanlığını anlama: Mind'ınızın hangi yöntemleri ve yetkinlikleri öğrendiğini görün
• Kalite güvencesi: Örüntülerin eğitim verilerinden doğru şekilde çıkarıldığını doğrulayın
• Bilgi boşlukları: Daha fazla eğitim verisine ihtiyaç duyulan alanları belirleyin
• Çerçeve karşılaştırması: Bir mind'ın farklı çerçevelerde nasıl performans gösterdiğini karşılaştırın

Hata Yanıtları

401 Unauthorized - Geçersiz veya eksik API key

403 Forbidden - Bu mind'a erişim yok

404 Not Found - Mind mevcut değil

System Prompt'u Yeniden Oluştur

Mevcut bilgi tabanını kullanarak bir spark için tüm system prompt bileşenlerini yeniden oluşturun. Bu, UI'nin "Generate All" düğmesiyle aynı AI destekli oluşturmayı kullanır.

Endpoint: POST /api/v1/sparks/{sparkId}/regenerate-prompt

Headers:

Authorization: Bearer minds_your_api_key

Nasıl Çalışır

Endpoint, mind'ın bilgi tabanını (portfolio öğeleri, örüntüler, embedding'ler) analiz eder ve tüm prompt bileşenlerini oluşturur:

user tipi spark'lar için:

• Core Identity & Demographics
• Needs & Motivations
• Pain Points & Challenges
• Tone & Communication Style
• Goals & Desires
• Behavioral Patterns

expert tipi spark'lar için:

• Core Identity & Personality
• Professional Expertise & Credentials
• Tone & Communication Style
• Professional Approach & Methods
• Domain Knowledge

creative tipi spark'lar için:

• Core Identity & Personality
• Creative Philosophy & Values
• Tone & Communication Style
• Creative Approach & Methods
• Domain Expertise

Yanıt

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Spark",
    "systemPrompt": "## Core Identity & Demographics\n\n...",
    "promptLength": 2847
  }
}

Örnek İstek

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/regenerate-prompt" \
  -H "Authorization: Bearer minds_your_api_key"

Kullanım Senaryoları

• Bilgi ekledikten sonra: Yeni eklenen bilgi öğelerini dahil etmek için prompt'u yeniden oluşturun
• Persona iyileştirme: Mevcut bilgi örüntülerine dayalı olarak personayı güncellemek için yeniden oluşturun
• Özelleştirmeleri sıfırla: Manuel düzenlemeleri temizleyin ve bilgi tabanından yeni prompt'lar yeniden oluşturun

Hata Yanıtları

401 Unauthorized - Geçersiz veya eksik API key

403 Forbidden - Bu mind'ı değiştirme izni yok (owner olmalısınız)

404 Not Found - Mind mevcut değil

500 Internal Server Error - Prompt oluşturulamadı (örn. yetersiz bilgi)

Spark Sil

Bilgi, portfolio öğeleri ve dosyalar dahil olmak üzere bir mind'ı ve ilişkili tüm verileri kalıcı olarak silin.

Endpoint: DELETE /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key

Yanıt

Başarılı olduğunda boş bir body ile 204 No Content döndürür.

Örnek İstek

curl -X DELETE "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

Nelerin Silineceği

Bir mind sildiğinizde, aşağıdakiler kalıcı olarak kaldırılır:

• Mind'ın kendisi ve tüm yapılandırma
• Tüm bilgi ve eğitim verileri
• Tüm portfolio öğeleri ve ilişkili dosyalar
• Tüm sohbet geçmişi ve mesajlar
• Profil resimleri ve yüklenen dosyalar

Uyarı: Bu eylem geri alınamaz.

Hata Yanıtları

400 Bad Request - Geçersiz spark ID formatı

401 Unauthorized - Geçersiz veya eksik API key

403 Forbidden - Bu mind'ı silme izni yok (owner olmalısınız)

404 Not Found - Mind mevcut değil

Sonraki Adımlar

• Mind'ınıza bilgi yükleyin
• Mind'ınızla sohbet edin
• Hatalar ve limitler hakkında bilgi edinin