# Разведка сайта

> POST /v1/crawl/probe: знаком ли сайт, как устроен его каталог и сколько примерно страниц займёт обход — до запуска и бесплатно

Источник: https://docs.parreq.com/crawl-probe/

Перед тем как заказывать двести страниц, полезно знать, что сайт вообще
открывается с наших адресов, что словарь понимает его устройство и сколько в
каталоге разделов. `POST /v1/crawl/probe` отвечает на это за один запрос и не
стоит ни кредита.

```bash
curl -X POST https://api.parreq.com/v1/crawl/probe \
  -H "Authorization: Bearer pr_ВАШКЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://shop.example/catalog/"}'
```

`url` — единственный параметр. Знакомый сайт отвечает из базы знаний
мгновенно; новый разведывается словарём за три-четыре захода: стартовая
страница и, если это оглавление, до трёх этажей вниз до первого списка с
ценами. Языковая модель не участвует.

## Ответ

```json
{
  "ok": true,
  "reachable": true,
  "understood": true,
  "note": "список товаров на 2-м этаже: 24 плитки с ценой",
  "knowledge": {
    "host": "shop.example",
    "known": true,
    "status": "warmed",
    "cms": "bitrix",
    "start_kind": "sections",
    "sections": 37,
    "levels": 2,
    "fields": ["listing", "price"],
    "runs": 0,
    "without_model": null,
    "disputed": 0
  },
  "structure": {
    "start_url": "https://shop.example/catalog/",
    "start_kind": "sections",
    "section_shapes": ["/catalog/<*>/", "/catalog/<*>/<*>/"],
    "card_shapes": ["/catalog/<*>/<*>/<*>/"],
    "levels": 2,
    "sections": 37,
    "listing_url": "https://shop.example/catalog/kraska/emal/",
    "pagination": "пагинация есть",
    "cms": "bitrix"
  },
  "estimate": { "sections": 37, "levels": 2, "pages_guess": 222, "known": true },
  "credits": 0
}
```

- **`ok`** (`boolean`):
  Разведка состоялась. `false` — сайт не открылся или закрыт для обхода;
  причина в `note`.

- **`reachable`** (`boolean`):
  Стартовая страница открылась с наших адресов.

- **`understood`** (`boolean`):
  Словарь понял устройство: нашёл формы адресов разделов или карточек. Если
  `false`, обход всё равно можно запускать — устройство будет разбирать
  карта сайта или модель, — но оценка объёма будет грубее. Поле есть только у
  свежей разведки; у знакомого сайта его заменяет `knowledge.status`.

- **`note`** (`string`):
  Что увидела разведка, человеческим языком: «старт — список товаров»,
  «список товаров на 2-м этаже», «оглавление есть, до списка товаров не
  спустились», «стартовая страница не открылась».

- **`knowledge`** (`object`):
  Карточка сайта из [базы знаний](https://docs.parreq.com/crawl-catalog#база-знаний): знаком ли
  (`known`), состояние (`new`, `warmed`, `learned`, `blocked`), опознанная
  CMS, вид стартовой страницы, число разделов и этажей, подтверждённые поля,
  сколько прогонов было (`runs`), какая доля страниц в последнем прогоне
  разобрана без модели (`without_model`), сколько спорных страниц
  (`disputed`).

- **`structure`** (`object`):
  Устройство с учётом ручных правок: стартовый адрес и его вид, формы адресов
  разделов (`section_shapes`) и карточек (`card_shapes`), где `<*>` — любой
  кусок пути, число этажей до списка (`levels`), адрес найденного списка,
  есть ли у него пагинация, CMS.

- **`estimate`** (`object`):
  Оценка объёма: `pages_guess` — сколько примерно страниц у каталога, по
  числу разделов и этажей. Грубо, но до запуска лучше грубая цифра, чем
  никакой: раздел на одном этаже — это список из одной-трёх страниц плюс
  карточки.

- **`credits`** (`integer`):
  Всегда `0`.

## Сайт не открылся

```json
{ "ok": false, "reachable": false, "note": "стартовая страница не открылась", "credits": 0 }
```

Обычные причины — защита от ботов на входе или сайт, который отвечает только
из своей страны. Запускать обход по такому адресу не стоит: он закончится
отказом `recon_failed`. В [кабинете](https://docs.parreq.com/crawler-cabinet) такой сайт уходит на
модерацию, и когда его откроют, вам придёт письмо.

Сайт, закрытый по решению модерации, приходит с `ok: false` и записью
`moderation` — причина в ней. Обход по нему отклоняется до старта кодом
`site_blocked`.

## Зачем это агенту

Для ИИ-агента разведка — первый шаг сценария: `parreq_site_probe` → `parreq_crawl` →
`parreq_crawl_status` → `parreq_crawl_rows`. По `estimate.pages_guess` агент
выбирает `pages`, по `understood` — стоит ли запускать вообще, по
`knowledge.known` — будет ли обход дешевле за счёт памяти сайта.
См. [MCP](https://docs.parreq.com/mcp#обход-каталога-агентом).

> **Примечание.**
>   Разведка — это и прогрев: её результат записывается в базу знаний, и обход,
>   запущенный следом, разведку не повторяет. Прогреть сайт заранее, чтобы
>   ночной прогон по расписанию начался сразу с обхода, — нормальная практика.