Specoria API, MCP ve GitHub Action

API ne yapar

• POST https://app.specoria.com/v1/scan bir sitede specoria.com’daki ücretsiz testin aynısını çalıştırır ve sonucu JSON olarak döner: 0–100 skor, seviye, kritik engeller ve durumu ile ağırlığıyla her kontrol.
• Tarama yalnızca verilen alan adındaki herkese açık sayfaları https üzerinden okur, başka alan adına giden yönlendirmeyi izlemez. Pazaryeri sayfaları ve tarama dışı alan adları reddedilir.
• İstek eşzamanlıdır. Sayfa okuma bütçesi 20 saniyedir; istemci zaman aşımını en az 60 saniye yapın.
• Aynı alan adı son 6 saatte tarandıysa siteye yeniden gidilmez, kayıtlı sonuç döner ("cached": true).
• API /v1 altında sürümlüdür. Yanıta yeni alan eklenebilir; v1 içinde var olan alanların anlamı değişmez.

API anahtarları

• Anahtarı Specoria panelinde oluşturun: Ekip ve profil → API anahtarları. Proje yöneticisi ve ticari onaylayıcı anahtar oluşturup iptal edebilir; organizasyon başına en fazla 10 etkin anahtar.
• Anahtar bir kez gösterilir. Biz yalnızca SHA-256 özetini ve gösterim için ilk 12 karakterini saklarız.
• Başlıkta gönderin: Authorization: Bearer spk_… — asla adreste değil. API tarayıcıdan (CORS) çağrılamaz; anahtarı sunucuda ya da CI sırlarında tutun.
• Anahtar organizasyonunuza aittir ve yalnızca organizasyonunuzun projelerini görür. İptal edilince ya da onu oluşturan kişi ekipten çıkınca çalışmaz.

Sınırlar

• Anahtar başına saatte 60, günde 500 tarama; MCP okuma araçlarında saatte 300 istek.
• Bir organizasyonun bütün anahtarları birlikte: saatte 60, günde 500 tarama (anahtar sayısını artırmak sınırı artırmaz).
• Önbellekten dönen sonuç sınıra sayılır; geçersiz istek (bozuk adres, pazaryeri, tarama dışı alan adı) sayılmaz.
• Sınır aşılınca HTTP 429 ve Retry-After başlığı döner. Başarılı yanıtta saatlik pencere için X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları vardır.
• API, hizmetin günlük tarama kapasitesinden ayrı bir pay kullanır: bütün API kullanıcıları için günde 100 yeni tarama (önbellekten dönen sonuç sayılmaz); böylece sitemizdeki ücretsiz testi asla tüketmez. Pay ya da genel kapasite dolunca HTTP 503 "busy" döner.

İstek

Örnek

curl -sS --max-time 90 -X POST https://app.specoria.com/v1/scan \
  -H "Authorization: Bearer $SPECORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://ornek.com.tr","lang":"tr"}'

Yanıt

Başarıda: {"success": true, "data": {…}}. data alanları:

{
  "success": true,
  "data": {
    "api_version": "v1",
    "model_version": "v2.4",
    "domain": "specoria.com",
    "scanned_at": "2026-10-08T14:02:48.579Z",
    "cached": false,
    "score": 75,
    "level": "partial",
    "insufficient": false,
    "blockers": [],
    "checks": [
      {
        "id": "bots_search",
        "status": "pass",
        "weight": 8,
        "…": "…"
      },
      {
        "id": "waf_access",
        "status": "pass",
        "weight": 8,
        "…": "…"
      },
      {
        "id": "no_js",
        "status": "na",
        "weight": 5,
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Kısaltılmış örnek; specoria.com için kendi ücretsiz test sonucumuzdan üretildi, tarama tarihi 2026-10-08 (tam JSON yöntem sayfasında). Ücretsiz test nasıl ölçer

Hatalar

{"success": false, "error": "…", "message": "…"}

Projeleriniz için MCP sunucusu

POST https://app.specoria.com/v1/mcp aynı anahtar ve sınırlarla Streamable HTTP üzerinden MCP konuşur (durumsuz, JSON yanıt). Araçlar:

İstemci ayarı (adres ve başlık kabul eden istemciler için)

{
  "mcpServers": {
    "specoria": {
      "type": "http",
      "url": "https://app.specoria.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${SPECORIA_API_KEY}"
      }
    }
  }
}

GitHub Action

Küçük bir eylem (action.yml ve tek bir JavaScript dosyası, yalnızca Node.js yerleşikleri) /v1/scan’i çağırır, işe bir özet tablo yazar ve skor min-score’un altındaysa adımı başarısız sayar.

- uses: <owner>/<repo>/integrations/github-action@<ref>
  with:
    url: https://ornek.com.tr
    api-key: ${{ secrets.SPECORIA_API_KEY }}
    min-score: 70
    lang: tr

• Girdiler: url, api-key, min-score (varsayılan 0), fail-on-blockers, lang, share. Çıktılar: score, level, blockers, passed, share-url.
• Skor yoksa (yeterince ölçülemedi) adım başarısız olur, çünkü karşılaştırılacak bir şey yoktur.
• Henüz GitHub Marketplace’te değil. iletisim@specoria.com adresine yazın, deponuza koyacağınız eylem dosyalarını gönderelim.

API’nin yapmadıkları

• Derin denetim, ajan simülasyonu, yapay zekâ görünürlüğü ya da ChatGPT Shopping ölçümü yok: bunlar panelde ve paketlerde kalır.
• API taramasında yapay zekâ modeli çağrılmaz.
• Yazma yok: mağazanızı ya da projenizi hiçbir zaman değiştirmez; webhook yok.
• Tarayıcıdan çağrı (CORS) ve adreste anahtar yok.

Sorular

iletisim@specoria.com