BölümlerTahta referansı

Başlangıç

Buradan başla

Referans

Kur

İş akışları

İş akışları

Destek

Referans

Tahta referansı

Dört uç nokta — link ekle, grupla, oku, sor — artı iş yoklama ve deste basma çağrısı. Her biri istek, cevap, hata ve bir curl ile.

Bu sayfa bir : baştan sona okunmaz, aranır.

Cevap zarfı

uç noktaları hep aynı zarfla cevap verir: success, yanında data ya da error.

İstisna GET /api/jobs/{id}: o düz JSON döner, zarfsız.

Başarı ve hata

json

{ "success": true,  "data": { } }
{ "success": false, "error": { "code": "BAD_REQUEST", "message": "…" } }

Ortak hatalar

Durum	Kod	Anlamı
401	UNAUTHORIZED	Anahtar yok, bozuk ya da iptal edilmiş. Dur, Ayarlar’dan kontrol et.
404	NOT_FOUND	Tahta senin değil ya da yok. İkisi ayırt edilmez — kimlik doğru mu diye bak.
400	BAD_REQUEST	error.message neyin yanlış olduğunu Türkçe söyler. Aynı gövdeyi ikinci kez gönderme.
429	RATE_LIMITED	Retry-After kadar bekle, bir kez daha dene.

Aşağıdaki her çağrıda {id} tahtanın UUID’sidir — kanvasta /board/<uuid> adresinde duran değer, ya da POST /api/boards cevabındaki data.id.

1 · POST /api/boards/{id}/nodes — linkleri tahtaya koy

Linkleri tahtaya birer olarak koyar ve her biri için transkript işini kuyruğa alır. Hız kademesi: heavy (10 istek/dakika). harcamaz.

Gövde tek alan taşır: urls, 1–20 link. Yalnız Instagram (reel/post/tv), TikTok (video, vm./vt. kısa linkleri dahil) ve YouTube (watch/shorts) kabul edilir.

Doğrulama hep-ya-hiç: bir link reddedilirse hiçbiri eklenmez ve tahtaya hiçbir şey yazılmaz. Hata mesajı hangi linkin reddedildiğini adıyla söyler.

İstek

bash

curl -sS -X POST "$BASE/api/boards/$BOARD/nodes" \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"urls":["https://www.instagram.com/reel/DA1b2C3d4E/","https://www.youtube.com/watch?v=xyz"]}'

Cevap

json

{ "success": true, "data": {
  "boardId": "8f1c…",
  "nodes": [
    { "nodeId": "instagram-content-1757…-4f2a", "url": "https://…", "platform": "instagram",
      "transcript": "queued", "jobId": "…" },
    { "nodeId": "youtube-video-1757…-e5f6", "url": "https://…", "platform": "youtube",
      "transcript": "skipped", "transcriptNote": "…" }
  ] } }

Alan	Değerler	Ne demek
platform	instagram · tiktok · youtube	Başka bir şey 400 döner
transcript	queued · skipped	queued: iş kuyruğa girdi. skipped: bu link için çıkarılmayacak
transcriptNote	metin	skipped ise sebebi burada
jobId	kimlik	GET /api/jobs/{id} ile tek tek izlemek istersen

Kart her hâlükârda tahtaya düşer — skipped transkriptin çıkmayacağını söyler, kartın eklenmediğini değil.
Tahtanın parça tavanı 500; parti bu tavanı aşacaksa çağrı 400 döner ve hiçbiri eklenmez.

2 · POST /api/boards/{id}/groups — kartları çerçevele

Kanvastaki ⌘G’nin aynısı: bir grup açar, verdiğin kartları içine alır ve konumlarını çerçeveye göre yeniden yazar. Hız kademesi: standard (60 istek/dakika). Kredi harcamaz.

Gövde iki alan taşır: nodeIds (çerçeveye girecek kartlar) ve title (çerçevenin adı).

İstek

bash

curl -sS -X POST "$BASE/api/boards/$BOARD/groups" \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"nodeIds":["instagram-content-…","tiktok-video-…"],"title":"Rakip Reels"}'

Cevap

json

{ "success": true, "data": {
  "groupId": "group-1757…", "title": "Rakip Reels",
  "memberIds": ["instagram-content-…","tiktok-video-…"],
  "severedEdgeIds": [] } }

Gruplama bağlantı koparır

Çerçeveye giren bir kartın bir sohbet kartına giden bağlantısı varsa o bağlantı kesilir — bundan sonra sohbeti besleyen şey çerçevenin kendisidir. Kopan bağlantılar severedEdgeIds içinde döner.
Önce grupla, sonra sor: tersi sırada kurduğun bağlantıları kendi elinle koparırsın.

Zaten bir grubun içinde olan kart, sohbet kartı, başka bir grup ve metin notu gruplanamaz — kanvastaki hareket de bunları reddeder. Bu durumda 400 döner ve mesaj hangi parça olduğunu söyler.

