Geliştiriciler · API v1

REST API

Hesap sayfanızdaki verilerin aynısı, JSON olarak: durumları ve kesintileriyle izlenen siteler, puanı ve bulgularıyla raporlarınız, istediğiniz an ücretsiz yapay zekâ botu kontrolü.

Anahtar oluşturEtkin bir izleme aboneliği gerekir

yalnızca kendi verileriniz

Bu sayfada (7)

§1Başlarken
§2Kimlik doğrulama
§3İstek sınırları
§4Kurallar
§5Hatalar
§6Uç noktalar
§7Değişiklikler

Başlarken

Temel adres

https://approvalens.com/api/v1

Her uç nokta JSON döner ve yalnızca anahtarın sahibi olan hesabın verilerini okur: izlenen siteleri ve e-posta adresiyle taranan ya da satın alınan raporları.

1
Oturum açın ve site sağlığı izlemeye abone olun (aylık 4,99 $): API onunla gelir.
2
Hesap → API anahtarları bölümünü açın, bir anahtar oluşturup kopyalayın: yalnızca bir kez gösterilir.
3
Her istekte bearer token olarak gönderin.

Kimlik doğrulama

Etkin bir izleme aboneliği gerekir

API erişimi, site sağlığı izleme aboneliğiyle (4,99 $ aylık) gelir; abonelik etkinken ya da iptal edilmiş ama henüz bitmemişken. Tam rapora dahil bir aylık izleme API içermez. Abonelik yoksa anahtarlarınız silinmez ama her istek 403 subscription_required döner; abonelik yeniden etkin olunca aynı anahtarlar çalışır.

Anahtarlar al_live_ ile başlar, ardından 32 karakter gelir. Authorization başlığında gönderin:

Authorization: Bearer al_live_••••••••••••••••••••••••••••••••

Bir hesabın en fazla 5 etkin anahtarı olabilir. Hesap sayfasında iptal ettiğiniz anahtar hemen çalışmaz olur. Her anahtarın yalnızca SHA-256 parmak izini saklarız; kaybolan anahtar yeniden gösterilemez, yenisini oluşturun.

API sunucular ve betikler içindir. CORS başlığı göndermez; başka bir sitedeki web sayfası onu ziyaretçinin tarayıcısından çağıramaz. Anahtarı asla ön yüz koduna koymayın.

İstek sınırları

Anahtar başına dakikada 60 istek; kayan bir dakika üzerinden sayılır. Her yanıtta şunlar bulunur:

X-RateLimit-Limit sınır (60)
X-RateLimit-Remaining geçerli dakikada kalan istek
X-RateLimit-Reset en eski isteğin pencereden çıkacağı an (Unix saniyesi)

Sınır aşılınca saniye cinsinden Retry-After başlığıyla 429 dönülür. POST /api/v1/ai-checks ücretsiz aracın kendi sınırına da tabidir: anahtar başına dakikada 6 kontrol; son 10 dakikada kontrol edilmiş bir site o sonucu geri alır (cached: true). Yanlış anahtarlı istekler IP adresi başına dakikada 20 ile sınırlıdır.

429

{
  "error": "rate_limited",
  "message": "Rate limit of 60 requests per minute per key reached. Retry in 12 s."
}

Kurallar

Zamanlar UTC'de, kesirsiz ISO-8601'dir: 2026-10-06T09:14:03Z. Olmayan zaman null'dır.
İnsanların okuyacağı metinler (kesinti açıklamaları, uyarı satırları, bulgu başlıkları) için ?lang=tr ekleyin; varsayılan İngilizcedir.
Alan adları www ile ve www olmadan eşleşir.
v1 yanıtlarına alan eklenebilir; mevcut alanların adı ve anlamı değişmez. Geriye uyumsuz değişiklikler yolda yeni bir sürümle gelir.

Hatalar

Hatalar HTTP durumunu ve makinenin okuyacağı bir kod ile insanlar için bir cümle içeren JSON gövdesini kullanır:

Kod	Durum	Anlamı
missing_key	401	Authorization: Bearer başlığı yok.
invalid_key	401	Anahtar hatalı biçimde, bilinmiyor ya da iptal edilmiş.
subscription_required	403	Hesabın etkin bir izleme aboneliği yok. Abonelik olunca aynı anahtarlar yeniden çalışır.
rate_limited	429	Çok fazla istek: Retry-After kadar saniye bekleyin.
bad_request	400	Bir parametre ya da JSON gövdesi geçersiz.
not_found	404	Böyle bir uç nokta yok ya da hesabınızda bu kimlikte veya alan adında bir şey yok.
unreachable	422	Yalnızca YZ kontrolü: site yanıt vermedi.
unavailable	503	Bizim tarafımızda bir sorun oldu. Biraz sonra tekrar deneyin.

