OLAB Assist Giriş yap
Geliştiriciler

API, webhook'lar ve MCP

OLAB Assist izleme verilerinizi ajansınızın zaten kullandığı araçlara taşıyın. Sürüm 1, salt okunur, Agency planına dahil.

Genel bakış

OLAB Assist, ajansların izleme verilerini panel dışında kullanmaları için beş yol sunar. Hepsi aynı veriyi okur ve aynı sürümlü sözleşmeyi izler; birinde gördüğünüz, diğerlerinde de aynıdır.

  • REST API: siteleri, puanları, bulguları, yapay zekâ yanıtlarını, puan geçmişini, trendleri ve değişiklikleri bir CRM'e, veri ambarına ya da raporlama aracına çekin.
  • Webhook'lar: bir tarama bittiğinde ya da yeni yapay zekâ yanıtları geldiğinde anında imzalı bir JSON olayı alın; hiçbir şeyin sürekli sorgulama yapmasına gerek kalmaz.
  • MCP sunucusu: Claude, ChatGPT, Cursor ya da herhangi bir Model Context Protocol istemcisini bağlayın ve sitelerinizi günlük dille sorun.
  • Looker Studio: OLAB Assist bağlayıcısıyla puanlar, sorunlar ve yapay zekâ görünürlüğü üzerine müşteri raporları hazırlayın.
  • Notion: sitelerinizi, sorunlarınızı ve yapay zekâ yanıtlarınızı içeren bir Notion sayfasını kod yazmadan güncel tutun.

Adım adım anlatım mı istersiniz? Entegrasyon rehberleri her birini adım adım kurar: Notion, Looker Studio, Slack, Discord, Zapier ve Make, REST API ve MCP.

API, webhook'lar, MCP, Looker Studio ve Notion Agency planına dahildir. Anahtarları ve webhook'ları hesap sahibi Entegrasyonlar sayfasından yönetir.

Kimlik doğrulama

Entegrasyonlar sayfasında bir anahtar oluşturun. Anahtarın tamamı yalnızca bir kez gösterilir; biz yalnızca özetini (hash) saklarız. Her istekte gönderin:

curl https://api.olabassist.com/api/v1/sites \
  -H "Authorization: Bearer olab_YOUR_KEY"

Anahtarlar salt okunurdur ve çalışma alanınızla sınırlıdır: bir anahtar yalnızca onu oluşturan hesaptaki siteleri görür. Entegrasyonlar sayfasında bir anahtarı iptal ettiğinizde hemen çalışmayı bırakır. Hesap Agency planından çıkarsa, plana dönene kadar anahtarları çalışmaz.

İstekler ve sınırlar

  • Temel adres: https://api.olabassist.com/api/v1. GET /api/v1 uç noktaların listesini döndürür.
  • Tüm uç noktalar GET kullanır ve JSON döndürür: { "data": …, "api_version": "v1" }. Sayfalanan listeler ayrıca next_cursor döndürür.
  • Zaman damgaları UTC'de ISO 8601 biçimindedir. Puanlar 0 ile 100 arasındadır.
  • Hız sınırı: anahtar başına dakikada 120 istek. Bu sınırın üzerinde retryAfterSeconds ile birlikte 429 alırsınız.
  • Yolda {site} geçen her yerde site kimliğini ya da alan adını kullanabilirsiniz, ör. /sites/example.com.

Uç noktalar

GET /account

Planınız, sınırlarınız ve kullanımınız.

GET /sites

İzlenen tüm siteler, son puanları ve açık sorunlarıyla.

{
  "data": [{
    "id": "k3Jd9x2Lq",
    "domain": "example.com",
    "brand_name": "Example",
    "status": "active",
    "created_at": "2026-09-01T10:00:00.000Z",
    "next_scan_at": "2026-10-12T10:00:00.000Z",
    "last_checked_at": "2026-10-05T10:00:00.000Z",
    "score": { "overall": 92, "seo": 95, "geo": 88, "aeo": 90, "aio": 94 },
    "issues": { "critical": 0, "warnings": 2 },
    "regressions_last_7_days": 0,
    "report_url": "https://olabassist.com/r/…",
    "app_url": "https://olabassist.com/app/?site=k3Jd9x2Lq"
  }],
  "api_version": "v1"
}

GET /sites/{site}

Yukarıdakilerin hepsi, ayrıca ai_visibility (kontrol edilen yanıtlar, kaçının sizi andığı, kaçının sitenizi kaynak gösterdiği, takip edilen markalar arasındaki sıranız, ton), takip edilen her marka için share_of_voice, asistanların en çok gösterdiği kaynaklar top_sources, competitors, questions ve engines.

