Показывает, подключён ли Яндекс Вебмастер: есть ли токен, откуда он взят (переменная окружения YANDEX_OAUTH_TOKEN или сохранённый вход), когда истекает и где лежит файл с сохранёнными данными. Ничего не отправляет в сеть и не показывает сам токен. Вызовите это, если инструменты Вебмастера отвечают, что подключение не настроено.

Первый шаг подключения Яндекс Вебмастера без правки конфигурации и без перезапуска клиента. Возвращает ссылку на страницу Яндекс OAuth. Покажите ссылку пользователю целиком и попросите: открыть её в браузере под аккаунтом, которому в Вебмастере видны нужные сайты, подтвердить доступ и прислать показанный код подтверждения. Полученный код передайте в finish_login. Код действует 10 минут. Сам по себе код бесполезен для постороннего: обменять его может только этот сервер.

Второй шаг подключения: обменивает код подтверждения из start_login на токен доступа, сохраняет его в файл только для владельца (0600) и сразу проверяет живым запросом к Вебмастеру. После успеха остальные инструменты работают немедленно — перезапускать клиент не нужно. Код одноразовый и живёт 10 минут: если он не принят, вызовите start_login заново и попросите свежий.

Удаляет сохранённый токен Вебмастера с диска. Токен, заданный переменной окружения YANDEX_OAUTH_TOKEN, не трогает — его нужно убирать из конфигурации клиента вручную. Доступ, выданный приложению, остаётся активным на стороне Яндекса: отозвать его можно в Яндекс ID.

Возвращает идентификатор пользователя (user_id) — владельца OAuth-токена: {"user_id": число}. Сервер подставляет user_id во все остальные вызовы автоматически, так что обычно этот инструмент нужен только для диагностики (например, чтобы задать YANDEX_USER_ID) или для путей raw_request.

Возвращает список сайтов пользователя в Яндекс Вебмастере: массив hosts с полями host_id (идентификатор вида «https:example.com:443» — он нужен всем остальным инструментам), ascii_host_url/unicode_host_url, verified (подтверждены ли права) и main_mirror (главное зеркало, если сайт — не главное). С этого инструмента стоит начинать любую работу с Вебмастером.

Добавляет сайт в список пользователя в Яндекс Вебмастере. Возвращает {"host_id": строка}. После добавления права на сайт нужно подтвердить (get_verification_status → start_verification). Ошибки: 409 HOST_ALREADY_ADDED — сайт уже в списке; 403 HOSTS_LIMIT_EXCEEDED — превышен лимит сайтов.

Возвращает сводную статистику сайта: sqi (ИКС — индекс качества сайта), searchable_pages_count (страницы в поиске), excluded_pages_count (исключённые страницы) и site_problems — число проблем по категориям FATAL/CRITICAL/POSSIBLE_PROBLEM/RECOMMENDATION. Требует подтверждённых прав на сайт.

Возвращает состояние подтверждения прав на сайт: verification_state (NONE/VERIFIED/IN_PROGRESS/VERIFICATION_FAILED/INTERNAL_ERROR), verification_type, verification_uin — код UIN, который нужно разместить на сайте перед запуском start_verification, applicable_verifiers (доступные способы), latest_verification_time и fail_info при неудаче.

Запускает проверку прав на сайт выбранным способом. Перед вызовом разместите UIN-код из get_verification_status: dns — TXT-запись «yandex-verification: »; html_file — файл yandex_.html в корне сайта; meta_tag — на главной. Ответ — как у get_verification_status (verification_state обычно IN_PROGRESS). Ошибка 409 VERIFICATION_ALREADY_IN_PROGRESS — проверка уже идёт.

Возвращает диагностику сайта — объект problems, где ключ — тип проблемы, а значение — {severity: FATAL/CRITICAL/POSSIBLE_PROBLEM/RECOMMENDATION, state: PRESENT/ABSENT/UNDEFINED, last_state_update}. Показывает, что именно Вебмастер считает проблемой сайта прямо сейчас. Требует подтверждённых прав на сайт.

