Kıvılcım Önerileri

Spark, istek başına bir odaklanmış yapay zeka önerisi üretir. Zincirlerinizden, Bitlerinizden, kişiselleştirme hafızanızdan ve aktif oturumlarınızdan bağlamı çözer ve ardından tam bir konuşma oturumu başlatmadan kısa ve öz bir öneri oluşturur.

Hafif uygulama içi anlar için Spark'ı kullanın: "Bundan sonra ne üzerinde çalışmalıyım?", "Bu yorumu eyleme dönüştürün", "bu Chainy için biraz önerin".

Uç nokta

Method	Path	Description	Auth	Rate Limit
POST	`/ai/spark/suggestions`	Create a context-aware suggestion	JWT + Spark entitlement	30/min

POST /ai/spark/suggestions

Kimlik doğrulama: JWT Taşıyıcı jetonu gereklidir. Yetki: Active Spark yetkisi gereklidir. Bitter ve üzeri sürümlerde mevcuttur (ücretsiz Explorer planına dahil değildir). Hız sınırı: Dakikada 30 istek. Idempotency: Yeniden denemeleri tekilleştirmek için bir "idempotency-key" başlığı iletin; aynı anahtarlar, LLM'yi yeniden çağırmadan önbelleğe alınan sonucu döndürür.

Rica etmek

Başlıkları Talep Et

Header	Required	Description
`Authorization`	Yes	`Bearer <token>`
`Content-Type`	Yes	`application/json`
`idempotency-key`	No	Unique key to deduplicate the request

Talep Gövdesi

Tüm alanlar isteğe bağlıdır. Hiçbir alan sağlanmazsa sunucu "auto_suggest" modunu kullanır.

Field	Type	Constraints	Description
`mode`	string	`auto_suggest`, `prompt_suggest`, `next_bit`, `comment_result`	Explicit mode. Omit to let the server resolve automatically.
`prompt`	string	max 4000 chars	Primary instruction or question.
`comment`	string	max 4000 chars	Raw comment to transform into a suggestion.
`chainyIds`	string[]	max 10, each a valid UUID	Ground the suggestion in specific Chainies.
`bitIds`	string[]	max 25, each a valid UUID	Ground the suggestion in specific Bits.
`contextOptions.useMemory`	boolean	—	Set `false` to suppress memory context for this request.
`contextOptions.useLatestSessions`	boolean	—	Set `false` to suppress recent-sessions context for this request.

Otomatik mod çözünürlüğü ("mod" belirtilmediğinde):

"yorum" sağlandı → "yorum_sonucu"
"istem" sağlandı → "prompt_suggest"
"zincir kimlikleri" sağlandı → "sonraki_bit"
Hiçbir şey → auto_suggest

Cevap

Yanıt Örneği

json

{
  "data": {
    "suggestionId": "cm9spark01",
    "mode": "next_bit",
    "title": "Add a pronunciation practice session",
    "content": "Your Spanish Chainy has strong vocabulary coverage but no pronunciation Bits. Adding a 10-minute daily audio session would round out the practice cycle.",
    "structuredResult": {
      "type": "next_bit",
      "payload": {
        "suggestedTitle": "Pronunciation: 10-min daily audio",
        "suggestedPriority": "high"
      }
    },
    "contextUsed": ["chainies", "bits", "memory"],
    "blockedContext": [
      {
        "category": "sessions",
        "reason": "sessions_disabled_by_preference"
      }
    ],
    "chainyIdsUsed": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "bitIdsUsed": [
      "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "c3d4e5f6-a7b8-9012-cdef-123456789012"
    ],
    "personaUsed": "coach",
    "provider": "google",
    "model": "gemini-2.5-flash",
    "createdAt": "2026-05-22T09:30:00.000Z"
  }
}

Yanıt Alanları

Field	Type	Description
`suggestionId`	string	Persisted suggestion ID
`mode`	string	Resolved mode used: `auto_suggest`, `prompt_suggest`, `next_bit`, `comment_result`
`title`	string	Short suggestion headline
`content`	string	Full suggestion text
`structuredResult`	object \| null	Optional structured output
`contextUsed`	string[]	Context categories that fed the suggestion
`blockedContext`	object[]	Context categories that were suppressed and why
`chainyIdsUsed`	string[]	Chainy IDs that grounded the suggestion
`bitIdsUsed`	string[]	Bit IDs that grounded the suggestion
`personaUsed`	string \| null	AI persona key if a persona was applied
`provider`	string	AI provider used (e.g. `google`, `anthropic`)
`model`	string	Model identifier
`createdAt`	string	ISO 8601 timestamp

