Veriniz, REST ve MCP üzerinden

Hızlı başlangıç

1. Ayarlar → Entegrasyonlar → API anahtarları bölümünden bir anahtar oluşturun (Pro ve üzeri). Anahtar bir kez gösterilir — parola gibi saklayın.
2. Anahtarı bearer token olarak geçip herhangi bir uca çağrı yapın; ilk çağrı /v1/sites olmalı — diğer her çağrının aldığı site id'lerini o döndürür.
3. İsterseniz REST'i atlayın: bir MCP istemcisini aşağıdaki sunucuya bağlayın — aynı anahtar tüm okuma araçlarını kapsar.

Kimlik doğrulama

Ayarlar → Entegrasyonlar → API anahtarları bölümünden bir anahtar oluşturun (Pro ve Ajans). Bearer başlığıyla gönderin — asla URL içinde değil. Anahtarlar hesap sahibinin kimliğidir: sahibi her anahtarı görebilir, döndürebilir ve iptal edebilir.

curl https://promvia.app/api/v1/sites \
  -H "Authorization: Bearer pv_live_..."

Sınırlar, açıkça

REST istekleri ve MCP araç çağrıları TEK aylık havuzdan düşer: Pro'da ayda 10.000, Ajans'ta 50.000 istek + dakikada 120 isteklik ani-yük sınırı. Havuz her ayın 1'inde (UTC) sıfırlanır. Kontroller, taramalar ve üretim kendi ürün bütçelerini korur — bir API çağrısı onları asla harcamaz; yalnız onları gerçekten çalıştıran eylemler harcar.

Başarılı yanıtlar ve aylık-havuz 429'ları X-RateLimit-Limit / -Remaining / -Reset başlıklarını taşır; GET /api/v1/usage hesabın tüm haklarını tek okumada verir. Havuz aşımında sınırı ve sıfırlanma tarihini söyleyen bir 429 alırsınız; ayrı dakikalık ani-istek 429'u ise yalnızca kısa süre sonra yeniden denemenizi ister.

REST uçları

