API Genel Bakış

Minds API dokümantasyonuna hoş geldiniz. API'miz, AI mind'ları programatik olarak oluşturup yönetmenizi, bilgi yüklemenizi ve onlarla etkileşim kurmanızı sağlar.

Başlarken

Minds API, REST prensipleri etrafında düzenlenmiştir. API'miz öngörülebilir kaynak odaklı URL'lere sahiptir, JSON kodlanmış istek body'leri kabul eder, JSON kodlanmış yanıtlar döndürür ve standart HTTP yanıt kodları, kimlik doğrulama ve verbler kullanır.

Base URL

Production: https://getminds.ai/api/v1 veya https://api.getminds.ai/v1

Yerel Geliştirme: http://localhost:3000/api/v1

Her iki production base URL'i tamamen eşdeğerdir. Daha temiz entegrasyon URL'leri için api.getminds.ai subdomain'i önerilir.

Kimlik Doğrulama

Tüm API endpoint'leri API key ile kimlik doğrulaması gerektirir. API key'lerinizi Settings → API Keys sayfasında oluşturup yönetebilirsiniz.

API key'inizi Authorization header'ına ekleyin:

Authorization: Bearer minds_your_api_key_here

OpenAPI Spesifikasyonu

Makine tarafından okunabilir bir OpenAPI 3.1.0 spesifikasyonu /_openapi.json adresinde yayımlanır. Spesifikasyonu tip güvenli istemciler (TypeScript, Python vb.) üretmek veya tek seferlik entegrasyon kodu için bir LLM'e bırakmak amacıyla kullan. Örnekler için OpenAPI sayfasına bak.

Content Type

Veri gönderen tüm istekler Content-Type header'ını içermelidir:

Content-Type: application/json

Dosya yüklemeleri için şunu kullanın:

Content-Type: multipart/form-data

Mevcut Endpoint'ler

Minds

Özel yapılandırmalarla AI mind'lar (ajanlar) oluşturun ve yönetin.

• GET /api/v1/minds - Tüm Mind'ları listele
• GET /api/v1/minds/{mindId} - Mind detaylarını al
• POST /api/v1/minds - Yeni bir Mind oluştur
• PUT /api/v1/minds/{mindId} - Bir Mind'ı güncelle
• DELETE /api/v1/minds/{mindId} - Bir Mind'ı sil
• POST /api/v1/minds/{mindId}/regenerate-prompt - Bilgilerden system prompt'u yeniden oluştur

Knowledge

Mind'larınız için bilgi yönetin.

• GET /api/v1/minds/{mindId}/knowledge - Bilgi öğelerini listele
• POST /api/v1/minds/{mindId}/knowledge - Bilgi ekle (bağlantılar, dosyalar veya anahtar kelime araması)
• PUT /api/v1/minds/{mindId}/knowledge/{itemId} - Bir bilgi öğesini güncelle
• DELETE /api/v1/minds/{mindId}/knowledge/{itemId} - Bir bilgi öğesini sil
• POST /api/v1/minds/{mindId}/knowledge/enrich - Anahtar kelime araması ile zenginleştir (kısayol)
• GET /api/v1/minds/{mindId}/knowledge/patterns - Çerçeveye göre bilgi örüntülerini al

Chat

Chat tamamlamaları aracılığıyla mind'larınızla etkileşim kurun.

• POST /api/v1/minds/{mindId}/completion - Mesaj gönder ve yanıt al

Studies

Mind audiencesını anketlemek için AI studyler oluşturun ve yönetin.

• GET /api/v1/studies - Tüm studyleri listele
• POST /api/v1/studies - Yeni bir study oluştur
• GET /api/v1/studies/{studyId} - Mesaj geçmişiyle birlikte study detaylarını al
• POST /api/v1/studies/{studyId}/ask - Studydeki tüm mind'lara bir soru sor (SSE stream)
• POST /api/v1/studies/{studyId}/export - Study sonuçlarını rapor olarak dışa aktar
• GET /api/v1/studies/{studyId}/export-status - Dışa aktarma job durumunu kontrol et
• GET /api/v1/studies/{studyId}/export-download - Dışa aktarılan PDF'i indir

User

Kullanıcıyla ilgili endpoint'ler.

• GET /api/v1/auth/me - Şu anki kimliği doğrulanmış kullanıcıyı al
• GET /api/v1/user/shareable-sparks - Paylaşım için uygun mind'ları listele

API Keys

Kimlik doğrulama için API key'lerinizi yönetin.

• GET /api/v1/api-keys - API key'lerinizi listele
• POST /api/v1/api-keys - Yeni bir API key oluştur
• DELETE /api/v1/api-keys/{keyId} - Bir API key'i sil