GET /sites/{site}/findings?status=fail,warn

Son taramadaki kontroller, kanıtları ve çözümleriyle (summary, where ve varsa yapıştırmaya hazır code). status verilmezse tüm kontroller döner.

GET /sites/{site}/answers

Saklanan yapay zekâ yanıtları, en yeniden eskiye. Her yanıtta soru, asistan (engine), markanızın anılıp anılmadığı (named) ve kaynak gösterilip gösterilmediği (cited), sırası (rank), tonu (sentiment), yanıttaki takip edilen tüm markalar ve gösterilen kaynaklar bulunur.

Parametreler: engine, question_id, since (ISO tarih), limit (1–500, varsayılan 100), cursor, yanıtın tam metni için include_answer=true. next_cursor boş değilse, sonraki sayfayı almak için onu cursor olarak gönderin.

GET /sites/{site}/history

Her taramadan sonraki puan, en eskiden yeniye (limit en fazla 200).

GET /sites/{site}/trends

Grafikler ve raporlar için zaman serileri; day (gün), week (pazartesi başlangıçlı hafta) ya da month (ay, UTC) olarak gruplanır. Parametreler: from ve to (YYYY-MM-DD, dahil; varsayılan son 90 gün, en fazla iki yıl), bucket (varsayılan aralığa göre seçilir). Yanıtta periods (dönem başlangıç tarihleri), series (her ölçüm için periods ile hizalı bir dizi; veri olmayan yerde null), her seriyi açıklayan bir catalog (unit: score, pct, count ya da rank; better: up ya da down) ve aralıktaki changes bulunur.

Seriler: score.overall, score.seo, score.geo, score.aeo, score.aio (her dönemin son taraması), issues.fail, issues.warn, ai.visibility, ai.cited, ai.positive, ai.negative (yüzdeler), ai.position (anıldığınızda ortalama sıra), ai.answers, engine.<asistan> ve intent.<niyet> (görünürlük %) ve brand.<rakip alan adı> (o rakibin anıldığı yanıtların payı).

GET /sites/{site}/changes

Taramalar arasında neyin değiştiği: new (yeni sorunlar), worse (kötüleşenler) ve better (düzelenler). Parametreler: since, limit.

Hatalar

Hatalar HTTP durum kodları ve bir JSON gövdesiyle döner: { "error": "NOT_FOUND", "message": "…" }.

  • 401 anahtar yok, geçersiz ya da iptal edilmiş
  • 403 API_NOT_IN_PLAN çalışma alanı Agency planında değil
  • 404 site bu çalışma alanında değil
  • 405 API salt okunurdur
  • 429 hız sınırı aşıldı

Webhook'lar

Entegrasyonlar sayfasında bir https adresi ekleyin ve almak istediğiniz olayları seçin. Her olay JSON gövdeli bir POST olarak gönderilir:

{
  "id": "evt_4Hh2…",
  "type": "scan.completed",
  "api_version": "v1",
  "created_at": "2026-10-05T10:00:00.000Z",
  "data": {
    "site": { "id": "k3Jd9x2Lq", "domain": "example.com", "app_url": "…" },
    "audit_id": "…",
    "checked_at": "2026-10-05T10:00:00.000Z",
    "score": { "overall": 92, "seo": 95, "geo": 88, "aeo": 90, "aio": 94 },
    "issues": { "critical": 0, "warnings": 2 },
    "changes": [{ "finding_id": "seo-title", "kind": "worse", "from": "pass", "to": "warn", "title": "Title tag is too long", "at": "…" }],
    "report_url": "https://olabassist.com/r/…"
  }
}

Olaylar

  • score.dropped: genel puan en az webhook'un eşiği kadar düştü (varsayılan %10, webhook başına %1–90). Önceki ve yeni puan, puan ve yüzde olarak düşüş ve her kategorinin değişimi.
  • visibility.lost: bir yapay zekâ asistanı takip edilen bir soruya verdiği son yanıtta markanızı anıyordu, artık anmıyor. Asistanı, soruyu ve yerine önerdiği rakipleri (named_instead) içerir.
  • visibility.gained: bir asistan daha önce anmadığı markanızı artık anıyor; sırasıyla birlikte.
  • scan.completed: bir tarama bitti (haftalık, elle ya da yeniden kontrol). Puanlar, sorun sayıları ve değişenler.
  • answers.updated: takip edilen bir soru için yeni yapay zekâ yanıtları; asistan başına bir kayıt, /answers ile aynı biçimde.
  • site.created ve site.deleted.

Bir ping olayı almak için Entegrasyonlar sayfasındaki Test gönder düğmesini kullanın.

