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: Free yalnız son 7 günü görür; Starter ve üzeri tüm arşivi alır. Pencere istediğiniz aralığı kırptıysa meta.plan_window_applied true olur ve meta.window_start etkin başlangıcı gösterir.

Kendi AI asistanınızı — Claude (Desktop / claude.ai), ChatGPT connector'ları, Cursor veya herhangi bir MCP istemcisi — doğrudan 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 — son 30 günün AI kaynaklı ziyaretleri, kaynak bazında

Yazma veya tarama tetikleme tool'u yoktur — asistanınız her şeyi okuyabilir ama tarama kotanızı harcayamaz.

Claude Desktop / Claude Code

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

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

claude.ai'de (web) Ayarlar → Connectors → Add custom connector altına aynı URL ile ekleyin. Cursor .cursor/mcp.json içinde aynı JSON şeklini kullanır.

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 — yeni marka bahsi tespit edildi
• competitor.overtake — bir rakip öne geçti

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