Yandex Webmaster

<!-- 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 — 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:

Capabilities

OAuth & authentication

Register an app on oauth.yandex.com with scopes webmaster:hostinfo, webmaster:verify. Authorization Code flow: https://oauth.yandex.com/authorize?response_type=code&client_id=... → exchange at https://oauth.yandex.com/token (form grant_type=authorization_code&code=...&client_id=...&client_secret=...). Response: access_token, refresh_token, expires_in, token_type=bearer. Use header Authorization: OAuth <access_token> (literal word OAuth, not Bearer). Refresh with grant_type=refresh_token.

Full reference: references/setup.md

Hosts & verification

GET /v4/user → user_id. GET /v4/user/{user-id}/hosts → array with host_id, ascii_host_url, unicode_host_url, verified, main_mirror, host_data_status (NOT_INDEXED / NOT_LOADED / OK). POST /v4/user/{user-id}/hosts body {"host_url": "..."} → 201. DELETE /v4/user/{user-id}/hosts/{host-id}. Verification: GET .../verification (state), POST .../verification?verification_type={DNS|HTML_FILE|META_TAG|TXT_FILE} (start). States: NONE, IN_PROGRESS, VERIFIED, VERIFICATION_FAILED, INTERNAL_ERROR.

Full reference: references/hosts-and-sitemaps.md

Search queries analytics

GET .../search-queries/popular?order_by={TOTAL_SHOWS|TOTAL_CLICKS}&query_indicator=...&device_type_indicator=...&date_from=...&date_to=...&offset=...&limit=... — TOP-3000 queries for last week by default, page up to 500. Indicators: TOTAL_SHOWS, TOTAL_CLICKS, AVG_SHOW_POSITION, AVG_CLICK_POSITION. Device: ALL (default), DESKTOP, MOBILE, TABLET, MOBILE_AND_TABLET. Single query history: .../search-queries/{query-id}/history. All-queries aggregated history: .../search-queries/all/history. query_id comes from popular response.

Full reference: references/search-queries.md

Indexing statistics

GET .../indexing/history?date_from=...&date_to=...&indexing_indicators=... — page-load dynamics split by HTTP code (HTTP_2XX, HTTP_3XX, HTTP_4XX, HTTP_5XX, OTHER). .../indexing/samples — sample loaded pages. .../indexing/insearch/history — pages in search; .../indexing/insearch/samples — sample searchable pages. .../search-events/history + .../search-events/samples — added/removed from search. Indicators: SEARCHABLE, DOWNLOADED, EXCLUDED, FAILED_TO_DOWNLOAD.

Full reference: references/indexing.md

Recrawl URL queue (daily quota, batch)

GET .../recrawl/quota → {daily_quota, quota_remainder}. Always check before batches. POST .../recrawl/queue body {"url": "..."} → 202 {task_id, quota_remainder}. Each POST = 1 quota unit. Duplicate → 409 URL_ALREADY_ADDED (no quota spent). GET .../recrawl/queue?offset=&limit=&date_from=&date_to= — task list. GET .../recrawl/queue/{task-id} → {task_id, url, added_time, state}. State: IN_PROGRESS, DONE, FAILED. For idempotency: persist URL → task_id mapping; do not re-POST.

Full reference: references/indexing.md

Sitemap management

GET .../sitemaps?limit=&from= — all sitemaps discovered by the bot, with sources (ROBOTS_TXT, WEBMASTER, INDEX_SITEMAP) and sitemap_type. Fields: sitemap_id, sitemap_url, last_access_date, errors_count, urls_count, children_count. GET .../sitemaps/{sitemap-id} — one. GET .../user-added-sitemaps — user-added only. POST .../user-added-sitemaps body {"url": "..."} → 201 {sitemap_id}. DELETE .../user-added-sitemaps/{sitemap-id}. Duplicate → 409 SITEMAP_ALREADY_ADDED (catch, treat as success).

Full reference: references/hosts-and-sitemaps.md

Links analysis (internal/external)

External links: GET .../links/external/samples?offset=&limit= (limit 1-100, default 10) → array {source_url, destination_url, discovery_date, source_last_access_date} + count. History: .../links/external/history?date_from=&date_to=. Internal (broken): .../links/internal/samples + .../links/internal/history. Used for backlink audits and broken-internal-link discovery.

Full reference: references/links.md

Site diagnostics & problems

GET .../diagnostics → {problems: {[PROBLEM_TYPE]: {severity, state, last_state_update}}}. Severity: FATAL (DISALLOWED_IN_ROBOTS, DNS_ERROR, MAIN_PAGE_ERROR, THREATS), CRITICAL (SSL_CERTIFICATE_ERROR, SLOW_AVG_RESPONSE_TIME), POSSIBLE_PROBLEM (NO_SITEMAPS, NO_ROBOTS_TXT, TOO_MANY_PAGE_DUPLICATES), RECOMMENDATION (NOT_MOBILE_FRIENDLY, FAVICON_PROBLEM, NO_METRIKA_COUNTER). State: PRESENT, ABSENT, UNDEFINED. Use for auto-alerting on FATAL/CRITICAL.

Full reference: references/diagnostics.md

Quick reference