Slack, Discord, Asana, ClickUp

Her webhook'un bir mesaj biçimi vardır. Bir Slack ya da Discord gelen webhook (incoming webhook) adresi yapıştırdığınızda OLAB Assist, hesabın dilinde, bağlantılı ve okunaklı tek satırlık bir uyarı gönderir (Slack ve Discord adresleri otomatik tanınır). Asana, ClickUp, Trello, HubSpot ve diğerleri için JSON biçimini Zapier, Make ya da n8n ile kullanın: "Catch webhook" tetikleyicisinin ardından gelen bir "Create task" adımı, her score.dropped ya da visibility.lost olayını bir göreve dönüştürür. Her gönderim OLAB-Signature taşır; Slack ve Discord bunu yok sayar.

İmzayı doğrulama

Her istekte OLAB-Event, OLAB-Delivery ve OLAB-Signature: t=<unix saniye>,v1=<hex> başlıkları bulunur. İmza, webhook'unuzun imzalama anahtarıyla t + "." + ham gövde üzerinden alınmış bir HMAC-SHA256'dır. Sabit sürede karşılaştırın ve eski zaman damgalarını reddedin:

// Node.js
import crypto from 'node:crypto';
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
# Python
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Yeniden denemeler

10 saniye içinde herhangi bir 2xx durumuyla yanıt verin. Diğer her durum yaklaşık 5 dakika, 30 dakika, 2 saat, 6 saat ve 24 saat sonra yeniden denenir. Art arda 25 başarısız gönderimden sonra webhook duraklatılır; Entegrasyonlar sayfasından yeniden açabilirsiniz. Daha önce işlediğiniz bir olayı yok saymak için id alanını kullanın.

MCP sunucusu

MCP uç noktası https://api.olabassist.com/mcp adresidir (Streamable HTTP). API uç noktalarını salt okunur araçlar olarak sunar: list_sites, get_site, get_findings, get_ai_answers, get_score_history, get_trends, get_changes.

Başlık (header) kabul eden istemciler (Claude Code, Cursor ve diğerleri):

{
  "mcpServers": {
    "olab-assist": {
      "url": "https://api.olabassist.com/mcp",
      "headers": { "Authorization": "Bearer olab_YOUR_KEY" }
    }
  }
}

Claude Code: claude mcp add --transport http olab-assist https://api.olabassist.com/mcp --header "Authorization: Bearer olab_YOUR_KEY"

Yalnızca adres kabul eden istemciler https://api.olabassist.com/mcp/olab_YOUR_KEY adresini kullanabilir. Bu adresi bir şifre gibi koruyun ve tek başına iptal edebilmek için ona ayrı bir anahtar kullanın.

Örnek sorular: “Bu hafta hangi müşteri sitelerim puan kaybetti?”, “ChatGPT example.com yerine kimi öneriyor?”, “example.com'daki kritik sorunları çözümleriyle birlikte listele.”

Looker Studio (Data Studio)

Looker Studio için OLAB Assist bağlayıcısı aynı v1 API'yi okur. Entegrasyonlar sayfasında bir anahtar oluşturun, Looker Studio'da bağla seçeneğini seçin, erişime izin verin ve anahtarı yapıştırın. Veriler rapor açıldığında okunur ve veri kaynağının güncellik süresi boyunca saklanır (varsayılan 12 saat; daha sık güncelleme için 15 dakika ya da 1 saat seçin). Google, Looker Studio'nun adını 2026'da Data Studio olarak değiştirdi; ürün aynıdır.

Her veri kaynağı için bir tablo seçin ve tek bir siteye ya da tüm sitelere göre filtreleyin. Veri kaynaklarını bir raporda Site alanıyla birleştirin. Her tablo kullanışlı bir varsayılan grafikle açılır.

  • Puan geçmişi (varsayılan: zaman içinde GEO puanı): tarama başına bir satır; tarama tarihi, site, rapor ve tüm puanlar ile sorun sayıları. Raporun tarih aralığını izler.
  • Rakiplere göre yapay zekâ görünürlüğü (varsayılan: markaya göre anılma sayısı): her yapay zekâ yanıtındaki takip edilen her marka için bir satır; sorulma tarihi, site, marka, kendi markanız, asistan, soru, niyet ile anılma, kaynak gösterilme ve sıra ölçümleri. Rakiplerle karşılaştırmak için zaman içinde markaya göre grafiğe dökün.
  • Kategoriye göre sorun trendi (varsayılan: zaman içinde kritik sorunlar): her tarama ve kategori (SEO, GEO, AEO, AIO) için bir satır; kritik sorunlar, uyarılar, açık sorunlar ve kategori puanı.
  • Siteler: site, marka adı, son kontrol, rapor, puan, SEO/GEO/AEO/AIO puanı, kritik sorunlar, uyarılar, kontrol edilen yapay zekâ yanıtları, markayı anan yanıtlar, anılma oranı ve takip edilen markalar arasındaki sıra.
  • Açık sorunlar: site, sorun, durum, kategori, etki, kanıt, nasıl düzeltilir, nerede, kontrol kimliği ve sorun sayısı.
  • Yapay zekâ yanıtları: yanıt başına bir satır; sorulma tarihi, site, soru, niyet, asistan, anıldı mı, kaynak gösterildi mi, ton, anılan markalar ile yanıtlar, markayı anan yanıtlar, siteyi kaynak gösteren yanıtlar ve anıldığında sıra ölçümleri. Raporun tarih aralığını izler.

