# Kulak

> Kulak; X, Reddit, YouTube, LinkedIn, Ekşi Sözlük, Şikayetvar ve forumlarda markan, ürünlerin ve rakiplerin hakkında konuşulanları toplar, yapay zekâ ile sınıflandırır ve önemli olanı anında sana iletir.

## Türkçe

Kulak, Türkiye pazarı için bir sosyal dinleme platformudur. Markanı, ürünlerini, rakiplerini ve konuları X, Reddit, YouTube, LinkedIn, Ekşi Sözlük, Şikayetvar ve forumlarda izler; bahsedilmeleri (mention) toplar, tekilleştirir, yapay zekâ ile kategori, duygu (olumlu / nötr / olumsuz), aciliyet (1-5) ve bayraklarla sınıflandırır. Sonuçlar panoda, e-posta alarmlarında, webhook'larda ve REST API'de sunulur.

### Kaynak kapsamı
- X, Reddit, YouTube: anahtar kelimenin geçtiği herkese açık paylaşımlar (resmi API veya yetkili sağlayıcı).
- LinkedIn: yalnızca müşterinin OAuth ile bağladığı kendi şirket sayfası.
- Ekşi Sözlük: yalnızca başlığında anahtar kelime geçen başlıklara girilen entry'ler; içerik yapay zekâya gönderilmez (robots.txt ai-input=no), kural tabanlı sınıflandırılır.
- Şikayetvar: anahtar kelime araması yapılmaz; anahtar kelimeye bağlı marka sayfası (sikayetvar.com/<marka>) izlenir.
- Forumlar: DonanımHaber ve Technopat'ta yeni açılan konular (herkese açık son konu listesi ve RSS); yanıtlar izlenmez.
- Web kaynakları KulakBot ile okunur: https://kulak.shippe.rs/bot (robots.txt kurallarına uyar, oturum açmaz; engellemek için `User-agent: KulakBot` + `Disallow: /`).

### Planlar (KDV dahil)
- Başlangıç: 1.299 TL/ay, 3 anahtar kelime, ayda 1.000 mention, 1 üye
- Pro: 4.499 TL/ay, 7 anahtar kelime, ayda 10.000 mention, 5 üye
- Ölçek: 13.499 TL/ay, 15 anahtar kelime, ayda 50.000 mention, 20 üye
- Deneme: kart gerekmez, 3 anahtar kelime, toplam 100 mention.
Aşım ücreti yoktur; kota dolunca akış dönem sonuna kadar durur.

### API kullanımı
- Temel adres: https://kulak.shippe.rs/api/v1
- Kimlik: `Authorization: Bearer kl_live_...` (panel > Geliştirici bölümünden oluşturulur, yalnızca bir kez gösterilir).
- Zarf: başarı `{ "data": ..., "meta": { "requestId", "idempotencyReplayed", "nextCursor" } }`, hata `{ "error": { "code", "message", "requestId" } }`.
- Erişemediğin kaynaklar 404 döner. Yazma isteklerinde `Idempotency-Key` başlığı desteklenir (24 saat).
- Sayfalama: `?cursor=&limit=` (en fazla 100); sonraki sayfa `meta.nextCursor`.
- Rate limit: anahtar başına dakikada 120 istek; aşılırsa 429 ve `Retry-After`.
- Gövde sınırı: 64 KB.
- Tam şema: https://kulak.shippe.rs/openapi.json

## English

Kulak is a social listening platform built for the Turkish market. It monitors brands, products, competitors and topics across X, Reddit, YouTube, LinkedIn (own company page via OAuth), Ekşi Sözlük (topic-title matches only, rule-based classification), Şikayetvar (brand page) and Turkish forums (DonanımHaber, Technopat; new threads only), deduplicates mentions and classifies them (category, sentiment, urgency 1-5, flags). Results are delivered via dashboard, email alerts, webhooks and a REST API. UI and content are primarily Turkish; prices are in TRY (VAT included).

### API quick reference
- Base URL: https://kulak.shippe.rs/api/v1 . Auth: `Authorization: Bearer kl_live_...`
- Scopes: projects:read, projects:write, keywords:read, keywords:write, mentions:read, mentions:write, alerts:read, alerts:write, webhooks:read, webhooks:write, usage:read, account:read (`:write` implies `:read`).
- Inaccessible resources return 404. Writes accept `Idempotency-Key`. Cursor pagination via `meta.nextCursor`.
- OpenAPI 3.1: https://kulak.shippe.rs/openapi.json
- Web sources are read by KulakBot (User-Agent contains "KulakBot"), which obeys robots.txt: https://kulak.shippe.rs/bot

