API SiteScan.top

Запускайте проверки и получайте отчёты из своего кода: проверка в CI перед релизом, сводная панель по сайтам клиентов, оповещение при падении оценки. API работает на том же сканере, что и сайт, и оплачивается из того же баланса токенов.

Базовый адрес: https://sitescan.top/api/v1

Быстрый старт

Войдите, откройте личный кабинет, вкладку «API». Создайте ключ и скопируйте его — он показывается один раз.
Запустите скан запросом POST /scans с доменом. В ответ придёт 202 и id скана.
Раз в несколько секунд запрашивайте GET /scans/{id}, пока status не станет done или failed. С ?report=1 последний ответ вернёт полный отчёт.

Авторизация

Каждый запрос, кроме /ping, передаёт ключ в одном из заголовков: Authorization: Bearer <ключ> или X-API-Key: <ключ>.

Ключи начинаются с ssk_. Хранится только хэш ключа, поэтому потерянный ключ показать заново нельзя — отзовите его и создайте новый. На аккаунт — до 5 ключей.

Ключ и есть доступ к аккаунту: держите его на сервере или в секретах CI, но не в публичной веб-странице.

Токены и стоимость

Скан стоит один токен за каждую страницу, которую сканер действительно прочитал, — так же, как проверка из личного кабинета. Токены списываются, когда скан завершён.

Скан, который упал, не уложился во время или был заблокирован сайтом, ничего не стоит. Чтение отчётов, списка сканов и аккаунта бесплатно.

Для запуска нужен хотя бы один токен, и скан никогда не читает больше страниц, чем оплачивает баланс. Токены покупаются на странице «Цены».

Ограничения

60 запросов в минуту на ключ. Каждый ответ содержит X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset, ответ 429 — ещё и Retry-After.

До 3 сканов одновременно на аккаунт. Повторный запуск домена, который уже сканируется, вернёт текущий скан вместо нового.

pages — от 1 до max_pages (сколько разрешает сервер, скажет GET /account), по умолчанию 5.

Методы

GET /ping

Работает ли API. Отвечает 503, если хранилище аккаунтов недоступно. Ключ не нужен — именно этот адрес опрашивает страница статуса.

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

GET /account

Аккаунт, которому принадлежит ключ: баланс в токенах и действующие ограничения.

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

POST /scans

Запустить скан. Отвечает 202, пока сканер работает, или 200, если скан завершился в рамках запроса.

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}

Один скан. 202, пока идёт (с прогрессом), 200 — когда done или failed. Этот опрос заодно продвигает застрявший скан.

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

GET /scans

50 последних сканов, запущенных этим аккаунтом через API, новые сверху.

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

GET /reports/{domain}

Последний сохранённый отчёт по домену, кто бы его ни запускал. Бесплатно.

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

Статусы скана

running: Скан в очереди или идёт. progress.stage — queued, crawl, audit или score.
done: Отчёт сохранён, заполнены score, pages_read и tokens_charged.
failed: Отчёта нет, причина в error (например, timeout или blocked). Ничего не списано.

Ошибки

Ошибки приходят в одном формате: {"error": {"code": "…", "message": "…"}}. Ориентируйтесь на code, message — для людей.

key_required (HTTP 401): В запросе нет ключа.
key_invalid (HTTP 401): Ключ неверный или отозван.
insufficient_tokens (HTTP 402): Баланс пуст — пополните его в личном кабинете.
unknown_scan (HTTP 404): У этого аккаунта нет скана с таким id.
unknown_report (HTTP 404): По этому домену ещё нет сохранённого отчёта.
unknown_endpoint (HTTP 404): Такого метода нет.
method_not_allowed (HTTP 405): Метод есть, но не с этим HTTP-глаголом.
invalid_domain (HTTP 422): domain — не доменное имя.
invalid_pages (HTTP 422): pages вне допустимого диапазона.
rate_limited (HTTP 429): Слишком много запросов за минуту — подождите Retry-After.
too_many_scans (HTTP 429): У аккаунта уже идут три скана.
store_unavailable (HTTP 503): Проблема на нашей стороне, повторите позже.

Примеры

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