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
}

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