Документация API

Базовый адрес API: https://cheburcheck.ru/api/v1. Проверка по спискам возвращает JSON, а сетевые сканеры передают результаты по мере готовности через Server-Sent Events (SSE).

# Авторизация

API-токены выдаются администратором по заявке. Чтобы получить токен для запросов к публичным сканерам, заполните форму заявки. При злоупотреблении токен может быть отозван.

Для GET /check и GET /status авторизация не требуется. Для GET /probe/<id> передайте API-токен в заголовке Authorization: Bearer <токен>. Для запроса к одному сканеру достаточно его токена в параметре token; API-токен в этом случае не требуется.

Храните API-токен на сервере или в секретах вашей системы автоматизации. Передавайте его в заголовке, а не в URL и не в публичном коде сайта. API-токен для сканеров не даёт доступ к административным методам.

# GET /check — проверка ресурса

GET /check?target=<цель> принимает домен, IPv4, IPv6, подсеть в формате CIDR или ASN (например, AS13335).

{
  "id": "<подписанный id>",
  "target": "example.com",
  "target_type": "Домен",
  "blocked": false,
  "ips": [
    "93.184.215.14"
  ],
  "reverse_lookup": [],
  "blocked_subnets": [],
  "cdn_providers": {},
  "geo": {
    "location": "США"
  },
  "complaints": []
}
		
			
			Копировать
		
	

Основные поля JSON-ответа:

• id — контекст для сканеров и обратной связи; может быть null.
• target, target_type — нормализованная цель и её тип.
• blocked, rkn_domain, blocked_subnets — результат проверки по спискам блокировок.
• ips, reverse_lookup, geo — адреса, обратные DNS-имена и данные о сети.
• cdn_providers — сети CDN по провайдерам; whitelist — найденное исключение.
• asn_info, subnet_size — дополнительные сведения для ASN и подсетей.
• complaints — дневные счётчики жалоб в виде объектов с полями date и count.

Необязательные поля могут отсутствовать или содержать null. Методика работы сканеров приведена в отдельной статье.

Поле id — подписанный контекст проверки со сроком действия 24 часа. Передавайте его целиком.

# GET /probe/<id> — сетевые сканеры

GET /probe/<id> возвращает поток text/event-stream. Сканеры доступны для доменов и отдельных IP-адресов. Подсети, ASN и специальные локальные адреса не поддерживаются.

Сначала выполните GET /check и подставьте поле id из ответа в URL запроса. Передайте API-токен в заголовке Authorization: Bearer <токен> и читайте события SSE до события done.

Лимиты API можно снять по запросу. Для этого напишите на support@cheburcheck.ru.

Необязательный параметр token позволяет выбрать конкретный сканер. Без выбора сканера используются доступные публичные сканеры.

Обрабатывайте именованные события:

• started — поля id, target, online_probes: начало запроса и число ожидаемых результатов.
• result — один ответ сканера. Сопоставляйте результаты по probe_id.
• done — поля id, response_count, online_probes: завершение ожидания. После него закройте соединение.

Сокращённый пример потока (показан один из двух результатов):

event: started
    data: {"id":"…","target":"example.com","online_probes":2}

    event: result
    data: {"job_id":"…","probe_id":"42","cached":false,"verdicts":["ok"],"host_results":[],"target_hop":null,"dpi_hop":null,"dns":null}

    event: done
    data: {"id":"…","status":"done","response_count":2,"online_probes":2}
		
			
			Копировать
		
	

В result также могут присутствовать region, provider, asn, cdn_unblocked, сведения о хостах в host_results, DNS в dns и прыжках в target_hop и dpi_hop. Поле cached: true означает повторное использование сохранённого измерения; по умолчанию кеш действует три часа.

Массив verdicts содержит значения ok, uncertain, cdn_block, sni_block, dns_spoofing, tspu_block или whitelist. Один сканер может вернуть несколько признаков.

Событие done приходит и при истечении времени ожидания, поэтому response_count может быть меньше online_probes.

# GET /credits — баланс кредитов

Передайте API-токен в заголовке Authorization: Bearer <токен>. Ответ {"credits":42} содержит текущий баланс этого токена. Запрос не расходует кредиты и работает при нулевом балансе. Отсутствующий, неверный, просроченный или отозванный токен возвращает 401.

# GET /status — статус сервиса

GET /status возвращает JSON с количеством доменов (domain_count) и IPv4-адресов (v4_count) в списках, временем последнего обновления (last_update) и версией сервиса (version). Авторизация не требуется.

{
  "domain_count": 1200000,
  "v4_count": 350000,
  "last_update": "2026-11-06T00:00:00Z",
  "version": "1.5.7"
}
		
			
			Копировать
		
	

# GET /healthcheck — готовность сервиса

GET /healthcheck возвращает текст OK с кодом 200, когда списки загружены. До загрузки списков возвращается код 500.

OK
		
			
			Копировать
		
	

# POST /feedback/<id>/<works> — обратная связь

POST /feedback/<id>/<works> отправляет обратную связь по проверке. Подставьте id из ответа GET /check, а вместо works передайте true, если ресурс работает, или false, если недоступен. При успехе возвращается код 200 без тела ответа.

# Ошибки и лимиты

До открытия SSE ошибки возвращаются как JSON с полями code и info. При отсутствии авторизации ответ 403 также содержит поле documentation_url со ссылкой на эту документацию.

• 400 — неподдерживаемая цель для сканеров, отключённая трассировка IP или неверные параметры.
• 401 — неверный или просроченный контекст id, неверный, просроченный или отозванный API-токен либо неверный заголовок авторизации.
• 403 — отсутствует авторизация для сканеров или целевой адрес запрещён.
• 404 — ресурс не найден при проверке или указанный сканер не существует.
• 429 — превышен лимит запросов. Уменьшите частоту и повторите запрос позже.
• 500, 503, 504 — ошибка сервиса, недоступность зависимостей или таймаут. Повторите запрос позже.

Для API действуют ограничения частоты запросов. Чтобы снять их, напишите на support@cheburcheck.ru.