SOV Tracker API

Tüm API istekleri Authorization header'ında Bearer token gerektirir. Anahtarınızı buradan alın: /dashboard/settings → API Erişimi.

Authorization: Bearer avt_live_xxxxxxxxxxxxxxxxxxxxxxxx

En son tamamlanmış taramaya göre tüm platformlardaki güncel SOV skorunu döndürür.

Request

curl -H "Authorization: Bearer $SOVTRACKER_KEY" \
  https://sovtracker.com/api/v1/sov

Response (200 OK)

{
  "scan_id": "scan_abc123",
  "completed_at": "2026-05-06T12:34:56Z",
  "avg_sov": 42,
  "platform_breakdown": {
    "chatgpt": 60,
    "claude": 35,
    "gemini": 50,
    "perplexity": 25,
    "ai_overviews": 40
  }
}

Son taramaları listele (yeniden eskiye). limit query param (max 50, varsayılan 10).

curl -H "Authorization: Bearer $SOVTRACKER_KEY" \
  "https://sovtracker.com/api/v1/scans?limit=20"

Response

{
  "scans": [
    {
      "id": "scan_abc123",
      "status": "completed",
      "scan_type": "manual",
      "started_at": "2026-05-06T12:30:00Z",
      "completed_at": "2026-05-06T12:34:56Z"
    }
  ]
}

Yeni tarama başlat. Aylık kotanızdan düşer. Body opsiyonel.

curl -X POST \
  -H "Authorization: Bearer $SOVTRACKER_KEY" \
  -H "Content-Type: application/json" \
  https://sovtracker.com/api/v1/scans

Response (202 Accepted)

{
  "scan_id": "scan_xyz789",
  "status": "running",
  "estimated_seconds": 60
}

Zaman Makinesi: tarihli ham AI cevap arşivi. Her tarama sonucu tam ham cevabıyla arşivlenir — "17 Temmuz 2026'da ChatGPT bu prompt'a ne cevap verdi?". Bu geçmiş sonradan üretilemez; yalnız o gün kaydedildiği için vardır.

Query parametreleri

• keyword_id — kelimeye göre filtrele (UUID)
• platform — chatgpt | claude | gemini | perplexity | ai_overviews
• from, to — ISO 8601 tarih aralığı
• limit — 1-100, varsayılan 50
• cursor — sayfalama: önceki cevabın meta.next_cursor değeri

curl -H "Authorization: Bearer $SOVTRACKER_KEY" \
  "https://sovtracker.com/api/v1/archive?platform=chatgpt&from=2026-06-01&limit=25"

Response (200 OK)

{
  "data": [
    {
      "id": "9f1c...",
      "scan_id": "scan_abc123",
      "platform": "chatgpt",
      "keyword_id": "kw_123",
      "prompt_used": "best crm tools for smb",
      "raw_response": "The most recommended CRM tools are...",
      "brand_mentioned": true,
      "mention_count": 2,
      "mention_position": 3,
      "sentiment": "positive",
      "sov_score": 42.5,
      "created_at": "2026-07-17T09:12:00Z"
    }
  ],
  "meta": {
    "count": 1,
    "next_cursor": "MjAyNi0wNy0xN1...",
    "plan_window_applied": false,
    "window_start": "2026-06-01T00:00:00.000Z"
  }
}

Geçmiş derinliği server tarafında plan bazlı uygulanır, ama bu yalnız dashboard'da anlam taşır: Free (orada son 7 günle sınırlı) ve Starter API'yi hiç çağıramaz — API erişimi Pro ve üzeri gerektirir, Pro ve üzerindeki her plan tüm arşivi alır. Yani gerçek bir API yanıtında meta.plan_window_applied pratikte her zaman false'tur.

Streamable HTTP ve Authorization başlığı destekleyen bir AI asistanını SOV verinize bağlayın. Sunucu Streamable HTTP konuşur ve REST API ile aynı API key ile doğrulanır (Pro ve üstü planlar). Tüm tool'lar salt-okunurdur ve key'in ait olduğu organizasyona scope'ludur.

