● Agency planına dahil

Viral trend verisi, API olarak

TikTok, Instagram ve YouTube için tek REST API: sıralı viral videolar, büyüme eğrileri, trend hashtag'ler, öne çıkan creator'lar ve kendi ajanlarının eşleşmeleri; yeni eşleşmeleri sana gönderen webhook'larla birlikte.

Anahtarları Agency çalışma alanında oluştur. Henüz Agency değil misin? Planları gör

Hızlı başlangıç
curl "https://vosscore.com/api/v1/feed?platform=tiktok&sort=newest&dateRange=24h&limit=10" \
  -H "X-API-Key: $VOSSCORE_API_KEY"

🔑 Kimlik doğrulama

Her istekte anahtarını X-API-Key başlığında gönder. Bearer başlığı da çalışır. Anahtarı sunucunda tut; tarayıcıya ya da uygulamaya koyma.

X-API-Key: vsk_••••••••••••••••
# or
Authorization: Bearer vsk_••••••••••••••••

Temel adres: https://vosscore.com/api/v1

📦 Video nesnesi

{
  "id": "tt_7627486...",
  "platform": "tiktok",
  "title": "...",
  "author": "hirsizkedi",
  "url": "https://www.tiktok.com/@.../video/...",
  "thumbnailUrl": "https://...",
  "views": 1200000,
  "likes": 42700,
  "comments": 812,
  "shares": 3100,
  "durationSec": 21,
  "hashtags": ["cat", "funny"],
  "publishedAt": "2026-10-27T09:14:00.000Z",
  "collectedAt": "2026-10-28T02:40:11.000Z",
  "vosscoreUrl": "https://vosscore.com/trend/tt_...",
  "embeddable": true
}

embeddable: false platformun bu videonun başka sitelere gömülmesine izin vermediği anlamına gelir. Veri yine geçerlidir; gömmek yerine url bağlantısını kullan.

Uç noktalar

Tüm uçlar GET ve JSON döner.

GET/feedHavuzdaki viral videolar; izlenmeye ya da havuza giriş zamanına göre sıralı.
platformtiktok | instagram | youtube | allVarsayılan: all
sortviews | newestnewest = havuza en son girenler
dateRange24h | 7d | 30d | 90dYalnız bu sürede havuza girenler
minViewsintegerEn az izlenme
limit1–100Varsayılan: 20
page1–50Varsayılan: 1
GET/videos/{id}Tek bir video. Büyüme anlık görüntüleri için history=1 ekle (zamana göre izlenme, beğeni, yorum).
history1Büyüme eğrisini ekle
GET/hashtags/trendingPencerede havuza giren videoların toplam izlenmesine göre sıralı hashtag'ler. #fyp gibi platform geneli etiketler çıkarılır.
platformtiktok | instagram | youtube | allVarsayılan: all
days1–60Varsayılan: 30
limit1–100Varsayılan: 30
GET/creators/topPencerede havuza en çok izlenme getiren creator'lar.
platformtiktok | instagram | youtube | allVarsayılan: all
days1–90Varsayılan: 30
limit1–100Varsayılan: 20
GET/agentsAjanların (takip ettiğin konular), terimleri ve ayarlarıyla.
GET/agents/{id}/matchesHavuzda ajanlarından biriyle eşleşen tüm videolar.
sortnewest | views | outlieroutlier = benzerlerinin çok üstünde performans
limit1–100Varsayılan: 48
page1–100Varsayılan: 1
GET/usageAnahtarının saatlik limiti, bu saat kullanılan istek ve pencerenin sıfırlanma zamanı.

İstek limitleri

Her anahtar saatte 1.000 istek yapabilir; en fazla 5 anahtar oluşturabilirsin. Her yanıt nerede olduğunu söyler. Daha fazlası mı lazım? Agency hesaplarına özel limit tanımlanır: beklediğin hacmi yazarak e-postalarımızdan birine yanıt ver.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1793782800   # unix seconds
Retry-After: 1260               # only on 429

Hatalar

400invalid_platform · invalid_dateRangeBir parametrenin değeri geçersiz. Yanıtta izin verilen değerler yazar.
401api_key_required · invalid_api_keyAnahtar yok, yanlış yazılmış ya da silinmiş.
403plan_requiredAnahtarın sahibi olan hesap artık Agency planında değil.
404not_foundHesabında bu kimlikle video ya da ajan yok.
429rate_limit_exceededSaatlik limit doldu. Retry-After süresi kadar bekle.

Webhook'lar

Herhangi bir ajana webhook adresi ekle (ajan ayarları → Webhook adresi). O ajanla yeni videolar eşleştiğinde onları sana POST ederiz; sorgulamana gerek kalmaz. Slack, Discord ve DingTalk robot bağlantılarına hazır mesaj gider (DingTalk: robotun güvenlik anahtar kelimesini “Vosscore” yap, 164.92.244.151 IP'sine izin ver ya da imza için adresin sonuna &secret=SEC… ekle); diğer HTTPS adreslerine aşağıdaki imzalı JSON gider. Denemek için ajan ayarlarındaki “Test gönder”i kullan.

Gövde · agent.new_matches

POST https://your-endpoint.com/hooks
Content-Type: application/json
X-Vosscore-Event: agent.new_matches
X-Vosscore-Timestamp: 1793781234
X-Vosscore-Signature: sha256=5f2c...

{
  "event": "agent.new_matches",
  "test": false,
  "sentAt": "2026-11-04T10:00:00.000Z",
  "agent": { "id": "...", "name": "Street food",
             "keywords": [...], "hashtags": [...],
             "platforms": [...], "url": "..." },
  "count": 3,
  "items": [ /* video objects */ ]
}

10 saniye içinde herhangi bir 2xx ile yanıt ver. Yönlendirmeler izlenmez.

İmzayı doğrula

İmza anahtarın Agency çalışma alanında. "timestamp.gövde" metninin HMAC-SHA256 değerini hesapla ve başlıkla karşılaştır.

const crypto = require("crypto");
// rawBody: the request body exactly as received
const ts = req.headers["x-vosscore-timestamp"];
const expected = "sha256=" + crypto
  .createHmac("sha256", process.env.VOSSCORE_WEBHOOK_SECRET)
  .update(ts + "." + rawBody)
  .digest("hex");
const got = String(req.headers["x-vosscore-signature"] || "");
const valid = got.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));

Vosscore üstünde geliştir

REST API, webhook'lar ve 5 takım koltuğu Agency planıyla gelir. İlk anahtarını bir dakikada oluştur.