Tasarım gereği salt-okunur (yazmalar OAuth kapsamlı MCP'de). Makine-okur açıklama: openapi.json

GET /v1/sites/{siteId}/visibility — yanıtlar kayıtlarını yanlarında taşır (sıralamanın basis alanı dipnot değil, verinin parçasıdır):

{
  "site": { "id": "site_1a2b3c", "name": "Acme", "domain": "acme.com" },
  "score": {
    "score": 49,
    "grade": "D",
    "components": [
      { "key": "coverage", "value": 0.44, "weight": 0.3 },
      { "key": "sov", "value": 0.1, "weight": 0.25 },
      { "key": "engines", "value": 0.8, "weight": 0.2 },
      { "key": "geo", "value": 0.81, "weight": 0.15 }
    ]
  },
  "rank": {
    "rank": 4,
    "of": 14,
    "basis": "businesses cited across your discovery questions — you plus every other brand that took an answer slot. Forums, reference sites, press, directories and social are excluded, and questions naming your own brand are not counted"
  },
  "scoreBasis": "A weighted index (0–100) over up to five components; a component with no signal (e.g. sentiment) is left out and the rest renormalized. …",
  "shareOfVoicePct": 10,
  "shareOfVoiceSample": {
    "successes": 4,
    "n": 40,
    "interval95Pct": { "low": 4, "high": 23 },
    "tooThin": false,
    "note": "4 of 40 = 10%. 95% Wilson score interval 4-23%."
  },
  "rivals": [
    {
      "domain": "rival-a.example", "you": false, "rank": 1, "shareOfVoicePct": 23, "versusYou": "tied",
      "shareOfVoiceSample": { "successes": 9, "n": 40, "interval95Pct": { "low": 12, "high": 38 }, "tooThin": false, "note": "9 of 40 = 23%. 95% Wilson score interval 12-38%." }
    },
    {
      "domain": "rival-b.example", "you": false, "rank": 2, "shareOfVoicePct": 18, "versusYou": "tied",
      "shareOfVoiceSample": { "successes": 7, "n": 40, "interval95Pct": { "low": 9, "high": 32 }, "tooThin": false, "note": "7 of 40 = 18%. 95% Wilson score interval 9-32%." }
    },
    {
      "domain": "rival-c.example", "you": false, "rank": 3, "shareOfVoicePct": 13, "versusYou": "tied",
      "shareOfVoiceSample": { "successes": 5, "n": 40, "interval95Pct": { "low": 5, "high": 26 }, "tooThin": false, "note": "5 of 40 = 13%. 95% Wilson score interval 5-26%." }
    },
    {
      "domain": "acme.com", "name": "Acme", "you": true, "rank": 4, "shareOfVoicePct": 10, "versusYou": null,
      "shareOfVoiceSample": { "successes": 4, "n": 40, "interval95Pct": { "low": 4, "high": 23 }, "tooThin": false, "note": "4 of 40 = 10%. 95% Wilson score interval 4-23%." }
    },
    {
      "domain": "rival-d.example", "you": false, "rank": 5, "shareOfVoicePct": 8, "versusYou": "tied",
      "shareOfVoiceSample": { "successes": 3, "n": 40, "interval95Pct": { "low": 3, "high": 20 }, "tooThin": false, "note": "3 of 40 = 8%. 95% Wilson score interval 3-20%." }
    }
  ],
  "rivalsBasis": "The top five businesses by share of voice, ordered by share, with your own row (you: true) always included: appended with its real rank when it is not in the five. Each share is that business's answer slots out of every answer slot a business occupied across your discovery questions, the same denominator as shareOfVoicePct and rank. Forums, reference sites, press, directories and social are excluded, and questions naming your own brand are not counted. Equal counts share a rank. When two businesses' 95% intervals overlap, the data shows no measured lead between them: call it a tie (versusYou: 'tied'), never 'ahead'. A competitor known only by a name you listed has domain null and that name in name. Your own rank is null while you hold no answer slot, as the top-level rank is. Empty when no completed check has ranked anyone."
}

Her oran, ölçüldüğü örneklemi de taşır. Gerçek bir oran olan her Pct alanının yanında bir …Sample kardeşi bulunur: arkasındaki sayımlar, aynı birimde %95 Wilson skor aralığı ve tooThin — n 32'nin altındaysa doğru olur; bu örneklem büyüklüğünün altında %95 aralığı ölçeğin üçte birinden geniş olabilir. Yalnızca n'e bakar, bu yüzden aynı n ile ölçülen her oran aynı tooThin değerini taşır; oran o örneklemden okunamaz. 10’da 2 ile 1.000’de 200 aynı “%20”’dir ve aynı bulgu değildir. Oran olmayan sayılar — Görünürlük Skoru, GEO hazırlık skoru, cevap içi sıra, ziyaretçi kalite katsayısı, para — bilerek aralıksızdır ve bunu Basis ya da note alanında söyler; aralık uydurmak bizim ürettiğimiz bir kesinlik olurdu. Bu alanlar eklemedir: v1’de adı geçen hiçbir alan yeniden adlandırılmadı ya da kaldırılmadı.

15 Ekim 2026'da değişti: tooThin (ve CSV dışa aktarımındaki _sample_too_small sütunları) artık yalnızca n'e bakar ve n, 32 sayısının altındaysa doğrudur. Bu tarihten önce gözlenen aralığın genişliğine bakıyordu; bu yüzden artık daha fazla oran tooThin: true taşır.

Hatalar

Her hata, error alanı olan bir JSON'dur. Karşılaşacağınız durumlar:

MCP sunucusu

MCP destekleyen herhangi bir asistanı aşağıdaki uca yöneltin. API anahtarıyla bağlantı salt-okunurdur (13 okuma aracı: siteler, kullanım hakları, görünürlük skoru, alıntılar, geçmiş, kanıt, kaynaklar, GEO denetimi ve eylemleri, fırsatlar, şablonlar, derin tarama, trafik metrikleri); 6 yazma aracı — prompt ekleme, koşum ve tarama başlatma, brief üretme — eşleşen kapsamda bir OAuth izni ister; sızan bir anahtar okuyabilir ama asla işlem yapamaz.

{
  "mcpServers": {
    "promvia": {
      "url": "https://promvia.app/api/mcp",
      "headers": { "Authorization": "Bearer pv_live_..." }
    }
  }
}

MCP araçları

13 okuma aracı yukarıdaki REST uçlarıyla aynı yanıtları döndürür — iki yüzey tek ortak okuma modeli üzerine kurulu, bu yüzden birbirinden sapamaz. Bir API anahtarı hepsini kapsar.

list_sites · get_usage · get_visibility_score · get_citations · get_citation_history · get_evidence · get_sources_report · get_geo_audit · get_geo_actions · get_opportunities · get_prompt_templates · get_deep_scan · get_metrics

6 yazma aracı uygulamanın kendi kapı merdivenlerinden geçer (plan havuzları, bütçeler, doğrulama) ve adı geçen scope ile bir OAuth izni ister — tek başına API anahtarı bilerek salt-okunur kalır.

Yazma kapsamları: prompts:write, runs:write, content:write, actions:write. Her yazma, aynadaki panel butonuyla aynı kapı merdiveninden geçer — kotalar, doğrulama ve plan sınırları dahil — yani tıkla alınamayan hiçbir şey API ile de alınamaz.

Webhook'lar

Sorgulamak yerine Ayarlar'dan bir HTTPS uç noktası kaydedin (yalnızca standart 443 portunda https:// — başka bir port içeren adres kaydederken ve her teslimatta reddedilir); Promvia olayları oraya POST'lar: her tam alıntı taramasından sonra run.completed (durum, anılma durumu değişen sorular ve teslim anındaki görünürlük skoru ile) ve bu değişiklikler olduğunda citations.changed. Teslimatlar üstel geri çekilmeyle 8 denemeye kadar yinelenir; sürekli başarısız olan uç nokta otomatik kapatılır ve Ayarlar'dan yeniden açılabilir.

Bir teslimatın telde görünüşü:

{
  "event": "run.completed",
  "deliveryId": "7f3c9e2a-…",
  "sentAt": "2026-09-01T13:05:12.000Z",
  "site": { "id": "site_1a2b3c", "name": "Acme", "domain": "acme.com" },
  "run": {
    "id": "b41d…", "status": "completed",
    "queriesChecked": 14, "queriesFailed": 0,
    "startedAt": "2026-09-01T13:00:02.000Z"
  },
  "citations": { "won": ["best crm for startups"], "lost": [] },
  "visibilityScore": { "score": 49, "grade": "D", "basis": "current at delivery time" }
}

queriesChecked, taramada en az bir yapay zekâ cevap motorunun cevapladığı soruları sayar; queriesFailed geri kalanları. Yalnız Bing arama vekilinin sonuç döndürdüğü bir soru başarısız sayılır — sonuç sayfası yapay zekâ cevabı değildir (2026-09-29'dan beri; öncesinde kontrol edilmiş sayılıyordu). Kazanılan ve kaybedilen listeleri de aynı kurala uyar.

Her teslimat X-Promvia-Signature başlığı taşır: t=<unix saniye>,v1=<uç nokta gizli anahtarınızla "<t>.<ham gövde>" üzerinden hex HMAC-SHA256>. MAC'i sabit zamanlı karşılaştırmayla doğrulayın ve 5 dakikadan eski zaman damgalarını reddedin — yakalanmış bir isteğin yeniden oynatılmasını bu yakalar. Aynı imzayla bir webhook.test olayı Ayarlar'dan gönderilebilir.

// Node.js — verify X-Promvia-Signature
const { createHmac, timingSafeEqual } = require("node:crypto");
function verify(secret, rawBody, header) {
  const m = header.match(/^t=(\d+),v1=([0-9a-f]{64})$/);
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const mac = createHmac("sha256", secret).update(`${m[1]}.${rawBody}`).digest();
  return timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}

run.completed haftalık ve talep üzerine kontrolleri kapsar; günlük kontrol yalnızca bir şey değiştiğinde citations.changed gönderir, eğilim kontrolü hiçbir şey göndermez — değişiklik olmasa da her gün ateşlenen bir webhook gürültü olurdu. visibilityScore alanı teslim anındaki değeri taşır: yinelenen teslimat skoru yineleme anındaki haliyle bildirir, asla geriye dönük kurgu yapmaz.

Sayılar ne anlatır

Yanıtlar kendi kayıtlarını taşır (bir sıralamanın neye karşı ölçüldüğü, bir taramanın hangi sayfaları sayıp hiç çekmediği) — çünkü bir asistan alanları ham okur ve müşterinize aynen söyler. Temiz ölçülemeyen sayı null döner ve bunu söyler — ürünün kendi kuralı.