Boş nodeIds ya da boş title de 400 döner.

3 · GET /api/boards/{id}/summary — tahtayı geri oku

Tahtanın makine okunur özeti: kartlar, gruplar, sohbet kartları ve her kartın transkript durumu. Gövde yok. Hız kademesi: standard (60 istek/dakika). Kredi harcamaz.

İstek

bash

curl -sS "$BASE/api/boards/$BOARD/summary" -H "$AUTH"

Cevap

json

{ "success": true, "data": {
  "id": "8f1c…", "title": "Rakip analizi",
  "nodes": [
    { "id": "instagram-content-…", "type": "instagram-content", "title": "…",
      "url": "https://…", "transcript": "ready", "parentId": "group-…" }
  ],
  "groups": [ { "id": "group-…", "title": "Rakip Reels", "memberIds": ["…"] } ],
  "chatNodeIds": ["ai-…"] } }

transcript	Ne demek
ready	Metin hazır
pending	İş kuyrukta ya da çalışıyor — beklemeye devam
failed	Bu kart için çıkmadı. Tekrar tekrar deneme; hangi link olduğunu kullanıcıya söyle
none	Bu kartın transkripti olmaz (not, grup, sohbet) ya da hiç iş açılmamış

Yoklama temposu

İlk kontrol ~10 saniye sonra, sonra 15 saniye arayla, toplam 10 dakika.
Süre dolduğunda hâlâ pending olanları rapor et ve devam et — tavansız bir yoklama döngüsü akışı sonsuza kadar orada tutar.

4 · POST /api/boards/{id}/ask — tahtaya sor

Tahtadaki kaynaklara bakan bir sohbet turu çalıştırır. Hız kademesi: heavy (10 istek/dakika). Kredi harcar.

sourceNodeIds ve/veya groupId sohbetin neyi göreceğini söyler; ikisi de gerçek bağlantılarla sohbete bağlanır. chatNodeId verirsen var olan sohbet (ve onun geçmişi) sürer; vermezsen kaynakların sağında yeni bir sohbet kartı açılır.

Cevap dakikalar sürebilir. İstemci zaman aşımını buna göre ayarla.

İstek

bash

curl -sS -X POST "$BASE/api/boards/$BOARD/ask" \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"question":"Bu üç reel’in ortak kancası ne?","groupId":"group-1757…"}'

Cevap

json

{ "success": true, "data": {
  "chatNodeId": "ai-…", "text": "…",
  "creditsNotice": null, "deckProposal": null, "actions": [] } }

Alan	Ne demek
chatNodeId	Aynı sohbeti sürdürmek için bir sonraki çağrıda geri gönder
text	Modelin cevabı
creditsNotice	exhausted geldiyse bakiye bitmiş — dur, kullanıcıya söyle
deckProposal	Deste istendiğinde dolar. Aşağıdaki diziye bak
actions	Turun ürettiği ek işlem kalemleri

Yardımcı · GET /api/jobs/{id} — işi yokla

Transkript ve deste basımı arka plan işidir. Bu uç nokta düz JSON döner, zarfsız.

status: pending · processing · completed · failed. terminal: true ise iş bir daha denenmeyecek ve terminalReason sebebi makine okunur biçimde verir — cümleden tahmin etme.

İstek ve cevap

bash

curl -sS "$BASE/api/jobs/$JOB_ID" -H "$AUTH"

{ "id": "…", "type": "transcript", "status": "completed", "output": { },
  "error": null, "terminal": false, "terminalReason": null, "progress": 100 }

Yardımcı · deste basmak

Ayrı bir “deste üret” uç noktası yok. aynı sohbetten istenir ve dört adımı vardır.

Üçüncüsü atlanırsa deste basılmaz.

İste

Aynı sohbete deste isteğini yaz: POST /api/boards/{id}/ask.

Cevapta deckProposal.act "ask" gelir ve credits tahmini maliyeti söyler.

bash

curl -sS -X POST "$BASE/api/boards/$BOARD/ask" \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"question":"2. fikri deste yap","chatNodeId":"ai-…"}'

2
Onayla
Onay serbest metindir: aynı chatNodeId ile “evet” gönder.
Bu turda deckProposal.act "fire" olur ve plan dolu gelir.
json
{ "type": "deliverable", "lane": "deck", "act": "fire", "credits": 148, "plan": { } }
3
Bas
Basma çağrısını sen yaparsın: POST /api/visual/generate.
"fire" tek başına piksel üretmez — kanvasta bu adımı istemci kodu atıyor. Planı olduğu gibi gönder.
bash
curl -sS -X POST "$BASE/api/visual/generate" \ -H "$AUTH" -H 'Content-Type: application/json' \ -d "$PLAN_JSON"
4
Bekle ve topla
Cevap ya doğrudan sonucu ya da { "jobId": "…", "mode": "job", "total": 6 } döner. jobId geldiyse iş bitene kadar yokla.
Sayfalar ayrıca tahtaya bir carousel kartı olarak düşer, yani GET /api/boards/{id} ile de adreslerini alabilirsin.
bash
curl -sS "$BASE/api/boards/$BOARD" -H "$AUTH" curl -sSL "<sayfa-gorsel-adresi>" -o sayfa-01.png