Uç noktalar

Yapı birebir aynıdır; değerler örnektir.

GET/api/v1/sites

İzlenen siteleri listele

Hesabınız için izlenen her site ve şu anki durumu: ayakta mı, 30 günlük erişilebilirlik, TLS sertifikasının kalan günü, ads.txt, ana sayfayı kaç yapay zekâ botunun okuyabildiği, son ve sonraki günlük kontrol ve varsa süren kesinti. Abonelik ya da rapora dahil ay bitince monitoring false olur.

Örnek istek

curl https://approvalens.com/api/v1/sites \
  -H "Authorization: Bearer $APPROVALENS_KEY"

Örnek yanıt

{
  "sites": [
    {
      "host": "example.com",
      "url": "https://example.com/",
      "status": "up",
      "monitoring": true,
      "plan": {
        "status": "active",
        "source": "subscription",
        "renews_at": "2026-10-25T10:00:00Z",
        "ends_at": null,
        "included_until": null,
        "test": false
      },
      "uptime_30d": 99.93,
      "tls_valid": true,
      "tls_days_left": 41,
      "tls_expires_at": "2026-11-16T12:00:00Z",
      "ads_txt": "found",
      "ai_allowed": 11,
      "ai_total": 14,
      "last_check": "2026-10-06T05:00:00Z",
      "next_check": "2026-10-07T05:00:00Z",
      "last_uptime_probe": "2026-10-06T09:58:00Z",
      "open_incident": null,
      "alerts_enabled": true
    }
  ]
}

GET/api/v1/sites/{host}

Tek bir izlenen site

Listedeki her şey, ayrıca yapay zekâ botu dökümü, en son 5 kesinti ve en son 10 uyarı (e-postanın söylediği satırlar ve gönderilip gönderilmediği).

host: site, www ile ya da www olmadan

Örnek istek

curl https://approvalens.com/api/v1/sites/example.com \
  -H "Authorization: Bearer $APPROVALENS_KEY"

Örnek yanıt

{
  "site": {
    "host": "example.com",
    "url": "https://example.com/",
    "status": "up",
    "monitoring": true,
    "plan": {
      "status": "active",
      "source": "subscription",
      "renews_at": "2026-10-25T10:00:00Z",
      "ends_at": null,
      "included_until": null,
      "test": false
    },
    "uptime_30d": 99.93,
    "tls_valid": true,
    "tls_days_left": 41,
    "tls_expires_at": "2026-11-16T12:00:00Z",
    "ads_txt": "found",
    "ai_allowed": 11,
    "ai_total": 14,
    "last_check": "2026-10-06T05:00:00Z",
    "next_check": "2026-10-07T05:00:00Z",
    "last_uptime_probe": "2026-10-06T09:58:00Z",
    "open_incident": null,
    "alerts_enabled": true,
    "ai_crawlers": {
      "allowed": 11,
      "blocked_by_robots": 2,
      "blocked_by_server": 1,
      "unknown": 0,
      "total": 14
    },
    "pending_confirmation": [],
    "latest_check_url": "https://approvalens.com/ai/Xk2v9QmL0pRa",
    "incidents": [
      {
        "id": 12,
        "started_at": "2026-10-03T10:00:00Z",
        "ended_at": "2026-10-03T10:25:00Z",
        "ongoing": false,
        "duration_seconds": 1500,
        "reason": "http_502",
        "http_status": 502,
        "description": "HTTP 502"
      }
    ],
    "alerts": [
      {
        "id": 87,
        "at": "2026-10-03T10:25:00Z",
        "kind": "up",
        "emailed": true,
        "lines": [
          "Your homepage answers again. It was down for 25 minutes (Oct 3, 2026 08:00 UTC – Oct 3, 2026 08:25 UTC). Reason seen: HTTP 502."
        ],
        "check_id": null
      },
      {
        "id": 86,
        "at": "2026-10-03T10:10:00Z",
        "kind": "down",
        "emailed": true,
        "lines": [
          "example.com is down · HTTP 502"
        ],
        "check_id": null
      }
    ]
  }
}

GET/api/v1/sites/{host}/incidents

Bir sitenin kesintileri

5 dakikalık erişilebilirlik kontrolünün bulduğu, since sonrasında biten ya da hâlâ süren kesintiler; en yenisi önce. Kesinti art arda iki başarısız kontrolden sonra açılır.