Hızlı Örnek

Bir mind oluşturup onunla sohbet etmenin hızlı bir örneği:

# 1. Bir mind oluştur (keywords modu)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Expert in digital marketing strategies",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["SEO", "content marketing", "social media", "analytics"]
  }'

# Response: { "data": { "id": "mind-id", ... }, "processing": { "queued": true, ... } }

# 2. Sosyal profilden bir mind oluştur (clone modu)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Influencer Clone",
    "description": "AI trained on influencer social presence",
    "mode": "clone",
    "type": "creative",
    "discipline": "Social Media Marketing",
    "personaContext": "https://twitter.com/username"
  }'

# 3. Mind ile sohbet et
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top social media trends for 2025?"
      }
    ]
  }'

Sonraki Adımlar

• Authentication hakkında bilgi edinin
• Minds endpoint'lerini keşfedin
• Bilgi yönetimi hakkında okuyun
• Chat tamamlamalarını anlayın
• Çoklu mind anketleri için Studies oluşturun
• Latency ve Performans bölümünü inceleyin
• MCP Entegrasyonu üzerinden bağlanın
• Hatalar ve Limitler bölümünü inceleyin

Plan Limitleri

API ve MCP erişimi desteklenen ücretli planlarda sunulur. Entegrasyonunuzda limitleri sabit kodlamak yerine yapılandırılmış plan_limited ve 429 yanıtlarını işleyin. Starter planı API payload'larında "premium" olarak görünür.

Aşağıdaki herkese açık varsayılanlar, ürünün kullandığı plan limiti ve özellik erişimi sözleşmesinden oluşturulur. Üründe gösterilen hesaba veya Enterprise sözleşmesine özel geçersiz kılmalar önceliklidir.

Planları Görüntüle

Yardıma mı İhtiyacınız Var?

API ile ilgili sorularınız varsa veya destek gerekiyorsa:

• Rehberimizi inceleyin
• Geri bildirim formu aracılığıyla bize ulaşın
• Topluluk tartışmalarımıza katılın

n8n iş akışları

Çalışmalar oluşturmak, araştırma planlarını önizlemek, Çalışmaları ve kaydedilmiş özetleri almak veya bir işlemi bir Yapay Zeka Ajanına sunmak için n8n için Minds topluluk düğümünü kullanın. Kendi kendine barındırılan n8n'e n8n-nodes-minds yükleyin ve bir Minds API anahtarı bağlayın. Paket npm üzerinde yayınlanmıştır; n8n doğrulaması inceleme aşamasındadır, bu nedenle n8n Cloud üzerinde henüz mevcut değildir. Araştırmayı Minds içinde ayrıca inceleyip başlatın.

Aracılar için Stripe faturalandırması

Yeni abonelikler ve yanıt kredisi yüklemeleri mevcut Stripe fiyatlarını kullanır. Satın alma önermeden önce doğrulanmış kataloğu okuyun; uygunluk, hesap sahipliği, denemeler, vergi ve indirimler Minds uygulamasıyla aynı faturalandırma hizmetlerine bağlıdır. Alıcının onayını ve abonelik için açık koşul kabulü ile cayma hakkı onayını alın.

1–128 harf, rakam, alt çizgi veya tireden oluşan sabit bir Idempotency-Key kullanın. Zaman aşımı sonrası aynı anahtarı ve gövdeyi tekrar kullanın; o anahtarla başka satın alma reddedilir. Yanıt data.url ve data.checkoutSessionId içerir. URL’yi alıcıya değiştirmeden verin. Ödeme URL’si ödeme kanıtı değildir; mevcut abonelik değişiklikleri Minds faturalandırma ayarlarında yapılır.

{
  "kind": "subscription",
  "priceId": "price_from_catalog",
  "planType": "premium",
  "billingCountry": "DE",
  "legalAcceptance": { "termsAccepted": true, "withdrawalConsent": true }
}

MPP ve x402 size ait, açık send_invoice faturalarına uygulanır; para birimi USD veya EUR, kalan tutar en az 50 küçük para birimi olmalıdır. Otomatik tahsilat Stripe fatura sayfasını kullanır. Ödeme isteği vergi ve indirim dahil gerçek bakiyeyi verir. MPP, sahibi Stripe hesabında işletme profili gerektirir. x402 ayrıca kripto uygunluğu ve yapılandırılmış kolaylaştırıcı ister; Base USDC ile USD faturalarını destekler ve mppx rota bağlama uzantısını gerektirir. Uzantısı olmayan cüzdanlar bu rotayı ödeyemez.