'structuredResult' nesnesi

LLM, anlatı metnine ek olarak yapılandırılmış verileri döndürdüğünde mevcut olur.

Field	Type	Description
`type`	string	`next_bit`, `idea`, `transformation`, or `generic`
`payload`	object	Type-specific fields (e.g. `suggestedTitle`, `suggestedPriority`)

'contextUsed' değerleri

Value	Meaning
`prompt`	User's `prompt` field was used
`comment`	User's `comment` field was used
`chainies`	Chainy data was retrieved
`bits`	Bit data was retrieved
`memory`	Personalization memory was used
`sessions`	Recent AI sessions were used
`preferences`	AI persona or language preference was applied

'blockedContext' nesnesi

Field	Type	Description
`category`	string	The `contextUsed` category that was blocked
`reason`	string	Why it was blocked

Reason	Cause
`memory_disabled_by_preference`	Memory disabled in your AI preferences
`memory_disabled_by_client`	Request sent `contextOptions.useMemory: false`
`sessions_disabled_by_preference`	Session context disabled in your AI preferences
`sessions_disabled_by_client`	Request sent `contextOptions.useLatestSessions: false`
`empty_input`	No prompt, comment, or Chainy IDs were provided
`no_bits_available`	The requested Chainies exist but contain no Bits

Hata Yanıtları

Status	Code	When
400	`VALIDATION_FAILED`	Mode/input mismatch (e.g. `next_bit` without `chainyIds`)
403	`FORBIDDEN`	`chainyIds` or `bitIds` do not belong to your account
429	`RATE_LIMIT_EXCEEDED`	More than 30 requests per minute
502	`BAD_GATEWAY`	AI provider returned an empty or failed response
503	`SERVICE_UNAVAILABLE`	No AI provider available

Kod Örnekleri

Aşağıdaki "sonraki bit" örneklerinde Chainie'lerinizden birinin "id"sini "$CHAINY_ID" olarak kullanın.

bash

curl -X POST "$BASE_URL/ai/spark/suggestions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

bash

curl -X POST "$BASE_URL/ai/spark/suggestions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: req_abc123" \
  -d '{
    "mode": "prompt_suggest",
    "prompt": "What is the highest priority thing I should tackle today?"
  }'

bash

curl -X POST "$BASE_URL/ai/spark/suggestions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "next_bit",
    "chainyIds": ["'"$CHAINY_ID"'"]
  }'

bash

curl -X POST "$BASE_URL/ai/spark/suggestions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "comment_result",
    "comment": "I keep losing focus after lunch and end up skipping my language practice."
  }'

javascript

// Auto suggest
const res = await fetch(`${BASE_URL}/ai/spark/suggestions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const { data } = await res.json();

// Prompt mode with idempotency
const res = await fetch(`${BASE_URL}/ai/spark/suggestions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
    "idempotency-key": "req_abc123",
  },
  body: JSON.stringify({
    mode: "prompt_suggest",
    prompt: "What is the highest priority thing I should tackle today?",
  }),
});
const { data } = await res.json();

// Next bit for a Chainy
const chainyId = process.env.CHAINY_ID; // id of the Chainy to ground the suggestion in