### Endpoints
- GET /api/v1/projects: Projeleri listele [projects:read]
- POST /api/v1/projects: Proje oluştur [projects:write]
- GET /api/v1/projects/{id}: Proje ayrıntısı [projects:read]
- PATCH /api/v1/projects/{id}: Proje güncelle [projects:write]
- DELETE /api/v1/projects/{id}: Proje sil [projects:write]
- GET /api/v1/projects/{id}/members: Üyeler ve davetler [projects:read]
- POST /api/v1/projects/{id}/members: Üye davet et [projects:write]
- GET /api/v1/keywords: Keyword'leri listele [keywords:read]
- POST /api/v1/keywords: Keyword oluştur (plan limiti uygulanır) [keywords:write]
- GET /api/v1/keywords/{id}: Keyword ayrıntısı [keywords:read]
- PATCH /api/v1/keywords/{id}: Keyword güncelle / duraklat (active) [keywords:write]
- DELETE /api/v1/keywords/{id}: Keyword sil [keywords:write]
- GET /api/v1/keyword-groups: Grupları listele [keywords:read]
- POST /api/v1/keyword-groups: Grup oluştur [keywords:write]
- GET /api/v1/keyword-groups/{id}: Grup ayrıntısı [keywords:read]
- PATCH /api/v1/keyword-groups/{id}: Grup güncelle [keywords:write]
- DELETE /api/v1/keyword-groups/{id}: Grup sil [keywords:write]
- GET /api/v1/mentions: Mention akışı (filtreli, cursor sayfalı) [mentions:read]
- GET /api/v1/mentions/{id}: Mention ayrıntısı (tespit özeti + notlar; maliyet/model/ham tespit içermez) [mentions:read]
- PATCH /api/v1/mentions/{id}: Durum güncelle [mentions:write]
- POST /api/v1/mentions/{id}/irrelevant: Alakasız işaretle / geri al [mentions:write]
- GET /api/v1/analytics/mentions: Mention analizi (zaman serisi, dağılımlar, ses payı) [mentions:read]
- GET /api/v1/categories: Kategorileri listele [projects:read]
- POST /api/v1/categories: Kategori oluştur [projects:write]
- GET /api/v1/categories/{id}: Kategori ayrıntısı [projects:read]
- PATCH /api/v1/categories/{id}: Kategori güncelle [projects:write]
- DELETE /api/v1/categories/{id}: Kategori sil (sistem kategorileri hariç) [projects:write]
- GET /api/v1/alerts: Alarmları listele [alerts:read]
- POST /api/v1/alerts: Alarm oluştur [alerts:write]
- GET /api/v1/alerts/{id}: Alarm ayrıntısı [alerts:read]
- PATCH /api/v1/alerts/{id}: Alarm güncelle [alerts:write]
- DELETE /api/v1/alerts/{id}: Alarm sil [alerts:write]
- GET /api/v1/saved-views: Görünümleri listele [mentions:read]
- POST /api/v1/saved-views: Görünüm oluştur [mentions:write]
- GET /api/v1/saved-views/{id}: Görünüm ayrıntısı [mentions:read]
- PATCH /api/v1/saved-views/{id}: Görünüm güncelle [mentions:write]
- DELETE /api/v1/saved-views/{id}: Görünüm sil [mentions:write]
- GET /api/v1/webhooks: Webhook'ları listele [webhooks:read]
- POST /api/v1/webhooks: Webhook oluştur (secret yalnızca bu yanıtta) [webhooks:write]
- GET /api/v1/webhooks/{id}: Webhook ayrıntısı [webhooks:read]
- PATCH /api/v1/webhooks/{id}: Webhook güncelle [webhooks:write]
- DELETE /api/v1/webhooks/{id}: Webhook sil [webhooks:write]
- POST /api/v1/webhooks/{id}/test: Test olayı gönder (senkron sonuç) [webhooks:write]
- GET /api/v1/webhooks/{id}/deliveries: Teslimat geçmişi [webhooks:read]
- POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/replay: Teslimatı yeniden gönder [webhooks:write]
- GET /api/v1/usage: Plan ve kota kullanımı [usage:read]
- GET /api/v1/account: Hesap bilgisi [account:read]

### Webhook events
- mention.created
- mention.updated
- mention.status_changed
- mention.marked_irrelevant
- keyword.created
- keyword.updated
- keyword.deleted
- keyword_group.created
- keyword_group.updated
- keyword_group.deleted
- alert.created
- alert.updated
- alert.deleted
- alert.delivered
- project.created
- project.updated
- project.deleted
- integration.connected
- integration.disconnected
- webhook.test
Signatures follow Standard Webhooks: headers `webhook-id`, `webhook-timestamp`, `webhook-signature: v1,<base64 HMAC-SHA256(secret, id.timestamp.body)>`. Secrets start with `whsec_`.

## İletişim / Contact
destek@kulak.app