Возвращает ТОП поисковых запросов сайта за период: queries — массив {query_id, query_text, indicators: {TOTAL_SHOWS, TOTAL_CLICKS, AVG_SHOW_POSITION, AVG_CLICK_POSITION}}, плюс date_from/date_to и count. В топ попадает до 3000 запросов за последнюю неделю, выдача — до 500 за раз (листайте offset/limit). По умолчанию период — последняя неделя. Требует подтверждённых прав; 404 HOST_NOT_INDEXED — сайт ещё не проиндексирован.

Возвращает историю суммарных показателей по ВСЕМ поисковым запросам сайта: indicators — объект, где ключ — показатель (TOTAL_SHOWS и т.д.), значение — массив точек {date, value}. Подходит для динамики видимости сайта: показы, клики и средние позиции по датам. По умолчанию период — последняя неделя. Требует подтверждённых прав на сайт.

Возвращает историю обхода сайта роботом: indicators — объект с массивами точек {date, value} по ключам HTTP_2XX, HTTP_3XX, HTTP_4XX, HTTP_5XX и OTHER (неподдерживаемый код или ошибка соединения). Показывает, сколько страниц робот загрузил и с какими кодами. По умолчанию — данные за текущий день; период задаётся date_from/date_to. Требует подтверждённых прав на сайт.

Отправляет страницу сайта в очередь на переобход роботом («Переобход страниц»). Возвращает {task_id: UUID, quota_remainder: остаток суточной квоты} со статусом 202. Квота на сайт суточная и зависит от сайта — показывайте пользователю quota_remainder. Ошибки: 400 INVALID_URL — URL не принадлежит сайту или некорректен; 409 URL_ALREADY_ADDED — страница уже в очереди; 429 QUOTA_EXCEEDED — суточная квота исчерпана, попробуйте завтра.

Возвращает отслеживаемые «важные страницы» сайта: urls — массив {url, update_date, change_indicators (что изменилось: INDEXING_HTTP_CODE/SEARCH_STATUS/TITLE/DESCRIPTION), indexing_status {status, http_code, access_date} и search_status {title, description, searchable, excluded_url_status, target_url, ...}}. Список страниц настраивается в интерфейсе Вебмастера. Требует подтверждённых прав на сайт.

Возвращает sitemap-файлы сайта, известные роботу: sitemaps — массив {sitemap_id, sitemap_url, last_access_date, errors_count, urls_count, children_count, sources (ROBOTS_TXT/WEBMASTER/INDEX_SITEMAP), sitemap_type (SITEMAP/INDEX_SITEMAP)}. Пагинация курсором: передайте в from последний sitemap_id предыдущей страницы; дерево индексных sitemap обходится через parent_id. Требует подтверждённых прав на сайт.

Добавляет sitemap-файл вручную (аналог раздела «Файлы Sitemap» в интерфейсе Вебмастера). Возвращает {"sitemap_id": строка} со статусом 201. Ошибка 409 SITEMAP_ALREADY_ADDED — такой sitemap уже добавлен. Требует подтверждённых прав на сайт.

Возвращает примеры внешних ссылок на сайт: count — общее число ссылок (int64, может прийти строкой) и links — массив {source_url (откуда ссылаются), destination_url (куда), discovery_date, source_last_access_date}. Листайте offset/limit. Требует подтверждённых прав на сайт.

Прямой вызов любого пути Yandex Webmaster API v4 — для эндпоинтов без отдельного инструмента (информация о sitemap, квота переобхода GET user/{user-id}/hosts/{host-id}/recrawl/quota, статус задачи переобхода, владельцы сайта, удаление сайта/sitemap и т.п.). Путь указывается относительно /v4, напр. «user/{user-id}/hosts» — плейсхолдер {user-id} сервер подставит сам. Query-параметры можно включить прямо в path («...?limit=20»). body отправляется как JSON и используется только с POST. ВНИМАНИЕ: DELETE удаляет безвозвратно.