const res = await fetch(`${BASE_URL}/ai/spark/suggestions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "next_bit",
    chainyIds: [chainyId],
  }),
});
const { data } = await res.json();

python

import os
import requests

BASE_URL = "https://api.chainabit.com/api/v1"
headers = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

# Auto suggest
res = requests.post(f"{BASE_URL}/ai/spark/suggestions", headers=headers, json={})
data = res.json()["data"]

# Prompt mode
res = requests.post(
    f"{BASE_URL}/ai/spark/suggestions",
    headers={**headers, "idempotency-key": "req_abc123"},
    json={
        "mode": "prompt_suggest",
        "prompt": "What is the highest priority thing I should tackle today?",
    },
)
data = res.json()["data"]

# Next bit
chainy_id = os.environ["CHAINY_ID"]  # id of the Chainy to ground the suggestion in

res = requests.post(
    f"{BASE_URL}/ai/spark/suggestions",
    headers=headers,
    json={
        "mode": "next_bit",
        "chainyIds": [chainy_id],
    },
)
data = res.json()["data"]

Plan kullanılabilirliği

Plan	Spark access	Monthly suggestion limit
Explorer	No	—
Bitter	Yes	150
Chainer	Yes	500
Architect	Yes	Unlimited

Spark erişimi olmayan bir planda bu uç noktayı çağırmak "403 YASAK" sonucunu döndürür.

Modlar

"otomatik_öneri"

Hiçbir giriş gerekli değildir. Spark, son Bit'lerinizi, Zincirlerinizi, hafızanızı ve oturumlarınızı okur ve istemsiz bir öneri oluşturur; "beni şaşırt" veya "sırada ne var?" için kullanışlıdır. anlar.

"prompt_suggest"

'İstemi' gerektirir. Açık sorunuza veya mevcut bağlamınızla birleştirilmiş talimatınıza dayanan bir öneri oluşturur.

"sonraki_bit"

En az bir "chainyId" gerektirir. Spark, Chainy'nin mevcut Bit'lerini analiz eder ve oluşturulacak somut bir sonraki Bit'i veya gerçekleştirilecek eylemi önerir.

"yorum_sonucu"

'Yorum' gerektirir. Ham kullanıcı yorumunu (bir not, düşünce veya gözlem) eyleme dönüştürülebilir bir öneriye dönüştürür.

Bağlam kontrolleri

Belirli kimliklerle topraklama

Öneriyi belirli içeriğe sabitlemek için "chainyIds" ve/veya "bitIds" sağlayın. Kimlikler olmadan Spark, en yeni Chainies ve Bit'lerinizden otomatik olarak çeker.

İstek başına bağlamın bastırılması

Tek bir istek için hesap düzeyindeki tercihlerinizi geçersiz kılmak için "contextOptions"ı kullanın:

json

{
  "contextOptions": {
    "useMemory": false,
    "useLatestSessions": false
  }
}

Hesap düzeyindeki tercihler

Bellek ve oturum bağlamı, AI tercihlerinizi takip eder ("ai_memory_enabled", "use_latest_sessions"). Bunları Tercihler API'si aracılığıyla yönetin.

iktidarsızlık

Yeniden denemeleri güvenli hale getirmek için bir "idempotency-key" başlığı iletin. Aynı anahtarla bir öneri zaten oluşturulmuşsa kalıcı sonuç, LLM'yi tekrar çağırmadan hemen döndürülür.

bash

curl -X POST "$BASE_URL/ai/spark/suggestions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: client-generated-unique-id" \
  -d '{ "prompt": "What should I focus on today?" }'

Anahtarlar hesabınızın kapsamına alınmıştır. Anahtar olarak bir UUID veya istek girişlerinin karmasını kullanın.

Kıvılcım Önerileri ​

Uç nokta ​

POST /ai/spark/suggestions ​

Rica etmek ​

Başlıkları Talep Et ​

Talep Gövdesi ​

Cevap ​

Yanıt Örneği ​

Yanıt Alanları ​

'structuredResult' nesnesi ​

'contextUsed' değerleri ​

'blockedContext' nesnesi ​

Hata Yanıtları ​

Kod Örnekleri ​

Plan kullanılabilirliği ​

Modlar ​

"otomatik_öneri" ​

"prompt_suggest" ​

"sonraki_bit" ​

"yorum_sonucu" ​

Bağlam kontrolleri ​

Belirli kimliklerle topraklama ​

İstek başına bağlamın bastırılması ​

Hesap düzeyindeki tercihler ​

iktidarsızlık ​

Kıvılcım Önerileri

Uç nokta

POST /ai/spark/suggestions

Rica etmek

Başlıkları Talep Et

Talep Gövdesi

Cevap

Yanıt Örneği

Yanıt Alanları

'structuredResult' nesnesi

'contextUsed' değerleri

'blockedContext' nesnesi

Hata Yanıtları

Kod Örnekleri

Plan kullanılabilirliği

Modlar

"otomatik_öneri"

"prompt_suggest"

"sonraki_bit"

"yorum_sonucu"

Bağlam kontrolleri

Belirli kimliklerle topraklama

İstek başına bağlamın bastırılması

Hesap düzeyindeki tercihler

iktidarsızlık