Справочник разработчика

Формат ответа

DomScan API для анализа доменов: Все ответы представлены в JSON. Каждый результат домена содержит следующие общие поля:

Формат ответа

Все ответы представлены в JSON. Каждый результат домена содержит следующие общие поля:

  • domain - Полное доменное имя
  • available - Логический статус доступности
  • source - "rdap" or "cache"
  • checked_at - Метка времени в формате ISO 8601
  • error - Присутствует при возникновении ошибки

Метаданные ответа

Каждый ответ API включает идентификатор запроса и значение свежести данных. Если они доступны, заголовки ответа также показывают запрошенные, списанные, возвращённые и оставшиеся кредиты, а также ваш план ограничения частоты, лимит, оставшуюся ёмкость и политику. Значение свежести unknown означает, что свежесть данных для этого ответа установить не удалось. Это не означает, что данные актуальны.

Выбор полей и компактные ответы

Добавьте fields или compact в строку запроса любого GET или POST запроса, чтобы получить более компактный JSON-ответ. Оба параметра необязательны. В POST запросах они передаются в строке запроса, а не в теле. Ни один из них не меняет стоимость в кредитах.

Выбор полей

fields принимает пути через точку, разделённые запятыми, например fields=domain,classification.status,records.data. Если путь проходит через список, он применяется к каждому элементу. Элементы сохраняют свои позиции, а элемент без единого выбранного поля становится {}. Значение null на пути сохраняется как null.

Передавайте до 50 путей, каждый не более чем из 6 сегментов длиной от 1 до 64 букв, цифр или подчёркиваний. Любое другое значение возвращает 400 INVALID_PARAMETER до выполнения запроса, поэтому плата не списывается.

Пути, которые ничему в ответе не соответствуют, исключаются и перечисляются в заголовке ответа X-Fields-Ignored, не более 20 путей.

Компактные ответы

compact=true удаляет только перечисленное ниже и только на верхнем уровне ответа:

  • В объекте meta: served_by и ключи времени duration_ms, query_time_ms, total_ms, total_time_ms, latency_ms, generation_ms и check_duration_ms. Сам объект meta удаляется, если в нём больше ничего не остаётся.
  • warnings, caveats, notes и errors, когда это пустые списки.
  • request_id, когда он повторяет заголовок X-Request-Id.

Поля с данными, classification, вложенные объекты и элементы списков никогда не удаляются. Если переданы оба параметра, сначала выполняется compact, затем fields.

Преобразуются только успешные JSON-ответы. Ответы с ошибками, CSV, текстовые и потоковые ответы, а также оценки dry_run возвращаются без изменений. Преобразованные ответы отправляются без отступов.

При использовании Idempotency-Key параметры fields и compact входят в состав запроса. Повторный запрос с теми же значениями возвращает сохранённый преобразованный ответ. Повторное использование ключа с другими значениями возвращает 422 IDEMPOTENCY_KEY_REUSED.

Инструменты MCP принимают те же необязательные аргументы fields и compact. Пути, которые ничему не соответствуют, перечисляются в _meta.fields_ignored результата инструмента.

Пример

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/dns?domain=google.com&type=TXT&fields=domain,status,records.data,records.ttl,owner&compact=true"

X-Fields-Ignored: owner

{
  "domain": "google.com",
  "records": [
    {
      "data": "v=spf1 include:_spf.google.com ~all",
      "ttl": 300
    },
    {
      "data": "google-site-verification=abc123",
      "ttl": 300
    }
  ],
  "status": "success"
}

Ключи snake_case (naming)

Большинство ключей ответа уже записаны в snake_case, но некоторые эндпоинты возвращают часть ключей в camelCase, например registrarName в результатах по ценам, tldTier в факторах оценки и eventDate в событиях RDAP. Добавьте naming=snake в строку запроса или отправьте заголовок DomScan-Naming: snake, чтобы получить все эти ключи в snake_case. Без этого ответы сохраняют текущие ключи.

Ключ меняется, только если он начинается со строчной буквы, содержит только буквы и цифры и включает хотя бы одну заглавную букву. Перед каждым новым словом ставится знак подчёркивания, а ключ переводится в нижний регистр. Аббревиатуры остаются цельными, включая IPv4 и формы множественного числа вроде IPs: registrarName становится registrar_name, secureDNS становится secure_dns, ipv4Address становится ipv4_address, а nameserverIPs становится nameserver_ips.

Ключи, которые являются данными, а не именами полей, сохраняют точное написание, например типы DNS-записей (A и MX), оценки (A+), доменные имена, имена заголовков и названия технологий. Значения никогда не меняются, а вложенные объекты и списки преобразуются на всех уровнях.

