---
title: "Specoria API, MCP ve GitHub Action"
description: "Ücretsiz ajan hazırlık testini kendi betiklerinizden, CI’dan ya da yapay zekâ asistanınızdan çalıştırın; projenizin görevlerini MCP ile okuyun. Bu sitedeki testle aynı kurallar; API hiçbir zaman yapay zekâ modeli çağırmaz."
source_url: "https://specoria.com/tr/gelistiriciler/"
lang: "tr"
---

GELİŞTİRİCİLER

# Specoria API, MCP ve GitHub Action

Ücretsiz ajan hazırlık testini kendi betiklerinizden, CI’dan ya da yapay zekâ asistanınızdan çalıştırın; projenizin görevlerini MCP ile okuyun. Bu sitedeki testle aynı kurallar; API hiçbir zaman yapay zekâ modeli çağırmaz.

## 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

| Alan | Tür | Anlamı |
| --- | --- | --- |
| `url` | metin, zorunlu | Site adresi, ör. https://ornek.com.tr (en çok 300 karakter, port ya da kullanıcı bilgisi yok). |
| `lang` | "en" \| "tr", isteğe bağlı | Kontrol başlıklarının ve yardım bağlantılarının dili; genel alan adlarında Accept-Language. Varsayılan en. |
| `share` | mantıksal, isteğe bağlı | Ayrıca paylaşılabilir bir sonuç bağlantısı oluşturur (30 gün saklanır, erken kaldırma bağlantısıyla). Varsayılan false. |

**Ö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ı:

| Alan | Anlamı |
| --- | --- |
| `api_version, model_version` | API sürümü (v1) ve bu sonucun skor modeli sürümü. |
| `domain, scanned_at, cached` | Ölçülen alan adı, ne zaman ölçüldüğü ve sonucun 6 saatlik önbellekten gelip gelmediği. |
| `score` | Kritik engel tavanları uygulanmış 0-100 skor; yeterince ölçülemediyse null (insufficient: true). |
| `raw_score, potential` | Tavan öncesi ağırlıklı skor; ilk üç öncelik düzeltilirse ulaşılacak skor. |
| `level` | ready, partial ya da low. |
| `site_type` | ecommerce, lodging ya da service: hangi kontrol setinin uygulandığı. |
| `blockers, priorities` | Kalan kritik kontrollerin kimlikleri; düzeltme sırası. |
| `categories, coverage` | Kategori başına skor; kaç kontrolün ölçüldüğü, doğrulanamadığı ya da geçerli olmadığı. |
| `checks[]` | id, title, status (pass, warn, fail, na), weight, critical, blocker, reason (neden ölçülemedi), help_url. |
| `method_url, share` | Skorun nasıl hesaplandığı; paylaşım bağlantısı (url, revoke_url, expires_at) ya da null. |

`{
"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](https://specoria.com/tr/yontem/)

## Hatalar

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

| HTTP | error | Ne zaman |
| --- | --- | --- |
| 400 | `invalid_json, invalid_body, invalid_url` | Gövde JSON değil, bir alanın türü yanlış ya da adres herkese açık bir site adresi değil. |
| 401 | `missing_api_key, invalid_api_key` | Bearer anahtar yok ya da anahtar bilinmiyor, iptal edilmiş veya oluşturan kişi ekipten çıkmış. |
| 413 | `too_large` | Gövde 8 KB’tan büyük. |
| 422 | `marketplace, blocked_domain, unreachable, redirect` | Pazaryeri sayfası; tarama dışı alan adı; ana sayfa açılmadı; ana sayfa başka alan adına yönlendiriyor. |
| 429 | `rate_limited` | Sınır doldu; Retry-After’a bakın. |
| 502 / 503 | `scan_failed / busy` | Beklenmeyen hata; günlük kapasite doldu. Daha sonra yeniden deneyin. |

## 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:

| Araç | Ne yapar |
| --- | --- |
| `scan_store` | /v1/scan ile aynı tarama; tarama sınırına sayılır. |
| `list_projects` | Organizasyonunuzun projeleri: alan adı, son skor, kritik engeller, açık ve tamamlanan görevler. |
| `get_project_tasks` | Bir projenin panelde görünen görevleri (project_id ya da alan adıyla); durum open, todo, ongoing, done ya da all. |

**İ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

Ücretli paket gerekiyor mu? Hayır. Her proje yöneticisi ya da ticari onaylayıcı panelde anahtar oluşturabilir. Yukarıdaki sınırlar her anahtara uygulanır.

API sonucu specoria.com’daki testle aynı mı? Aynı tarama, aynı skor modeli ve aynı önbellek. Tek fark: sitedeki test, açık olduğunda kuralların okuyamadığı politika ayrıntılarını (ör. iade süresi) doldurmak için küçük bir yapay zekâ modeli kullanabilir. API hiçbir zaman yapay zekâ modeli çağırmaz; bu yüzden yeni bir API sonucu nadiren biraz farklı olabilir, önbellekten dönen sonuç ise modeli kullanan bir site testinden gelmiş olabilir.

Sahibi olmadığım siteleri tarayabilir miyim? Tarama, bu sitedeki ücretsiz test gibi yalnızca herkese açık sayfaları okur. Site sahipleri alan adlarının tarama dışı bırakılmasını isteyebilir (tarayıcı sayfamıza bakın).

[iletisim@specoria.com](mailto:iletisim@specoria.com)