> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/ru/docs/response-format

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

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` результата инструмента.

#### Пример

```bash
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 заголовок не читают.

```bash
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/subdomains` | `max_age=2592000` |
| `skip_cache` | `/v1/status`, `/v1/tech`, `/v1/categorize`, `/v1/identity-assets`, `/v1/identity-resolution`, `/v1/url-intelligence`, `/v1/agent-readiness`, `/v1/robots` | `max_age=0` |
| `cache_skip` | `/v1/status` | `max_age=0` |
| `cache-skip` | `/v1/status` | `max_age=0` |
| `options.prefer_cache (body)` | `/v1/status/bulk` | `max_age=2592000` |
| `prefer_cache (body)` | `/v1/status/bulk` | `max_age=2592000` |
| `options.skip_cache (body)` | `/v1/status/bulk` | `max_age=0` |
| `options.cache_skip (body)` | `/v1/status/bulk` | `max_age=0` |
| `options.cache-skip (body)` | `/v1/status/bulk` | `max_age=0` |
| `refresh` | `/v1/ssl/deep-scan` | `max_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/history` | 50 | 100 |
| `GET /v1/dns/history` | 100 | 1000 |
| `GET /v1/subdomains` | 500 | 2000 |
| `GET /v1/certificates` | 100 | 1000 |
| `GET /v1/watchlist` | Весь список | 100 |
| `GET /v1/watchlist/expiring` | Весь список | 100 |
| `GET /v1/watchlist/available` | Весь список | 100 |
| `GET /v1/brand-monitor` | Весь список | 100 |
| `GET /v1/email/blacklist` | 1000 | 10000 |

#### Пример

```bash
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 или платформы без надежного способа проверки.

```json
{
  "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` вместо «не запаркован».
