/yandex-webmaster

name: yandex-webmaster
description: "[RU: Яндекс.Вебмастер API — поисковые запросы, индексация, переобход URL, sitemap] Yandex.Webmaster REST API v4 — OAuth 2.0, popular/history search queries, recrawl with daily quota, sitemap CRUD, diagnostics, host verification. Use when: yandex webmaster, яндекс вебмастер, webmaster api, api.webmaster.yandex.net, /v4/user, host_id, recrawl, переобход url, popular search queries, TOTAL_SHOWS, AVG_SHOW_POSITION, sitemap api, OAuth Яндекс, верификация прав, диагностика, индексация. SKIP: Wordstat frequency (→mutagen); SERP positions (→xmlstock); Google Search Console (→google-search-console); traffic (→yandex-metrica); ads (→yandex-direct)."
stacks:
  - yandex-webmaster
  - ru-seo
  - python
  - nodejs
tags:
  - seo
  - ru
  - yandex
  - search-console
  - indexing
  - sitemap
  - oauth
source: vechkasov-global-skills
risk: high-stakes

<!-- versions:start --> <!-- versions:end -->

Usage

Loaded automatically when the description matches the active task. Read only the section you need, then follow the link to the relevant reference file.

Use this skill when

• Pulling search query stats (shows, clicks, avg position, CTR) — `search-queries/popular` or `search-queries/all/history`
• Monitoring indexing dynamics — `indexing/history`, `indexing/samples`, `indexing/insearch/history`
• Submitting URLs to recrawl with daily-quota awareness — `POST recrawl/queue` + `GET recrawl/quota`
• Managing sitemaps: list, add user sitemaps, track processing errors — `sitemaps`, `user-added-sitemaps`
• Site diagnostics with severity (FATAL/CRITICAL/POSSIBLE_PROBLEM/RECOMMENDATION) — `diagnostics`
• External/internal link audit — `links/external/samples`, `links/internal/samples`
• Host ownership verification (DNS, HTML_FILE, META_TAG, TXT_FILE) — `verification`
• SQI history, search events (pages added/removed) — `sqi-history`, `search-events`
• Building a Python (`httpx`) / Node.js (`undici`) OAuth client with refresh-token, `task_id` persistence, recrawl daily quota
• Registering an OAuth app on `oauth.yandex.com` and obtaining a long-lived token

Do not use this skill when

• Wordstat / general phrase frequency — Webmaster reports shows that already happened on your site, not query volume. Use `mutagen` (cascade)
• Generic SERP position tracking for arbitrary keywords — Webmaster only covers verified hosts. Use `xmlstock` (cascade)
• Google Search Console / Bing Webmaster — different provider. Use `google-search-console` (cascade)
• Yandex.Metrica (behavior, traffic sources, conversions) — separate product. Use `yandex-metrica` (cascade)
• Yandex.Direct (ad campaigns, bids, budgets) — separate API. Use `yandex-direct` (cascade)
• Custom SERP scraping bypassing the API — `xmlstock` or your own scraper via `proxy6`
• Downstream runtime (HTTP client, DB, cache) — use `httpx`, `nodejs`, `postgresql`, `redis`

Purpose

Yandex.Webmaster API v4 (`https://api.webmaster.yandex.net/v4/`) — official REST interface for managing sites in Yandex.Webmaster: search analytics (what users searched and clicked), indexing, page recrawl, problem diagnostics, sitemaps, links, ownership verification. Auth is OAuth 2.0 with `Authorization: OAuth <token>` header.

This skill is **high-stakes** because:

1. **Recrawl daily quota silently exhausts.** Each `POST /recrawl/queue` spends 1 unit; a batch of 5000 URLs without a pre-check hits 429 `QUOTA_EXCEEDED` after ~N successful posts. Duplicate URL returns 409 `URL_ALREADY_ADDED` (no quota spent, but trips batch logic). Quota varies with SQI / site type; **always** call `GET /recrawl/quota` first. 2. **OAuth token is short-lived by default.** Without explicitly requesting long-lived tokens in the app settings, the token expires ~1 year from last use; tokens with explicit `expires_in` expire quickly. Refresh logic is mandatory. 3. **`host_id` is not a domain.** It is an internal id like `https:example.com:443` (colon-separated) — never guess; fetch from `GET /v4/user/{user-id}/hosts` and persist. 4. **Date-range retention is not documented but bounded.** Detailed search-query data is retained ~90 days. Older ranges return truncated payloads silently. For long history — accumulate locally. 5. **Unverified site (`HOST_NOT_VERIFIED`)** returns 404 on most endpoints. Filter `verified=true` before analytics calls. 6. **Rate limit on 429** is not publicly documented as a number. Strategy: exponential backoff + Retry-After-aware + concurrency ≤ 5-10 per host. 7. **`HOSTS_LIMIT_EXCEEDED`** per user (historically ~1703) — verify before bulk adds. 8. **Sitemap add is idempotent by URL**: re-POST same URL → 409 `SITEMAP_ALREADY_ADDED` — catch and treat as success.

The skill owns provider domain knowledge: v4 endpoints, OAuth lifecycle, recrawl quota semantics, search-query indicators, diagnostics enums, sitemap flow, error table. HTTP transport itself belongs to `httpx` / `nodejs`.

End-to-end API Workflow

> Full step-by-step API interaction: **[references/workflow.md](references/workflow.md)** — bootstrap, host verification, sitemap submission, search analytics, indexing & recrawl, diagnostics, links, daily ETL pattern. Each step includes HTTP method + URL template, request/response shape, error paths, curl + Python snippets.

Quick map of the workflow file:

| Stage | What | |---|---| | 1. Bootstrap | OAuth app → scopes → token → `user_id` → list hosts | | 2. Host verification | Add host → choose verifier (DNS/HTML_FILE/META_TAG/TXT_FILE) → poll state | | 3. Sitemap management | Submit user-added sitemap → poll processing → handle errors | | 4. Search analytics | Pull popular queries → query history → handle 90-day retention | | 5. Indexing & recrawl | Read indexing history → check quota → submit URL → poll task | | 6. Diagnostics | Pull problems → classify by severity → wire to monitoring | | 7. Links | External/internal samples → paginate | | 8. Daily ETL | Cron / BullMQ → persist to Postgres → dedupe → alert on quota |

Capa