host: site, www ile ya da www olmadan
since: ISO-8601 tarih ya da zaman; varsayılan 30 gün önce
limit: 1–500, varsayılan 100

Örnek istek

curl "https://approvalens.com/api/v1/sites/example.com/incidents?since=2026-09-06" \
  -H "Authorization: Bearer $APPROVALENS_KEY"

Örnek yanıt

{
  "host": "example.com",
  "since": "2026-09-06T08:00:00Z",
  "incidents": [
    {
      "id": 12,
      "started_at": "2026-10-03T10:00:00Z",
      "ended_at": "2026-10-03T10:25:00Z",
      "ongoing": false,
      "duration_seconds": 1500,
      "reason": "http_502",
      "http_status": 502,
      "description": "HTTP 502"
    }
  ]
}

GET/api/v1/reports

Raporlarınızı listele

Oturum açıkken yaptığınız taramalar ve e-posta adresinizle satın alınan raporlar, en yenisi önce: puan ve sonuç (tarama bitene kadar ya da site bizi engellediyse null), raporun kilidinin ne zamana kadar açık olduğu ve kilit açmanın başlattığı derin tarama.

Örnek istek

curl https://approvalens.com/api/v1/reports \
  -H "Authorization: Bearer $APPROVALENS_KEY"

Örnek yanıt

{
  "reports": [
    {
      "id": "q7RkT2mYw9Lb3xNc",
      "host": "example.com",
      "url": "https://example.com/",
      "status": "done",
      "score": 78,
      "verdict": "almost",
      "created_at": "2026-10-04T10:00:00Z",
      "finished_at": "2026-10-04T10:06:50Z",
      "unlocked": true,
      "unlocked_until": "2026-11-03T10:00:00Z",
      "ai_unlocked_until": null,
      "deep_scan": {
        "id": "Hn4sP0dVe8KqZ1aY",
        "status": "done",
        "progress": 100
      },
      "report_url": "https://approvalens.com/scan/q7RkT2mYw9Lb3xNc"
    }
  ]
}

GET/api/v1/reports/{id}

Tek bir rapor

Puan, sonuç, önem derecesine göre sorun sayıları, kategori puanları ve başlığı ile önem derecesiyle başarısız her bulgu. Bir bulgunun arkasındaki sayfalar ve parametreler (kanıt) yalnızca hesabınızda sitenin kilidi açıksa gelir: tam raporda hepsi, YZ görünürlük raporunda YZ bulguları.

id: listedeki rapor kimliği

Örnek istek

curl https://approvalens.com/api/v1/reports/q7RkT2mYw9Lb3xNc \
  -H "Authorization: Bearer $APPROVALENS_KEY"

Örnek yanıt

{
  "report": {
    "id": "q7RkT2mYw9Lb3xNc",
    "host": "example.com",
    "url": "https://example.com/",
    "status": "done",
    "score": 78,
    "verdict": "almost",
    "created_at": "2026-10-04T10:00:00Z",
    "finished_at": "2026-10-04T10:06:50Z",
    "unlocked": true,
    "unlocked_until": "2026-11-03T10:00:00Z",
    "ai_unlocked": true,
    "ai_unlocked_until": null,
    "report_url": "https://approvalens.com/scan/q7RkT2mYw9Lb3xNc",
    "counts": {
      "blocker": 0,
      "critical": 1,
      "warning": 3,
      "notice": 2,
      "pass": 74
    },
    "categories": [
      {
        "id": "content",
        "score": 71
      },
      {
        "id": "trust",
        "score": 90
      }
    ],
    "pages_scanned": 50,
    "findings": [
      {
        "id": "content.thin_pages",
        "title": "Thin articles",
        "category": "content",
        "severity": "critical",
        "level": "official",
        "evidence_total": 26,
        "unlocked": true,
        "params": {
          "thin": 26,
          "very_thin": 9,
          "of": 42,
          "pct": 62,
          "median": 131,
          "tools": 0
        },
        "evidence": [
          {
            "url": "https://example.com/recipes/quick-salsa/",
            "detail": "96 words"
          },
          {
            "url": "https://example.com/recipes/lemonade/",
            "detail": "118 words (+240 words of menus/footer)"
          }
        ]
      },
      {
        "id": "trust.contact_missing",
        "title": "Contact information",
        "category": "trust",
        "severity": "warning",
        "level": "official",
        "evidence_total": 0,
        "unlocked": true,
        "params": {},
        "evidence": []
      }
    ]
  }
}

POST/api/v1/ai-checks

Yapay zekâ botu kontrolü çalıştır

