BölümlerTahta referansı

Başlangıç

Buradan başlaADIM 1

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.

Ajan tahtayı kendi açar

Anahtar `Authorization: Bearer` başlığıyla gider. Dönen kimlik bundan sonraki her çağrının adresi.

Adım 1 / 7

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

Bölüm 01

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": "…" } }

Bölüm 02

Ortak hatalar

Durum	Kod	Anlamı
401	UNAUTHORIZED	Anahtar yok, bozuk ya da iptal edilmiş. Dur, «API ve Claude» sayfasından 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.

Bölüm 03

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 (reels/post/tv), TikTok (video, vm./vt. kısa linkleri dahil — kısa linkin yönlendirmesi önce okunur; foto gönderisi — /photo/ — slaytlarıyla tek bir carousel kartı olur ve transkripti yoktur) 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.

Bölüm 04

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": [], "wiredChatIds": [] } }

Gruplama bağlantıyı çerçeveye taşır

Çerçeveye giren bir kartın bir sohbet kartına giden bağlantısı varsa o bağlantı kesilir ve yerine çerçevenin kendisi o sohbete bağlanır — sohbet kartı okumaya çerçeve üzerinden devam eder. Kesilenler severedEdgeIds, çerçevenin bağlandığı sohbetler wiredChatIds içinde döner.
Önce grupla, sonra sor: tersi sırada kurduğun bağlantılar çerçeveye taşınır, kart tek başına okunmaz.

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.

Bölüm 06

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.

Bölüm 08

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 üç reels’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

Bölüm 09

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 }

Bölüm 10

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.

Bölüm 11

Sonra

Tuzaklar

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

Aç

İş akışları

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

Aç