Kulak API dokümantasyonu

1. 1Kulak'a kayıt ol ve bir proje oluştur; anahtar kelimelerini ekle.
2. 2Panelde Geliştirici bölümünden bir API anahtarı oluştur. Anahtar yalnızca bir kez gösterilir, güvenli bir yerde sakla.
3. 3Aşağıdaki istekle en acil bahsedilmeleri çek. Proje kimliğini panelin adres çubuğunda veya GET /projects yanıtında bulursun.

curl "https://kulak.app/api/v1/mentions?projectId=prj_123&minUrgency=4&limit=20" \
  -H "Authorization: Bearer kl_live_xxxxxxxxxxxxxxxx"

Her istekte Authorization: Bearer kl_live_... başlığını gönder. Anahtarlar sunucuda yalnızca özetlenmiş (hash) olarak saklanır; kaybedersen yenisini oluşturup eskisini iptal et.

Anahtarlar kapsam (scope) ile sınırlandırılır. :write kapsamı aynı kaynağın :read iznini de içerir. Bir anahtarı tek bir projeyle de sınırlayabilirsin; bu durumda projectId parametresi opsiyoneldir.

Erişimin olmayan ya da var olmayan kaynaklar aynı şekilde 404 döner; böylece başka hesaplara ait kimlikler tahmin edilemez.

Temel adres https://kulak.app/api/v1. İstek ve yanıt gövdeleri JSON'dur; gövde en fazla 64 KB olabilir.

Her yanıt aynı zarfı kullanır. Başarılı yanıtlar data ve meta, hatalar error alanı taşır. Her yanıtta x-request-id başlığı ve meta.requestId bulunur; destek taleplerinde bu kimliği paylaş.

{
  "data": {
    "id": "mnt_8f2k",
    "source": "x",
    "sentiment": "olumsuz",
    "urgency": 5
  },
  "meta": {
    "requestId": "req_3b1c9e",
    "idempotencyReplayed": false
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Gönderilen veri geçersiz.",
    "requestId": "req_3b1c9e",
    "issues": [
      {
        "path": "term",
        "message": "En az 2 karakter olmalı."
      }
    ]
  }
}

Hata kodu makine tarafından okunur ve sabittir; mesaj insan içindir ve değişebilir. İstemcinde her zaman error.code alanına göre dallan.

Yazma isteklerinde (POST, PATCH, DELETE) Idempotency-Key başlığı gönderebilirsin (en fazla 255 karakter). Aynı anahtarla tekrarlanan istek 24 saat boyunca ilk yanıtı döndürür ve meta.idempotencyReplayed alanı true olur.

Ağ hatasından sonra yeniden denerken aynı anahtarı kullan; çift kayıt oluşmaz. Her yeni işlem için yeni bir anahtar (ör. UUID) üret.

curl -X POST "https://kulak.app/api/v1/keywords" \
  -H "Authorization: Bearer kl_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d0e2c1a-4f5b-4a51-9d0c-2a4f0e6b1c11" \
  -d '{"projectId":"prj_123","term":"Tencere","type":"brand"}'

Liste uç noktaları cursor tabanlıdır: ?limit= (varsayılan 25, en fazla 100) ve ?cursor=. Sonraki sayfa için yanıttaki meta.nextCursor değerini gönder; değer null ise son sayfadasın.

Cursor'lar opaktır; içeriğini ayrıştırma ya da elle üretme.

Her API anahtarı dakikada 120 istek yapabilir. Sınır aşıldığında 429 rate_limited ve saniye cinsinden Retry-After başlığı döner.

Toplu okumalarda en büyük sayfa boyutunu kullan, yeni veriyi sürekli sorgulamak yerine webhook'lara abone ol.

Panelden bir endpoint ekle ve dinlemek istediğin olayları seç. Kulak her olayı imzalı bir POST isteğiyle gönderir. Endpoint'in 2xx dönmelidir; aksi durumda teslimat yeniden denenir.

İstek zaman aşımı 10 saniyedir, yönlendirmeler takip edilmez. Başarısız teslimatlar üstel beklemeyle en fazla 8 kez denenir; art arda 20 başarısızlıktan sonra endpoint otomatik devre dışı kalır. Teslimat geçmişini panelden görebilir, tek tıkla yeniden gönderebilirsin.

Aynı olay birden fazla kez ulaşabilir; webhook-id başlığını saklayarak tekrarları ayıkla.

{
  "id": "evt_k2x9p1",
  "type": "mention.created",
  "timestamp": "2026-09-29T08:41:12.000Z",
  "projectId": "prj_123",
  "data": {
    "id": "mnt_8f2k",
    "source": "x",
    "url": "https://x.com/...",
    "text": "Tencere uygulamasında ödeme adımında sürekli hata alıyorum...",
    "category": "hata_bildirimi",
    "sentiment": "olumsuz",
    "urgency": 5
  }
}

İmzalar Standard Webhooks biçimindedir: HMAC-SHA256(anahtar, "{webhook-id}.{webhook-timestamp}.{ham gövde}") sonucunun base64 kodlaması. Anahtar, whsec_ önekinden sonraki base64 değerin çözülmüş byte'larıdır.

Doğrulamayı JSON'u ayrıştırmadan önce, ham gövde üzerinde yap. Zaman damgası 5 dakikadan eskiyse isteği reddet (tekrar saldırılarına karşı) ve karşılaştırmada sabit zamanlı fonksiyon kullan.

1import { createHmac, timingSafeEqual } from "node:crypto";
2 
3const TOLERANCE_SECONDS = 300;
4 
5/** rawBody: ayrıştırılmamış istek gövdesi (string). */
6export function verifyKulakWebhook(secret, headers, rawBody) {
7  const id = headers["webhook-id"];
8  const ts = headers["webhook-timestamp"];
9  const sigHeader = headers["webhook-signature"];
10  if (!id || !ts || !sigHeader) return false;
11  if (Math.abs(Date.now() / 1000 - Number(ts)) > TOLERANCE_SECONDS) return false;
12 
13  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
14  const expected = createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest();
15 
16  return sigHeader.split(" ").some((part) => {
17    const [version, sig] = part.split(",", 2);
18    if (version !== "v1" || !sig) return false;
19    const given = Buffer.from(sig, "base64");
20    return given.length === expected.length && timingSafeEqual(given, expected);
21  });
22}

Bu liste uygulamanın ürettiği OpenAPI belgesinden otomatik oluşturulur; her zaman API ile birebir aynıdır.