SiteScan.top-API

Schnellstart

• Melden Sie sich an, öffnen Sie das Konto und den Tab „API“. Erstellen Sie einen Schlüssel und kopieren Sie ihn — er wird nur einmal angezeigt.
• Starten Sie einen Scan mit POST /scans und der Domain. Die Antwort ist 202 mit der ID des Scans.
• Fragen Sie GET /scans/{id} alle paar Sekunden ab, bis status done oder failed ist. Mit ?report=1 enthält die letzte Antwort den vollständigen Bericht.

Authentifizierung

Jede Anfrage außer /ping trägt einen Schlüssel in einem der Header: Authorization: Bearer <Schlüssel> oder X-API-Key: <Schlüssel>.

Schlüssel beginnen mit ssk_. Gespeichert wird nur ein Hash, ein verlorener Schlüssel lässt sich also nicht erneut anzeigen — widerrufen Sie ihn und erstellen Sie einen neuen. Ein Konto kann 5 Schlüssel haben.

Der Schlüssel ist der Zugang zum Konto: auf dem Server oder in CI-Secrets aufbewahren, nie in einer öffentlichen Webseite.

Tokens und Preise

Ein Scan kostet einen Token pro Seite, die der Scanner tatsächlich gelesen hat — so viel wie eine Prüfung aus dem Konto. Die Tokens werden abgebucht, wenn der Scan fertig ist.

Ein Scan, der fehlschlägt, die Zeit überschreitet oder von der Website blockiert wird, kostet nichts. Berichte, die Scan-Liste und das Konto zu lesen ist kostenlos.

Ein Scan braucht mindestens einen Token und liest nie mehr Seiten, als das Guthaben bezahlt. Tokens gibt es auf der Preisseite.

Limits

60 Anfragen pro Minute und Schlüssel. Jede Antwort trägt X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset, eine 429 zusätzlich Retry-After.

3 gleichzeitige Scans pro Konto. Ein zweiter Scan einer Domain, die schon gescannt wird, liefert den laufenden zurück, statt einen neuen zu starten.

pages ist 1 bis max_pages (wie viele der Server erlaubt, sagt GET /account), ohne Angabe 5.

Endpunkte

GET /ping

Ob die API läuft. Antwortet 503, wenn der Kontospeicher nicht verfügbar ist. Braucht keinen Schlüssel — diese Adresse fragt die Statusseite ab.

curl https://sitescan.top/api/v1/ping

GET /account

Das Konto hinter dem Schlüssel: Guthaben in Tokens und die geltenden Limits.

curl https://sitescan.top/api/v1/account \
  -H "Authorization: Bearer $SITESCAN_KEY"

POST /scans

Einen Scan starten. Antwortet 202, solange der Scanner arbeitet, oder 200, wenn er innerhalb der Anfrage fertig wurde.

curl -X POST https://sitescan.top/api/v1/scans \
  -H "Authorization: Bearer $SITESCAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "pages": 5}'

GET /scans/{id}

Ein Scan. 202, solange er läuft (mit Fortschritt), 200, sobald er done oder failed ist. Die Abfrage bringt zugleich einen hängenden Scan voran.

curl "https://sitescan.top/api/v1/scans/scn_4f1c9a2b7d3e8f60?report=1" \
  -H "Authorization: Bearer $SITESCAN_KEY"

GET /scans

Die 50 letzten Scans, die dieses Konto über die API gestartet hat, neueste zuerst.

curl https://sitescan.top/api/v1/scans \
  -H "Authorization: Bearer $SITESCAN_KEY"

GET /reports/{domain}

Der neueste gespeicherte Bericht für eine Domain, egal wer ihn gestartet hat. Kostenlos.

curl https://sitescan.top/api/v1/reports/example.com \
  -H "Authorization: Bearer $SITESCAN_KEY"

Scan-Status

running

Der Scan wartet oder läuft. progress.stage ist queued, crawl, audit oder score.

done

Der Bericht ist gespeichert; score, pages_read und tokens_charged sind gesetzt.

failed

Kein Bericht — der Grund steht in error (z. B. timeout oder blocked). Nichts wurde abgebucht.

Fehler

Fehler haben eine Form: {"error": {"code": "…", "message": "…"}}. Werten Sie code aus; message ist für Menschen.

key_required (HTTP 401)

Kein Schlüssel in der Anfrage.

key_invalid (HTTP 401)

Der Schlüssel ist falsch oder widerrufen.

insufficient_tokens (HTTP 402)

Das Guthaben ist leer — im Konto aufladen.

unknown_scan (HTTP 404)

Kein Scan mit dieser ID in diesem Konto.

unknown_report (HTTP 404)

Für diese Domain gibt es noch keinen gespeicherten Bericht.

unknown_endpoint (HTTP 404)

Diesen Endpunkt gibt es nicht.

method_not_allowed (HTTP 405)

Den Endpunkt gibt es, aber nicht mit dieser Methode.

invalid_domain (HTTP 422)

domain ist kein Domainname.

invalid_pages (HTTP 422)

pages liegt außerhalb des Bereichs.

rate_limited (HTTP 429)

Zu viele Anfragen in dieser Minute — Retry-After abwarten.

too_many_scans (HTTP 429)

In diesem Konto laufen bereits drei Scans.

store_unavailable (HTTP 503)

Ein Problem auf unserer Seite; später erneut versuchen.

Beispiele

curl + jq

export SITESCAN_KEY="ssk_…"

ID=$(curl -s -X POST https://sitescan.top/api/v1/scans \
  -H "Authorization: Bearer $SITESCAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}' | jq -r .scan.id)

while :; do
  SCAN=$(curl -s https://sitescan.top/api/v1/scans/$ID -H "Authorization: Bearer $SITESCAN_KEY")
  STATUS=$(echo "$SCAN" | jq -r .scan.status)
  [ "$STATUS" != "running" ] && break
  sleep 5
done
echo "$SCAN" | jq .scan

JavaScript

const KEY = process.env.SITESCAN_KEY;
const api = (path, init = {}) =>
  fetch("https://sitescan.top/api/v1" + path, {
    ...init,
    headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
  }).then((r) => r.json());

let { scan } = await api("/scans", { method: "POST", body: JSON.stringify({ domain: "example.com", pages: 5 }) });
while (scan.status === "running") {
  await new Promise((done) => setTimeout(done, 5000));
  ({ scan } = await api(`/scans/${scan.id}`));
}
console.log(scan.status, scan.score, scan.report_url);

Python

import os, time, requests

API = "https://sitescan.top/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SITESCAN_KEY']}"}

scan = requests.post(f"{API}/scans", json={"domain": "example.com", "pages": 5}, headers=HEADERS).json()["scan"]
while scan["status"] == "running":
    time.sleep(5)
    scan = requests.get(f"{API}/scans/{scan['id']}", headers=HEADERS).json()["scan"]

print(scan["status"], scan["score"], scan["report_url"])