API

JSON API проверки доступности. Все эндпоинты — на этом же домене, без ключа для базового доступа.

English documentation follows the Russian one.

POST /api/check

Создаёт проверку и сразу возвращает объект проверки с флагом done.

curl -s https://checkhost.dev/api/check \
  -H 'Content-Type: application/json' \
  -d '{"url":"example.com","type":"http"}'

TCP-порт с API-ключом:

curl -s https://checkhost.dev/api/check \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: my-key' \
  -d '{"url":"example.com","type":"tcp","port":22}'

GET /api/check/<id>

Текущее состояние проверки. Пока done равно false, часть результатов находится в статусе pending.

{
  "id": "Yb3kQ9xLm2A",
  "target": "http://example.com",
  "type": "http",
  "port": null,
  "started": 1730000000.0,
  "finished": null,
  "done": false,
  "total": 45,
  "results": [
    {
      "cc": "DE", "country": "Germany", "city": "Frankfurt",
      "lat": 50.11, "lon": 8.68,
      "status": "ok", "code": 200, "ms": 412,
      "detail": null, "error": null, "error_code": null, "pending": false
    }
  ]
}

Статусы: pending — ещё проверяется, ok — успех, warn — ответ с ошибкой (HTTP 4xx/5xx, закрытый порт), fail — нет соединения. Поле detail содержит ответ, специфичный для типа: IP для DNS, порт для TCP, заголовок Server для info.

GET /api/nodes

Список узлов проверки: код страны, название, город, координаты.

GET /api/uptime

Раз в час сервис проверяет топ-100 популярных сайтов России, США и Европы со всех узлов. Сайт считается недоступным, если с ним не соединилось больше 50% узлов (поле down больше половины total). Ответ содержит время обхода, сводку по регионам и список сайтов с полями host, region, category, total, down, up, available, checked; сводка по отраслям — в categories. Если сайт недоступен дольше двух суток подряд, он исключается из трекера и попадает в список dropped. Параметр ?history=1 добавляет к каждому сайту поле history — до 48 точек [время, всего узлов, не ответило] для графиков. Публичная страница с графиками — /status.

Типы проверок

• http — HTTP/HTTPS GET через прокси узла, результат — код и время;
• ping — TCP-подключение к 80/443 через прокси (ICMP через HTTP-прокси недоступен);
• tcp — TCP CONNECT на указанный порт через прокси;
• udp — UDP-запрос с сервера сервиса (прокси-пул не передаёт UDP);
• dns — DNS-over-HTTPS через прокси: какой адрес вернёт резолвер из этой страны;
• info — HTTP-заголовки ответа с узлов (код и Server).

Ограничения

• Сайт: до 10 проверок в час с одного IP.
• API с заголовком X-API-Key: до 5 проверок в час на один ключ.
• Не более 4 проверок одновременно; результаты хранятся 2 часа.
• Локальные и служебные адреса заблокированы.

Ошибки

Ответ ошибки: {"error": "текст", "code": "код"}. Коды: url_required, bad_url, bad_scheme, bad_port, bad_port_range, blocked, rate_limit, busy, loading, bad_request, bad_id, not_found.

English

POST /api/check

Starts a check. Body: {"url": "example.com", "type": "http"}. type is one of http, ping, tcp, udp, dns, info. port (1–65535) is required for tcp and udp.

curl -s https://checkhost.dev/api/check \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: my-key' \
  -d '{"url":"example.com","type":"tcp","port":443}'

GET /api/check/<id>

Returns the current state. While done is false, some results are pending. Each result has cc, country, city, lat, lon, status (pending/ok/warn/fail), code, ms, detail, error_code.

GET /api/nodes

Returns the check nodes: country code and name, city, coordinates.

GET /api/uptime

Hourly sweep of the top-100 popular sites in Russia, the USA and Europe, checked from all nodes. A site is unavailable when more than 50% of the nodes cannot connect to it. Each site has host, region, category, total, down, up, available, checked; per-industry totals are in categories. A site unavailable for more than two days in a row is dropped from the tracker and listed under dropped. Add ?history=1 to include up to 48 hourly points [time, total, down] per site. The public status page is /status.

Limits and errors

• 10 checks per hour per IP; with an X-API-Key header — 5 checks per hour per key.
• At most 4 concurrent checks; results are kept for 2 hours.
• Errors: {"error": "...", "code": "..."} with codes url_required, bad_url, bad_scheme, bad_port, bad_port_range, blocked, rate_limit, busy, loading, bad_request, bad_id, not_found.