webaccess API

Genel bakış

webaccess küçük bir REST API sunar. Onu bir alan adına ya da URL'e yöneltirsiniz; içeriği SSRF koruması ve nezaket kuralları ardında getirir ve çıkarılmış sonucu döndürür. Asla veri uydurmaz: bir sayfa getirilemezse turu, içerik uydurmak yerine başarısız olarak raporlar.

Base URL

https://api.webaccess.searchestra.com

Kurallar

• Tüm istek ve yanıt gövdeleri application/json'dur.
• Başarılı yanıtlar üst düzey bir data alanına sarılır. Hatalar üst düzey bir error alanı döndürür (bkz. Hatalar).
• Her /v1/* uç noktası X-API-Key başlığını ister. /healthz istemez.
• Her istekte kendi clientRef'inizi verirsiniz; verinizi kapsar ve izole eder (bkz. Kimlik doğrulama).
• Zaman damgaları UTC ve ISO 8601'dir (örneğin 2026-08-24T10:12:00Z).

Hızlı başlangıç

Bir tarama başlatın, sonra durumunu poll edin. wa_live_your_key'i tenant'ınıza verilen API anahtarıyla değiştirin (bkz. Kimlik doğrulama).

curl -X POST https://api.webaccess.searchestra.com/v1/crawl/start \
  -H "X-API-Key: wa_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "godiva.com.tr",
    "scope": "domain",
    "clientRef": "marka-123"
  }'

{
  "data": {
    "runId": "01a0347a-3cd9-70e1-9dce-c2dd5962a4e6",
    "status": "pending"
  }
}

Ardından tur done ya da failed olana dek poll edin ve çıkarılan sayfaları okuyun:

curl "https://api.webaccess.searchestra.com/v1/crawl/pages?clientRef=marka-123&domain=godiva.com.tr" \
  -H "X-API-Key: wa_live_your_key"

Kimlik doğrulama

Her /v1/* isteği X-API-Key başlığında bir API anahtarı taşımalıdır. Anahtarlar wa_live_ önekiyle başlar ve bir kullanıcıyı değil bir tenant'ı temsil eder.

X-API-Key: wa_live_your_key

Sunucu yalnızca anahtarın hash'ini saklar. Ham değer yalnızca üretim anında bir kez gösterilir ve kurtarılamaz. Anahtar kaybolursa yeni bir tane üretin.

Çok-kiracılılık ve clientRef

Her istekte ayrıca kendi proje ya da marka kimliğinizi, clientRef'i verirsiniz. Servis bunu doğrulanmış tenant'ınızla birleşik bir anahtara çevirir; böylece veri izolasyonu otomatiktir: aynı clientRef'i kullanan iki farklı müşteri birbirinin verisini asla görmez.

Tarama başlat

Bir alan adı için asenkron taramayı başlatır ve hemen bir runId döner. İş arka planda yürür: GET /v1/crawl/{runId} ile izleyin ya da webhook'u bekleyin.

Aynı alan adı bu proje için yakın zamanda tarandıysa (varsayılan 24 saat), servis yeniden taramak yerine son turu döndürür. Bu kısayolu atlayıp sıfırdan yeniden taramak için force: true verin.

İstek gövdesi

{ "data": { "runId": "01a0347a-3cd9-70e1-9dce-c2dd5962a4e6", "status": "pending" } }

Tur durumunu getir

Bir tarama turunun anlık durumunu ve ilerleme sayaçlarını döner. status, done ya da failed olana dek poll edin. clientRef'inizi sorgu parametresi olarak verin.

{
  "data": {
    "runId": "01a0347a-3cd9-70e1-9dce-c2dd5962a4e6",
    "status": "running",
    "domain": "godiva.com.tr",
    "scope": "domain",
    "pagesFound": 90,
    "pagesCrawled": 74,
    "pagesFailed": 2
  }
}

status şunlardan biridir: pending, running, done, failed. failed olduğunda bir error alanı nedeni açıklar.

En son turu getir

Projenin en son tarama turunu runId'ye ihtiyaç duymadan döner: "şu an aktif bir tarama var mı, en son ne tarandı?" sorusunun cevabı. Hiç tur yoksa data boş bir nesnedir ({}).

Taranan sayfaları listele

Projenin taranmış sayfalarını çıkarılmış içerikleriyle döner: başlık, açıklama, görünür metin, durum kodu, kanonik URL ve yapısal veri. Ham HTML varsayılan olarak dahildir; onsuz daha hafif bir yanıt için summary=true verin.

Sorgu parametreleri

{
  "data": [
    {
      "url": "https://godiva.com.tr/urunler",
      "canonicalUrl": "https://godiva.com.tr/urunler",
      "title": "Ürünler",
      "description": "Godiva çikolata koleksiyonu",
      "textExcerpt": "El yapımı Belçika çikolataları...",
      "statusCode": 200,
      "fetchedVia": "http",
      "depth": 1,
      "crawledAt": "2026-08-24T10:12:00Z"
    }
  ]
}

fetchedVia, düz çekim için http; sayfa gerçek bir headless tarayıcı gerektirdiğinde browser'dır.

Projeyi indeksle

Projenin tüm taranmış sayfalarını arama ve RAG için paragraf sınırlarında parçalara böler ve — bir embedding sağlayıcı yapılandırılmışsa — vektör üretir. Embedding yoksa parçalar yine saklanır; yalnızca klasik tam-metin arama çalışır.

{ "clientRef": "marka-123" }

{ "data": { "pagesIndexed": 74, "chunksCreated": 210, "chunksEmbedded": 210 } }

chunksEmbedded, embedding sağlayıcı yapılandırılmadığında 0'dır.

Tek URL çek

Tek bir adresi ham HTML, tüm HTTP başlıkları ve tam yönlendirme zinciriyle getirir; zamanlama metrikleri (TTFB, toplam süre) ve gövde boyutu dahil.

{ "url": "https://competitora.com" }

{
  "data": {
    "html": "...",
    "headers": { "Content-Type": ["text/html"] },
    "statusCode": 200,
    "finalUrl": "https://competitora.com/",
    "redirectChain": [ { "url": "http://competitora.com", "status": 301 } ],
    "ttfbMs": 120,
    "totalMs": 480,
    "bodyBytes": 51234,
    "fetchedVia": "http",
    "robotsBlocked": false,
    "fromCache": false
  }
}

Core Web Vitals ölç

Gerçek bir headless tarayıcı açar ve bir sayfanın performans metriklerini ölçer: LCP (en büyük içeriğin yüklenmesi), CLS (görsel kayma) ve TBT (toplam bloklama süresi).

{ "url": "https://competitora.com" }

{ "data": { "lcp": 2100, "cls": 0.04, "tbt": 150, "ttfb": 180, "lcpSupported": true } }

Destek bayrakları (lcpSupported, clsSupported, ...) her metriğin bu sayfada gözlenebilip gözlenemediğini söyler.

robots.txt getir

Bir alan adının robots.txt kurallarını ham metin olarak döner.

{ "domain": "competitora.com" }

{ "data": { "found": true, "rawBody": "User-agent: *\nDisallow: /admin" } }

Sitemap adreslerini getir

Bir alan adının site haritasındaki adresleri listeler. Index sitemap ve sıkıştırılmış (.xml.gz) sitemap'ler desteklenir. Bilinen sitemap yollarını hints ile verebilirsiniz.

{ "domain": "competitora.com", "hints": [] }

{ "data": { "urls": ["https://competitora.com/urun-1", "https://competitora.com/urun-2"] } }

Sağlık kontrolü

Konteyner orkestrasyonu için liveness probe. Kimlik doğrulama gerektirmez. Servis ayaktayken 200 döner.

Kapsamlar

crawl/start'taki scope alanı, bir taramanın seed alan adından ne kadar uzağa uzandığını belirler.

Webhook

Bir tur tamamlandığında ve tenant'ınız bir webhook URL'i kaydettiyse, webaccess HMAC-SHA256 imzalı bir olay gönderir; böylece poll etmek zorunda kalmazsınız.

{
  "event": "crawl.completed",
  "runId": "01a0347a-3cd9-70e1-9dce-c2dd5962a4e6",
  "clientRef": "marka-123",
  "status": "done",
  "pagesCrawled": 74,
  "pagesFailed": 2
}

Yükü güvenmeden önce imza başlığını WEBHOOK_SECRET'ınıza karşı doğrulayın.

Hatalar

Hatalar bir code ve bir message içeren error nesnesi döndürür.

{ "error": { "code": "unauthorized", "message": "Geçersiz API anahtarı." } }

Limitler ve varsayılanlar

Tarama davranışı yapılandırılabilir varsayılanlarla sınırlanır. Bunlar hem hedefi hem bütçenizi korur.

Bunlar dağıtım düzeyi varsayılanlardır; maxPages, crawl/start'ta tur başına geçersiz kılınabilir.