Если в объекте уже есть имя в snake_case, например одновременно fooBar и foo_bar, то foo_bar сохраняет своё значение, а fooBar сохраняет исходное имя, поэтому ничего не теряется. Порядок ключей не меняется.

Параметр запроса имеет приоритет над заголовком, поэтому naming=default отключает выбор, сделанный через заголовок, для одного запроса. Допустимые значения: snake и default. Любое другое значение приводит к ответу 400 INVALID_PARAMETER до выполнения запроса, поэтому плата не списывается. Ответы содержат Vary: DomScan-Naming.

naming выполняется раньше compact и fields, поэтому пути в fields записывайте в snake_case, например fields=factors.tld_tier. Ответы с ошибками уже в snake_case и никогда не меняются, а стоимость в кредитах остаётся прежней.

При использовании Idempotency-Key выбор формата имён входит в состав запроса независимо от того, передан он параметром или заголовком, поэтому повторный запрос вернёт те же ключи.

Инструменты MCP принимают тот же необязательный аргумент naming. Вызовы MCP заголовок не читают.

curl -H "X-API-Key: $DOMSCAN_API_KEY" -H "DomScan-Naming: snake" "https://domscan.net/v1/value?domain=example.com&fields=domain,factors.tld_tier,factors.has_hyphens"

{
  "domain": "example.com",
  "factors": {
    "tld_tier": "premium",
    "has_hyphens": false
  }
}

Управление актуальностью данных (max_age)

Эндпоинты, которые могут отвечать по недавно проверенным данным, принимают max_age, то есть целое число секунд от 0 до 2592000 (30 дней). Данные старше max_age проверяются заново перед возвратом, а max_age=0 всегда запускает новую проверку. Без max_age каждый эндпоинт работает как обычно.

Каждый успешный ответ этих эндпоинтов содержит поле верхнего уровня cache_age_s: возраст использованных данных в секундах или 0, если данные проверены заново. То же значение передается в заголовке ответа X-Cache-Age. Если ответ содержит несколько элементов, например проверку доступности нескольких доменов, указывается возраст самого старого элемента, а у элементов, у которых уже было свое значение, сохраняется собственный cache_age_s.

max_age никогда не меняет классификацию результата. Результат, который не удалось подтвердить, остается unknown независимо от того, насколько он свежий, а недавние данные никогда не показываются как присутствующие или отсутствующие, если это не подтвердила исходная проверка.

max_age не меняет стоимость запроса. Новая проверка и ответ по недавним данным стоят одинаковое количество кредитов.

В /v1/status и /v1/status/bulk принудительные новые проверки (max_age=0) ограничены для каждого клиента, чтобы защитить реестры. При превышении лимита запрос обрабатывается так, будто max_age не передавался, а cache_age_s показывает возраст полученных данных. Значение max_age, которое не является целым числом от 0 до 2592000, возвращает 400 INVALID_PARAMETER до выполнения запроса, поэтому плата не списывается.

Эндпоинты, принимающие max_age: GET /v1/status, POST /v1/status/bulk, GET /v1/subdomains, GET /v1/certificates, GET /v1/tech, GET /v1/categorize, GET /v1/identity-assets, GET /v1/avatar, GET /v1/logo/:domain, GET /v1/brand, GET /v1/identity-resolution, GET /v1/url-intelligence, GET /v1/agent-readiness, GET /v1/robots, GET /v1/ssl/deep-scan

Прежние параметры кеша

Эти параметры продолжают работать и теперь считаются устаревшими псевдонимами max_age. Если вы передаете и max_age, приоритет у max_age.

ПараметрЭндпоинтыЭквивалент
prefer_cache/v1/status, /v1/subdomainsmax_age=2592000
skip_cache/v1/status, /v1/tech, /v1/categorize, /v1/identity-assets, /v1/identity-resolution, /v1/url-intelligence, /v1/agent-readiness, /v1/robotsmax_age=0
cache_skip/v1/statusmax_age=0
cache-skip/v1/statusmax_age=0
options.prefer_cache (body)/v1/status/bulkmax_age=2592000
prefer_cache (body)/v1/status/bulkmax_age=2592000
options.skip_cache (body)/v1/status/bulkmax_age=0
options.cache_skip (body)/v1/status/bulkmax_age=0
options.cache-skip (body)/v1/status/bulkmax_age=0
refresh/v1/ssl/deep-scanmax_age=0

В /v1/subdomains параметр prefer_cache также сохраняет поведение «только кеш»: если ничего еще не сохранено, запрос возвращает 202 без списания средств и запускает поиск в фоновом режиме.

Инструменты MCP для этих эндпоинтов принимают тот же необязательный аргумент max_age, а их результаты содержат cache_age_s.