Minds kimliği için Authorization: Bearer tutun; MPP kimlik bilgisini Payment-Authorization, x402 bilgisini PAYMENT-SIGNATURE ile gönderin. Yerel MPP istemcileri yalnız bu rotada Authorization: Payment ve Minds bearer bilgisini taşıyan Minds-Authorization kullanabilir. Ödeme kimlik bilgilerini modelin gördüğü MCP argümanlarına koymayın. Belirsiz ödemeyi özgün kimlik bilgisiyle tekrar deneyin; yeni bilgi ikinci bir tahsilat oluşturmamalıdır. Stripe doğrulaması ve imzalı webhook hizmetin sağlanmasını belirler.

Ödeme seçeneklerini /openapi.json ile keşfedin; dinamik tutarlar 402 yanıtında belirtilir. /.well-known/acp.json, /api/acp altındaki barındırılan ödeme adaptörünü, 2026-04-17 sürümünü bildirir. Oturum oluştururken line_items içine tek Stripe fiyatı, onun currency değeri ve capabilities: {} verin; billingCountry, ekip quantity ve abonelik legalAcceptance alanlarını metadata içine koyun. Okuma, güncelleme, tamamlama ve iptal /checkout_sessions/{id} ile /complete veya /cancel üzerinden yapılır. POST istekleri idempotent anahtar gerektirir. Güncelleme ve tamamlama boş gövde kabul eder; alıcı girdisi gerektiğinde continue_url döndürün ve ancak Stripe doğruladığında tamamlandı deyin.

UCP keşfi /.well-known/ucp adresinde, 2026-08-25 sürümüyle sunulur; REST ödeme işlemleri /api/ucp altında MCP ve faturalandırma API’siyle aynı Stripe oturumlarını kullanır. Uyumlu bir platform profili yayımlayın ve aynı HTTPS kaynağında meta veri belgesi bulunan bir Minds OAuth istemcisi kullanın. Kişisel API anahtarları rastgele bir platform profili adına işlem yapamaz. Her istekte UCP-Agent: profile="https://your-platform.example/.well-known/ucp", yazma işlemlerinde ayrıca Idempotency-Key gönderin. Alıcı Stripe Checkout üzerinden ödeme yaptığı için ödeme işleyicileri boştur.

Hazır olma webhook abonelikleri

Kaynak için kullanılan aynı doğrulanmış API anahtarını veya OAuth bağlantısını kullan. GET /api/v1/events izin verilen olayları ve kesin şemalarını döndürür. POST /api/v1/events/subscribe belirlenebilir abonelik oluşturur veya yeniler; POST /api/v1/events/unsubscribe asıl olay, argümanlar ve callback URL’siyle araştırmayı iptal etmeden aboneliği durdurur. Hedef Kitle filtresi operationId; Çalışma filtresi studyId ve runId ister. MCP yöntemleri events/list, events/subscribe ve events/unsubscribe olup 2026-07-28 protokolünde server/discover ile keşfedilir.

{
  "name": "study.run.finished",
  "arguments": {
    "studyId": "163bcb31-6ca7-4fef-91bd-9b963a9dd39f",
    "runId": "663bcb31-6ca7-4fef-91bd-9b963a9dd39f"
  },
  "delivery": {
    "mode": "webhook",
    "url": "https://receiver.example/mcp-events",
    "secret": "whsec_<base64-encoded-signing-key>"
  },
  "cursor": null
}

HTTPS callback, imzalı doğrulama isteğinin challenge değerini geri vermelidir. Standard Webhooks başlıkları webhook-id, webhook-timestamp, webhook-signature ve X-MCP-Subscription-Id kullanılır. whsec_ anahtarı 24–64 bayta çözülmelidir. Özel adresler, yönlendirmeler ve URL kimlik bilgileri reddedilir. Doğrulama hatası gerekçeyle MCP -32015 döndürür ve aboneliği etkinleştirmez. HTTP 2xx alındı onayıdır; geçici hatalar sabit olay kimliği ve sınırlı üstel beklemeyle yeniden denenir; 410 ve 413 teslimatı durdurur. Sonraki işlemden önce kimliklere göre tekilleştir.

Yanıt id, refreshBefore, cursor:null ve truncated:false içerir. ttlMs daha kısa süre isteyebilir; eksik veya null, 86400000 ms ile sınırlı sonlu varsayılanı verir. Aynı kimlik, callback, olay ve argümanlar aynı ID’yi yeniler. Anahtar değişiminde kısa süre iki anahtarla imzalanır. Süre sonu veya erişimin kaldırılması teslimatı durdurur. Veri Bearer kimlik bilgisi veya araştırma yanıtları içermez.