Public API v1

Genel bakış

Public API v1 tek bir salt-okunur uç sunar. Yazma (prompt ekleme, rerun tetikleme) API üzerinden yapılamaz; bunlar panelden yürütülür. Webhooks henüz yok — planlanıyor.

GET https://yanit.io/api/v1/visibility?days=30
Authorization: Bearer iai_live_...

• Taban URL: https://yanit.io
• Biçim: JSON (UTF-8). Tüm yanıtlar cache-control: no-store ve x-request-id başlığı taşır.
• Scope: read:visibility (şu an tek scope).
• Adil kullanım: hesap başına 5 aktif token.

Kimlik doğrulama

Her istek Authorization: Bearer iai_live_… başlığı taşımalıdır. Token, hesabın Owner rolündeki kullanıcısı tarafından panelde /dashboard/api sayfasından oluşturulur.

• Token yalnızca oluşturulduğu anda bir kez gösterilir; sonradan tekrar görüntülenemez. Kaybederseniz yenisini oluşturun.
• İsteğe bağlı son kullanma süresi: 1–365 gün. Süresi dolan token 401 döner.
• Token istediğiniz an iptal edilebilir (revoke); iptal anında geçersiz olur.
• Her token tek scope ile gelir: read:visibility.
• Eksik, biçimi bozuk, geçersiz, iptal edilmiş veya süresi dolmuş token → 401 unauthorized.

GET /api/v1/visibility

Hesabınızın (tenant) son N günlük agregat görünürlük verisini döner. Veri, panelin ana sayfasındaki metriklerle birebir aynı hesaplamadan gelir.

OPTIONS isteği CORS preflight için 204 döner.

Yanıt alanları

Metrik tanımları

Hatalı (ERROR) run’lar her iki metrikte de paydaya dahil edilmez; errored_runs alanında ayrıca raporlanır. Paydası sıfır olan pencerelerde skor 0 döner.

Rate limit

Token başına 60 istek / dakika (kayan pencere). Her yanıt şu başlıkları taşır:

Limit aşıldığında 429 rate_limited döner. Veri gece toplu güncellendiği için dakikada birden fazla çekmenin pratik faydası yoktur; sonuçları kendi tarafınızda önbelleğe alın.

Hatalar

Tüm hata yanıtları aynı JSON şemasını kullanır. requestId değerini destek taleplerinde paylaşın; details yalnızca doğrulama hatalarında bulunur.

{
  "message": "Geçersiz veya eksik API token",
  "code": "unauthorized",
  "requestId": "req_7f3c2a91"
}

CORS

GET ve OPTIONS için Access-Control-Allow-Origin: * döner; izin verilen başlıklar Authorization ve Content-Type. Bu, sunucu tarafı ve edge ortamlarını kolaylaştırmak içindir — token’ı asla tarayıcıya gönderilen JavaScript’e gömmeyin; herkesin görebileceği bir yerde durur. Ön yüz gösterimleri için veriyi kendi backend’inizden proxy’leyin.

Güvenlik

• Token düz metin olarak saklanmaz; veri tabanında yalnızca SHA-256 hash'i tutulur. Bu yüzden sonradan görüntülenemez.
• Rotasyon: yeni bir token oluşturun, entegrasyonu güncelleyin, eskisini iptal edin. Aynı anda birden fazla token aktif olabilir (5 adede kadar).
• Token oluşturma ve iptal işlemleri hesabın denetim kaydına (audit log) yazılır: kim, ne zaman.
• Son kullanım zamanı (lastUsedAt) panelde görünür; kullanılmayan token’ları iptal edin.
• Token’ı ortam değişkeninde veya gizli anahtar yöneticisinde tutun; sürüm kontrolüne eklemeyin.

Örnekler

curl -s "https://yanit.io/api/v1/visibility?days=30" \
  -H "Authorization: Bearer iai_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "window_days": 30,
  "generated_at": "2026-09-06T08:12:41.000Z",
  "visibility_score": 62.5,
  "share_of_voice": 41.2,
  "total_runs": 432,
  "errored_runs": 6,
  "total_mentions": 655,
  "trend": [
    { "date": "2026-08-08", "visibility": 58.3 },
    { "date": "2026-08-09", "visibility": 61.1 }
  ],
  "by_provider": [
    { "provider": "OPENAI", "visibility": 71.4 },
    { "provider": "ANTHROPIC", "visibility": 63.9 },
    { "provider": "GOOGLE", "visibility": 52.1 }
  ],
  "competitors": [
    { "name": "Rakip A", "count": 212 },
    { "name": "Rakip B", "count": 173 }
  ],
  "top_citation_sources": [
    { "domain": "wikipedia.org", "count": 48 },
    { "domain": "g2.com", "count": 31 }
  ],
  "definitions": {
    "visibility_score": "own-brand-mentioned SUCCESS runs / SUCCESS runs × 100",
    "share_of_voice": "own mentions / (own + competitor mentions) × 100; errored runs excluded"
  }
}

// Sunucu tarafında çalıştırın (Node 18+, Deno, Bun, edge function).
// Token'ı asla tarayıcıya gönderilen koda gömmeyin.
const res = await fetch('https://yanit.io/api/v1/visibility?days=30', {
  headers: { Authorization: `Bearer ${process.env.IAI_API_TOKEN}` },
});

if (res.status === 429) {
  const wait = Number(res.headers.get('Retry-After') ?? 60);
  throw new Error(`Rate limit; ${wait} sn sonra tekrar deneyin`);
}
if (!res.ok) {
  const err = await res.json(); // { message, code, requestId }
  throw new Error(`${err.code}: ${err.message} (${err.requestId})`);
}

const data = await res.json();
console.log(data.visibility_score, data.share_of_voice);
console.log('Kalan istek:', res.headers.get('X-RateLimit-Remaining'));

Ücretsiz araç uçları (token gerekmez)

Ücretsiz araçların arkasındaki uçlar herkese açıktır: POST + JSON gövde, JSON yanıt. Kayıtsız kullanımda IP başına saatlik sınır ve küresel tavan vardır; giriş yapmış kullanıcıda hesap başına 30/saat. 429’da Retry-After bekleme süresini verir. Yalnızca http/https ve herkese açık adresler; özel ağ adresleri 400 döner. Deterministik tarayıcı; LLM’e kişisel veri gitmez.

Uçlar sözleşme değil: araç sayfaları için tasarlandı, sürüm garantisi vermiyoruz; entegrasyon için Public API’yi kullanın. Tarayıcımızın kimliği ve engelleme: YanitBot.