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
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.
/feedHavuzdaki viral videolar; izlenmeye ya da havuza giriş zamanına göre sıralı.| platform | tiktok | instagram | youtube | all | Varsayılan: all |
| sort | views | newest | newest = havuza en son girenler |
| dateRange | 24h | 7d | 30d | 90d | Yalnız bu sürede havuza girenler |
| minViews | integer | En az izlenme |
| limit | 1–100 | Varsayılan: 20 |
| page | 1–50 | Varsayılan: 1 |
/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).| history | 1 | Büyüme eğrisini ekle |
/hashtags/trendingPencerede havuza giren videoların toplam izlenmesine göre sıralı hashtag'ler. #fyp gibi platform geneli etiketler çıkarılır.| platform | tiktok | instagram | youtube | all | Varsayılan: all |
| days | 1–60 | Varsayılan: 30 |
| limit | 1–100 | Varsayılan: 30 |
/creators/topPencerede havuza en çok izlenme getiren creator'lar.| platform | tiktok | instagram | youtube | all | Varsayılan: all |
| days | 1–90 | Varsayılan: 30 |
| limit | 1–100 | Varsayılan: 20 |
/agentsAjanların (takip ettiğin konular), terimleri ve ayarlarıyla./agents/{id}/matchesHavuzda ajanlarından biriyle eşleşen tüm videolar.| sort | newest | views | outlier | outlier = benzerlerinin çok üstünde performans |
| limit | 1–100 | Varsayılan: 48 |
| page | 1–100 | Varsayılan: 1 |
/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
| 400 | invalid_platform · invalid_dateRange | Bir parametrenin değeri geçersiz. Yanıtta izin verilen değerler yazar. |
| 401 | api_key_required · invalid_api_key | Anahtar yok, yanlış yazılmış ya da silinmiş. |
| 403 | plan_required | Anahtarın sahibi olan hesap artık Agency planında değil. |
| 404 | not_found | Hesabında bu kimlikle video ya da ajan yok. |
| 429 | rate_limit_exceeded | Saatlik 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.