Deste basımı kredi harcar ve geri alınmaz. Bir ajan ya da otomasyon adına bu çağrıyı yapıyorsan tahmini maliyeti önce kullanıcıya söyle.
Ayrıca: üründe PDF çıktısı yok, sayfalar PNG olarak iner.

Sonra

Tuzaklar

Bu dört uç noktanın sessizce beklediğinden farklı davrandığı yerler.

İş akışları

Bu çağrıların baştan sona birleştiği beş gerçek iş.

Ortak hatalar

Durum	Kod	Anlamı
401	UNAUTHORIZED	Anahtar yok, bozuk ya da iptal edilmiş. Dur, Ayarlar’dan kontrol et.
404	NOT_FOUND	Tahta senin değil ya da yok. İkisi ayırt edilmez — kimlik doğru mu diye bak.
400	BAD_REQUEST	error.message neyin yanlış olduğunu Türkçe söyler. Aynı gövdeyi ikinci kez gönderme.
429	RATE_LIMITED	Retry-After kadar bekle, bir kez daha dene.

1 · POST /api/boards/{id}/nodes — linkleri tahtaya koy

Linkleri tahtaya birer olarak koyar ve her biri için transkript işini kuyruğa alır. Hız kademesi: heavy (10 istek/dakika). harcamaz.

Gövde tek alan taşır: urls, 1–20 link. Yalnız Instagram (reel/post/tv), TikTok (video, vm./vt. kısa linkleri dahil) ve YouTube (watch/shorts) kabul edilir.

Doğrulama hep-ya-hiç: bir link reddedilirse hiçbiri eklenmez ve tahtaya hiçbir şey yazılmaz. Hata mesajı hangi linkin reddedildiğini adıyla söyler.

curl -sS -X POST "$BASE/api/boards/$BOARD/nodes" \ -H "$AUTH" -H 'Content-Type: application/json' \ -d '{"urls":["https://www.instagram.com/reel/DA1b2C3d4E/","https://www.youtube.com/watch?v=xyz"]}'

{ "success": true, "data": { "boardId": "8f1c…", "nodes": [ { "nodeId": "instagram-content-1757…-4f2a", "url": "https://…", "platform": "instagram", "transcript": "queued", "jobId": "…" }, { "nodeId": "youtube-video-1757…-e5f6", "url": "https://…", "platform": "youtube", "transcript": "skipped", "transcriptNote": "…" } ] } }

Alan

Değerler

Ne demek

platform

instagram · tiktok · youtube

Başka bir şey 400 döner

transcript

queued · skipped

queued: iş kuyruğa girdi. skipped: bu link için çıkarılmayacak

transcriptNote

metin

skipped ise sebebi burada

jobId

kimlik

GET /api/jobs/{id} ile tek tek izlemek istersen

Gruplama bağlantı koparır

Çerçeveye giren bir kartın bir sohbet kartına giden bağlantısı varsa o bağlantı kesilir — bundan sonra sohbeti besleyen şey çerçevenin kendisidir. Kopan bağlantılar severedEdgeIds içinde döner.

Önce grupla, sonra sor: tersi sırada kurduğun bağlantıları kendi elinle koparırsın.

{ "success": true, "data": { "id": "8f1c…", "title": "Rakip analizi", "nodes": [ { "id": "instagram-content-…", "type": "instagram-content", "title": "…", "url": "https://…", "transcript": "ready", "parentId": "group-…" } ], "groups": [ { "id": "group-…", "title": "Rakip Reels", "memberIds": ["…"] } ], "chatNodeIds": ["ai-…"] } }

transcript

Ne demek

ready

Metin hazır

pending

İş kuyrukta ya da çalışıyor — beklemeye devam

failed

Bu kart için çıkmadı. Tekrar tekrar deneme; hangi link olduğunu kullanıcıya söyle

none

Bu kartın transkripti olmaz (not, grup, sohbet) ya da hiç iş açılmamış

4 · POST /api/boards/{id}/ask — tahtaya sor

Tahtadaki kaynaklara bakan bir sohbet turu çalıştırır. Hız kademesi: heavy (10 istek/dakika). Kredi harcar.

Cevap dakikalar sürebilir. İstemci zaman aşımını buna göre ayarla.

Alan

Ne demek

chatNodeId

Aynı sohbeti sürdürmek için bir sonraki çağrıda geri gönder

text

Modelin cevabı

creditsNotice

exhausted geldiyse bakiye bitmiş — dur, kullanıcıya söyle

deckProposal

Deste istendiğinde dolar. Aşağıdaki diziye bak

actions

Turun ürettiği ek işlem kalemleri