API & MCP referansı
Panelde gördüğünüz her şey iki programatik arayüzle de erişilebilir: klasik REST API ve AI ajanları için MCP sunucusu. Temel adres: https://api.yerliveri.com
Kimlik doğrulama
| Token | Ön ek | Kapsam | Nereden alınır |
|---|---|---|---|
| Kullanıcı token'ı | yvm_… | Tüm projeler + yazma işlemleri (proje/alan/anahtar oluşturma) | Panel → Hesap → MCP token (bir kez gösterilir) |
| Proje anahtarı | yvk_… | Yalnızca bir projede salt-okunur analytics | Panel → proje → Kurulum → API anahtarları |
curl -H "Authorization: Bearer yvk_…" \ https://api.yerliveri.com/v1/projects/prj_…/analytics/overview?days=7
REST uçları
| Uç | Yöntem | Açıklama |
|---|---|---|
/v1/status | GET | Bileşen sağlığı ve sürüm |
/v1/bulk?days=7 | GET | Tüm projeler: toplamlar, paylar, en iyi sayfalar |
/v1/projects | GET/POST | Projeleri listele / oluştur (döner: id, site_key) |
/v1/projects/{id} | GET/DELETE | Proje detayı / sil (geri alınamaz: toplama durur, anahtarlar iptal) |
/v1/projects/{id}/domains | GET/POST | Alan adları; POST doğrulama token'ı döner (DNS TXT) |
/v1/projects/{id}/keys | GET/POST | API anahtarları; anahtar yalnızca oluşturma anında gösterilir |
/v1/projects/{id}/analytics/{topic} | GET | overview · timeseries · pages · sources · devices · geo · errors · performance · heatmap?path= · events · realtime · funnel?steps= · anomalies |
/v1/projects/{id}/usage | GET | Günlük kullanım sayaçları |
/v1/projects/{id}/export?days=90 | GET | Tüm aggregate verisi JSON — veri ihracı |
/v1/audit?limit=50 | GET | Denetim kaydı (kullanıcı token'ı gerekir) |
Tüm yanıtlar JSON'dur ve Cache-Control: no-store ile gelir. Zaman pencereleri UTC gün bazlıdır; benzersiz sayıları ~%3 hatalı HyperLogLog tahminidir, olay/gösterim sayıları kesindir.
MCP sunucusu (AI ajanları için)
Uç nokta: https://api.yerliveri.com/mcp — Streamable HTTP JSON-RPC (initialize → tools/list → tools/call), Authorization: Bearer yvm_… ile. ZCode, Claude Desktop veya destekleyen herhangi bir MCP istemcisine şu şekilde eklenir:
{
"mcp": {
"servers": {
"yerliveri": {
"type": "http",
"url": "https://api.yerliveri.com/mcp",
"headers": { "Authorization": "Bearer yvm_…" }
}
}
}
}
18 araç: list_projects, create_project, add_domain, create_api_key, delete_project (geri alınamaz — ajansınıza onaylattırın), analytics_bulk, analytics_overview, analytics_timeseries, analytics_pages, analytics_sources, analytics_devices, analytics_geo, analytics_realtime, analytics_errors, analytics_performance, analytics_funnel, analytics_anomalies, analytics_events.
Örnek tur: create_project → site anahtarını kurulum koduna yerleştir → add_domain ile TXT token'ı al → analytics_realtime ile akışı doğrula → analytics_bulk ile portföyü izle. Ajanlar için tam kılavuz: agent skill dokümanı.
Toplama uçları (SDK olmayan istemciler)
| Uç | Açıklama |
|---|---|
POST /v1/batch (a.yerliveri.com) | Toplu olay gönderimi — gövde: {"v":1,"k":"yv_…","e":[…]}, Content-Type: text/plain |
POST /v1/collect?k=yv_… | Tek olay gönderimi |
GET /v1/pixel.gif?k=yv_…&e=page_view | Piksel (yalnızca sayfa görüntüleme) |
GET /v1/sdk.js | SDK'nın kendisi (önbelleklenir) |
Sunucu tarafı doğrulama vardır: geçersiz zaman damgası (±10 dk), bozuk kimlikler ve bilinmeyen anahtarlar reddedilir (unknown_site), kötüye kullanım hız limitine takılır (429 + Retry-After).
Hız limitleri
| Kapsam | Limit |
|---|---|
| Kimlik uçları (giriş/kayıt) | 10 istek/dk/IP |
| REST + MCP | 300 istek/dk/ilke |
| Toplama | 240 istek/dk/IP · proje başına 3000/dk (anonim: 60/dk) |