https://sovtracker.com/api/mcp

API anahtarınızı buradan alın: /dashboard/settings → API Erişimi — MCP istemcisi bunu her istekte Authorization header'ı olarak gönderir.

Mevcut tool'lar

• get_visibility_summary — son tarama: genel SOV, platform bazlı skor/bahsedilme, önceki taramaya göre trend
• list_keywords — takip edilen kelimeler ve güncel durumları
• get_scan_results — bir taramanın satır bazlı sonuçları, platform/kelime filtresiyle
• get_answer_archive — Zaman Makinesi: tarihli ham AI cevapları (plan geçmiş derinliği uygulanır)
• get_business_card — işletme kartı durumu: güven skoru, alan grubu tazeliği, aktiflik beyan tarihi
• get_ai_traffic — AI yönlendirme sinyalleri ve yalnız AI etiketi taşıyan ziyaretler, ayrı raporlanır

Yazma veya tarama tetikleme tool'u yoktur — asistanınız organizasyon, kapsam ve planının izin verdiği kayıtları tarama kotası harcamadan okuyabilir.

Claude Code

Claude Code için .mcp.json dosyasına ekleyin:

{
  "mcpServers": {
    "sov-tracker": {
      "type": "http",
      "url": "https://sovtracker.com/api/mcp",
      "headers": {
        "Authorization": "Bearer avt_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor, .cursor/mcp.json içinde uzak URL ve Authorization başlığını destekler. Claude.ai için istek başlığıyla doğrulama beta erişimi olan bir organizasyon yöneticisi gerekir; uç noktayı ve Authorization: Bearer anahtarını birlikte girin. ChatGPT ile bu Bearer anahtarı üzerinden doğrudan bağlantı henüz doğrulanmadı.

Genel Streamable HTTP istemcisi

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://sovtracker.com/api/mcp"),
  {
    requestInit: {
      headers: { Authorization: "Bearer avt_live_xxx" },
    },
  }
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const tools = await client.listTools();
const summary = await client.callTool({
  name: "get_visibility_summary",
  arguments: {},
});

Rate limit: key başına dakikada 60 istek. 401 = eksik/geçersiz key veya Pro altı plan; 429 = rate limit aşıldı.

Olaylar tetiklendiğinde HTTP POST bildirim alın. URL ve olayları buradan ayarlayın: /dashboard/settings → Outbound Webhooks.

Mevcut olaylar

• scan.completed — tarama tamamlandığında
• sov.dropped — SOV uyarı eşiğinin altına düştü
• mention.detected — markanızdan yeni bir kez bahsedildi
• competitor.overtake — bir rakip öne geçti

Ön koşul: son üç olay uyarı motoru tarafından hesaplanır; her biri yalnız Ayarlar → Uyarılar & Bildirimler altındaki karşılık gelen kural AÇIKKEN tetiklenir (sov.dropped → SOV Düşüşü, mention.detected → Yeni Bahsedilme, competitor.overtake → Rakip Geçişi). Karşılık gelen uyarı e-postasıyla aynı anda gönderilir. scan.completed için böyle bir ön koşul yoktur.

Gövde

{
  "event": "scan.completed",
  "organization_id": "org_abc",
  "timestamp": "2026-05-06T12:34:56Z",
  "data": {
    "scan_id": "scan_xyz",
    "avg_sov": 42,
    "results_count": 50,
    "mentioned_count": 21
  }
}

İmza doğrulama

Her istek X-Sovtracker-Signature header'ı içerir (raw body'nin HMAC-SHA256 hex çıktısı, webhook secret'ınızla imzalanmış).

import crypto from 'crypto';

function verify(rawBody, headerSig, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(headerSig)
  );
}

• 401 — API key eksik veya geçersiz
• 403 — Plan API erişimi içermiyor (Pro+ gerekli)
• 429 — Aylık tarama kotası bitti
• 500 — Sunucu hatası — exponential backoff ile tekrar deneyin