Bir ana sayfa için ücretsiz “Yapay zekâ sitenizi görebiliyor mu?” kontrolünü çalıştırır (yaklaşık 20 saniye) ve sonucun tamamını döner: her yapay zekâ botunun robots.txt kuralı ve simüle isteği, meta yönergeleri, llms.txt ve site haritası. Yeni kontrolde 201, önbellekteki sonuçta 200.

url: JSON gövdesi: sitenin adresi

Örnek istek

curl -X POST https://approvalens.com/api/v1/ai-checks \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Örnek yanıt

{
  "check": {
    "id": "aic_7Qm2xK9pLs",
    "url": "greenleaf-journal.example",
    "final_url": "https://www.greenleaf-journal.example/",
    "host": "www.greenleaf-journal.example",
    "checked_at": "2026-10-06T12:45:00Z",
    "duration_ms": 17420,
    "cached": false,
    "headline": {
      "key": "blocked_server",
      "bot": "ChatGPT-User",
      "product": "ChatGPT"
    },
    "summary": {
      "allowed": 6,
      "blocked_robots": 4,
      "blocked_server": 3,
      "unknown": 1,
      "total": 14
    },
    "bots": [
      {
        "id": "oai-searchbot",
        "token": "OAI-SearchBot",
        "name": "OAI-SearchBot",
        "vendor": "OpenAI",
        "product": "ChatGPT",
        "purpose": "search",
        "kind": "fetcher",
        "doc_url": "https://developers.openai.com/api/docs/bots",
        "robots_respected": true,
        "robots": {
          "allowed": true,
          "group": "*",
          "rule": null
        },
        "http": {
          "simulated": true,
          "status": 200,
          "verdict": "ok",
          "reason": "200 OK, same page as a browser",
          "similarity": 0.98,
          "headers": {
            "content-type": "text/html; charset=utf-8"
          }
        },
        "verdict": "allowed"
      }
    ],
    "robots": {
      "url": "https://www.greenleaf-journal.example/robots.txt",
      "status": 200,
      "found": true,
      "unavailable": false,
      "excerpt": "User-agent: *\nDisallow: /wp-admin/\nAllow: /wp-admin/admin-ajax.php\n\nUser-agent: GPTBot\nDisallow: /\n\nUser-agent: CCBot\nDisallow: /\n\nUser-agent: Bytespider\nDisallow: /\n\nUser-agent: Google-Extended\nDisallow: /\n\nSitemap: https://www.greenleaf-journal.example/sitemap_index.xml"
    },
    "directives": {
      "meta": [
        {
          "name": "robots",
          "content": "index, follow, noai, noimageai"
        }
      ],
      "x_robots_tag": [],
      "flags": {
        "noai": true,
        "noimageai": true,
        "noindex": false,
        "nosnippet": false
      }
    },
    "js": {
      "raw_words": 412,
      "rendered_words": 1860,
      "ratio": 0.22,
      "verdict": "js_dependent",
      "reason": ""
    },
    "llms": {
      "url": "https://www.greenleaf-journal.example/llms.txt",
      "status": 200,
      "found": true,
      "content_type": "text/html; charset=utf-8",
      "h1": "Greenleaf Journal",
      "summary": null,
      "sections": 3,
      "links": 18,
      "problems": [
        {
          "code": "no_summary",
          "detail": "No blockquote summary after the H1",
          "line": 2
        },
        {
          "code": "content_type",
          "detail": "Served as text/html; expected text/plain or text/markdown",
          "line": null
        },
        {
          "code": "bad_list_item",
          "detail": "Several links on one list line",
          "line": 14
        }
      ]
    },
    "sitemap": {
      "sitemaps": [
        {
          "url": "https://www.greenleaf-journal.example/sitemap_index.xml",
          "status": 200,
          "valid": true,
          "blocked_for": [
            "gptbot",
            "ccbot",
            "bytespider",
            "google-extended"
          ]
        },
        {
          "url": "https://www.greenleaf-journal.example/post-sitemap.xml",
          "status": 200,
          "valid": true,
          "blocked_for": [
            "gptbot",
            "ccbot",
            "bytespider",
            "google-extended"
          ]
        }
      ],
      "sampled": 20,
      "resolved": 19,
      "problems": [
        {
          "code": "blocked_for_ai",
          "detail": "robots.txt blocks 4 AI crawlers from the URLs this sitemap lists"
        }
      ]
    },
    "result_url": "https://approvalens.com/ai/aic_7Qm2xK9pLs"
  }
}

Değişiklikler

v1 · 2026-10-06İlk sürüm: siteler, kesintiler, raporlar, rapor özeti, YZ kontrolleri.
—Sunucu izleme uç noktaları, o özellik yayına girince buraya eklenecek.