API SiteScan.top

Szybki start

• Zaloguj się, otwórz panel konta i kartę „API”. Utwórz klucz i skopiuj go — jest pokazywany tylko raz.
• Uruchom skan przez POST /scans z domeną. Odpowiedź to 202 z id skanu.
• Co kilka sekund wywołuj GET /scans/{id}, aż status będzie done lub failed. Z ?report=1 ostatnia odpowiedź zawiera pełny raport.

Uwierzytelnianie

Każde żądanie poza /ping przesyła klucz w jednym z nagłówków: Authorization: Bearer <klucz> lub X-API-Key: <klucz>.

Klucze zaczynają się od ssk_. Przechowywany jest tylko skrót klucza, więc zgubionego klucza nie da się pokazać ponownie — unieważnij go i utwórz nowy. Konto może mieć 5 kluczy.

Klucz to dostęp do konta: trzymaj go na serwerze lub w sekretach CI, nigdy na publicznej stronie.

Tokeny i cena

Skan kosztuje jeden token za każdą stronę, którą skaner faktycznie odczytał — tyle samo co test z panelu konta. Tokeny są pobierane po zakończeniu skanu.

Skan, który się nie powiódł, przekroczył czas lub został zablokowany przez witrynę, nic nie kosztuje. Odczyt raportów, listy skanów i konta jest bezpłatny.

Skan wymaga co najmniej jednego tokenu i nigdy nie czyta więcej stron, niż pokrywa saldo. Tokeny kupuje się na stronie Cennik.

Limity

60 żądań na minutę na klucz. Każda odpowiedź zawiera X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset, a 429 także Retry-After.

3 skany naraz na konto. Ponowne uruchomienie domeny, która jest już skanowana, zwraca bieżący skan zamiast nowego.

pages to od 1 do max_pages (ile pozwala serwer, mówi GET /account), domyślnie 5.

Endpointy

GET /ping

Czy API działa. Zwraca 503, gdy magazyn kont jest niedostępny. Nie wymaga klucza — ten adres odpytuje strona statusu.

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

GET /account

Konto, do którego należy klucz: saldo w tokenach i obowiązujące limity.

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

POST /scans

Uruchom skan. Zwraca 202, gdy skaner pracuje, lub 200, gdy skan zakończył się w ramach żądania.

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}

Jeden skan. 202 w trakcie (z postępem), 200 po done lub failed. To odpytywanie popycha też zawieszony skan.

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

GET /scans

50 ostatnich skanów uruchomionych przez to konto przez API, od najnowszych.

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

GET /reports/{domain}

Ostatni zapisany raport dla domeny, niezależnie od tego, kto go uruchomił. Bezpłatnie.

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

Statusy skanu

running

Skan czeka w kolejce lub trwa. progress.stage to queued, crawl, audit lub score.

done

Raport zapisany; uzupełnione są score, pages_read i tokens_charged.

failed

Brak raportu — przyczyna w error (np. timeout lub blocked). Nic nie pobrano.

Błędy

Błędy mają jeden format: {"error": {"code": "…", "message": "…"}}. Rozróżniaj po code; message jest dla ludzi.

key_required (HTTP 401)

Brak klucza w żądaniu.

key_invalid (HTTP 401)

Klucz jest błędny lub unieważniony.

insufficient_tokens (HTTP 402)

Saldo jest puste — doładuj je w panelu konta.

unknown_scan (HTTP 404)

To konto nie ma skanu o tym id.

unknown_report (HTTP 404)

Dla tej domeny nie ma jeszcze zapisanego raportu.

unknown_endpoint (HTTP 404)

Nie ma takiego endpointu.

method_not_allowed (HTTP 405)

Endpoint istnieje, ale nie z tą metodą.

invalid_domain (HTTP 422)

domain nie jest nazwą domeny.

invalid_pages (HTTP 422)

pages jest poza zakresem.

rate_limited (HTTP 429)

Za dużo żądań w tej minucie — odczekaj Retry-After.

too_many_scans (HTTP 429)

Na tym koncie trwają już trzy skany.

store_unavailable (HTTP 503)

Problem po naszej stronie; spróbuj później.

Przykłady

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"])