İyi bir başlangıç: Puan geçmişinden Puan zaman serisi ve Yapay zekâ yanıtlarından asistana göre markayı anan yanıtlar ÷ yanıtlar tablosu.

Notion

Kod gerekmez. Entegrasyonlar sayfasında Notion'a bağlan seçeneğini seçin. Notion'un onay ekranında ya AI Visibility Dashboard şablonunu çoğaltın (tek tık, başka seçim gerekmez) ya da bir sayfa paylaşıp onu seçin. Site başına bir özet ve sayfa içinde gösterilen üç veritabanı içeren, markalı bir pano sayfası elde edersiniz. Sayfa her taramadan ve her yeni yapay zekâ yanıtından sonra güncellenir (en geç yaklaşık bir saat içinde, ya da Şimdi senkronize et ile hemen):

  • Siteler: site başına bir satır; genel ve SEO, GEO, AEO, AIO puanları, kritik sorunlar ve uyarılar, yapay zekâ yanıtlarının sizi ne sıklıkla andığı, takip edilen markalar arasındaki sıranız, tarihler ve rapor ile panoya bağlantılar.
  • Sorunlar: durum, kategori, etki, kanıt ve çözümüyle açık bulgular. Düzelen sorunlar silinmez, Çözüldü olarak işaretlenir.
  • Yapay zekâ yanıtları (haftalık yapay zekâ soru günlüğü): son 30 günden itibaren yanıt başına bir satır; soru, niyeti, asistan, anılıp anılmadığınız, sıra, kaynak gösterilme, ton, anılan markalar ve kaynaklar.

Satırlar yerinde güncellenir, asla çoğaltılmaz. Kendi sütunlarınızı ve görünümlerinizi ekleyebilirsiniz; bizim sütunlarımız her eşitlemede yeniden yazılır. Sonradan eklediğimiz yeni sütunlar mevcut veritabanlarınızda otomatik olarak görünür. Bağlantıyı kesmek güncellemeleri durdurur ve sayfaları Notion'da bırakır.

Niyet ve ton

Takip edilen her soru bir niyet etiketi alır: research (araştırma), comparison (karşılaştırma), purchase (satın alma) ya da brand (marka). Etiket bir kez, küçük bir dil modeliyle (yedek olarak anahtar kelimelerle) belirlenir. Bir yanıt markanızı andığında tonu positive (olumlu), neutral (nötr) ya da negative (olumsuz) olarak etiketlenir. İkisi de API'de (questions[].intent, answers[].question.intent, answers[].sentiment, ai_visibility.by_intent), Notion'da ve Looker Studio'da yer alır; panelde yanıtlar bunlara göre filtrelenebilir.

Sürümleme

Bu, sürüm 1'dir. v1 içinde yalnızca ekleme yaparız: yeni uç noktalar, yeni alanlar ve yeni olay türleri. Alanları kaldırmaz, yeniden adlandırmaz, anlamlarını ya da türlerini değiştirmeyiz. Tanımadığınız alanları yok sayın; biz özellik ekledikçe entegrasyonunuz çalışmaya devam eder. Geriye uyumsuz bir değişiklik gerekirse v1'in yanında /api/v2 olarak yayınlanır ve v1, e-postayla duyurulan bir geçiş süresi boyunca çalışmaya devam eder.

Değişiklik günlüğü

  • 2026-10: v1 yayınlandı: REST API, webhook'lar (scan.completed, answers.updated, site.created, site.deleted), MCP sunucusu ve Notion eşitlemesi.
  • 2026-10: uyarılar (score.dropped, visibility.lost, visibility.gained), Slack ve Discord biçimleri, Notion pano şablonu, Looker Studio rakip ve kategori tabloları, soru niyeti.