Постраничная навигация (limit и cursor)

Эндпоинты, возвращающие длинные списки, принимают limit и cursor, а каждый ответ содержит has_more и next_cursor. Чтобы получить следующую страницу, повторите запрос, передав в cursor значение next_cursor. На последней странице has_more равно false, а next_cursor равно null.

Без limit каждый эндпоинт возвращает прежнее количество элементов, поэтому существующие запросы не меняются. Значение limit можно менять от страницы к странице.

Курсоры непрозрачны и подписаны. Курсор работает только для аккаунта, который его получил, и только для того же запроса, например с тем же доменом и теми же фильтрами. Курсор, который был изменен, принадлежит другому аккаунту или передан с другими фильтрами, возвращает 400 INVALID_CURSOR.

Страницы следуют в стабильном порядке, поэтому элементы, добавленные или удаленные между запросами, не повторяются и не пропускаются. В эндпоинтах истории сводные поля описывают элементы текущей страницы.

Каждая страница является обычным запросом и стоит столько же кредитов, сколько обычно стоит эндпоинт, точно так же как раньше запрос с limit. Бесплатные эндпоинты остаются бесплатными.

Прежние параметры продолжают работать: offset в /v1/email/blacklist и числовой pagination.next_cursor в /v1/certificates.

ЭндпоинтРазмер страницы по умолчаниюМаксимальный limit
GET /v1/whois/history50100
GET /v1/dns/history1001000
GET /v1/subdomains5002000
GET /v1/certificates1001000
GET /v1/watchlistВесь список100
GET /v1/watchlist/expiringВесь список100
GET /v1/watchlist/availableВесь список100
GET /v1/brand-monitorВесь список100
GET /v1/email/blacklist100010000

Пример

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/whois/history?domain=example.com&limit=20"

{
  "domain": "example.com",
  "snapshots": [
    "..."
  ],
  "has_more": true,
  "next_cursor": "eyJvIjoi..."
}

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/whois/history?domain=example.com&limit=20&cursor=eyJvIjoi..."

Статус классификации

Эндпоинты, которые сообщают, существует ли что-либо (регистрация доменов, имена в соцсетях, DNS-записи и записи аутентификации почты, security.txt, robots.txt, карты сайта, заголовки безопасности, парковка, регистрации тайпосквоттинга и SSL-сертификаты), добавляют объект classification рядом с существующими полями. Существующие поля сохраняют названия и смысл.

  • status - present (есть), absent (нет) или unknown (неизвестно). Значения present и absent возвращаются только тогда, когда проверка дала точное и надежное подтверждение.
  • reason - Возвращается только при статусе unknown. Объясняет, почему определенный ответ получить не удалось.
  • evidence - Откуда получен ответ: source, method, observed_at и необязательное поле detail, например http_404 или nxdomain.
  • checked_at - Когда DomScan сформировал классификацию. Для кешированных результатов evidence.observed_at указывает более раннее время.

Причины unknown

  • blocked - Цель отказала в доступе, например ответом HTTP 401, 403 или проверкой на бота.
  • rate_limited - Цель или реестр попросили нас снизить частоту запросов, например ответом HTTP 429.
  • timeout - Проверка не завершилась в отведенное время.
  • ambiguous - Ответ пришел, но он не доказал ни наличие, ни отсутствие, например неожиданный код состояния или некорректная запись.
  • upstream_error - Источник данных дал сбой, например из-за ошибки DNS-сервера или ответа HTTP 5xx.
  • unsupported - Эта проверка недоступна для введенных данных, например для неподдерживаемого TLD или платформы без надежного способа проверки.
{
  "classification": {
    "status": "unknown",
    "reason": "rate_limited",
    "evidence": {
      "source": "rdap",
      "method": "rdap_lookup",
      "observed_at": "2026-10-10T09:30:00.000Z",
      "detail": "http_429"
    },
    "checked_at": "2026-10-10T09:30:00.000Z"
  }
}
Заблокированная, ограниченная по частоте, прерванная по таймауту или неудачная проверка никогда не сообщается как absent. Воспринимайте unknown как «повторите позже», а не «не существует», и никогда не считайте отсутствие доказательством того, что имя можно занять.

Баллы и оценки при неизвестных проверках

Баллы никогда не считают неизвестную проверку отсутствующей. Балл безопасности DNS и оценка аутентификации почты не учитывают неизвестные проверки, указывают их в checks_unknown и задают score_confidence значение partial. Если все проверки неизвестны, балл и оценка равны null. Оценка и балл SSL равны null, а grade_reason получает значение certificate_not_retrieved, если не удалось прочитать сертификат, а балл репутации сообщает неизвестную парковку как null вместо «не запаркован».