Veriniz, REST ve MCP üzerinden

Hızlı başlangıç

1. Ayarlar → 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 → API anahtarları'ndan 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": 62,
    "grade": "C",
    "components": [
      { "key": "coverage", "value": 0.44, "weight": 0.3 },
      { "key": "sov", "value": 0.18, "weight": 0.25 },
      { "key": "engines", "value": 0.67, "weight": 0.2 },
      { "key": "geo", "value": 0.81, "weight": 0.15 }
    ]
  },
  "rank": {
    "rank": 4,
    "of": 23,
    "basis": "domains cited across your tracked queries — forums, reference sites and press are counted alongside rivals"
  },
  "shareOfVoicePct": 18
}

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 (12 okuma aracı: siteler, 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ı

12 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_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; Promvia olayları oraya POST'lar: her tam alıntı taramasından sonra run.completed (durum, anılma durumu değişen sorgular 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": 62, "grade": "C", "basis": "current at delivery time" }
}

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"));
}

Webhook olayları yalnızca TAM alıntı taramaları içindir — trend hattı bilerek dışarıdadır; değişiklik olmasa da 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ı.