Справочник методов API (версия 126)

Все методы API версии 1 (/api/v1). У каждого метода указаны право ключа, команда CLI (seomaster …) и имя инструмента MCP: эти имена общие для CLI и MCP-сервера и не меняются. Общие правила — ошибки, постраничность, идемпотентность, задания, вебхуки — описаны в руководстве «API». Машиночитаемая версия: GET /api/v1/openapi.json, возможности: GET /api/v1/capabilities.

В примерах $SEOMASTER_KEY — ваш ключ (smk_…), seo.example — адрес вашего сервиса. Тексты в примерах ответов приведены как есть, на русском: это язык данных сервиса.

Служебное

GET /capabilities

Право: ключ не нужен · CLI: seomaster api capabilities · MCP: get_capabilities

Возможности API для CLI и MCP-сервера: версия контракта, права, лимиты, соглашения, каталог ошибок, события вебхуков и все методы с именами команд и инструментов. Ключ не нужен.

Пример:

curl "https://seo.example/api/v1/capabilities"

Пример ответа:

{
  "api": {
    "version": "1.1",
    "base": "/api/v1",
    "openapi": "/api/v1/openapi.json"
  },
  "scopes": [
    {
      "id": "read"
    }
  ],
  "limits": {
    "rate_per_hour_default": 120,
    "page_max": 200,
    "idempotency_ttl_s": 86400
  },
  "errors": [
    {
      "code": "limit",
      "http": 429,
      "retry": true
    }
  ],
  "endpoints": [
    {
      "operation_id": "get_api_v1_overview",
      "method": "GET",
      "path": "/api/v1/overview",
      "scope": "read",
      "cli": "sites overview",
      "mcp": "get_overview",
      "read_only": true,
      "async": false
    }
  ]
}

GET /openapi.json

Право: ключ не нужен · CLI: seomaster api spec · MCP: get_openapi_spec

Это описание API в формате OpenAPI 3. Ключ не нужен.

Пример:

curl "https://seo.example/api/v1/openapi.json"

Ответ: the OpenAPI 3 document.

Ключ

GET /me

Право: чтение (read) · CLI: seomaster auth whoami · MCP: get_account

Сведения о ключе и владельце: права, срок, лимит, расход за текущий час.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/me"

Пример ответа:

{
  "user": {
    "id": 7,
    "email": "you@example.com"
  },
  "key": {
    "id": 3,
    "name": "CLI",
    "prefix": "smk_0375",
    "scopes": [
      "read",
      "run",
      "write"
    ],
    "expires": null,
    "allowed_ips": [],
    "created": 1791600000
  },
  "rate": {
    "limit_per_hour": 120,
    "used_this_hour": 4
  },
  "plan": null
}

GET /usage

Право: чтение (read) · CLI: seomaster auth usage · MCP: get_key_usage

Запросы этого ключа по дням за последние 30 суток.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/usage"

Пример ответа:

{
  "days": 30,
  "total": 234,
  "errors": 3,
  "usage": [
    {
      "day": "2026-10-09",
      "calls": 41,
      "errors": 0,
      "limited": 0
    }
  ]
}

Сайты

GET /sites

Право: чтение (read) · CLI: seomaster sites list · MCP: list_sites

Сайты в мониторинге с последней оценкой.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/sites"

Пример ответа:

{
  "sites": [
    {
      "host": "example.com",
      "added": 1791000000,
      "interval_h": 24,
      "rank": 78,
      "prev_rank": 74,
      "label": "Хорошо",
      "last_run": 1791600000
    }
  ]
}

POST /sites

Право: изменение данных (write) · CLI: seomaster sites add · MCP: add_site

Добавить сайт в мониторинг (с учётом лимита тарифа).

Пример:

curl -X POST -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' -d '{"host":"example.com","interval":24}' "https://seo.example/api/v1/sites"

Пример ответа:

{
  "host": "example.com",
  "added": true
}

DELETE /sites/{host}

Право: изменение данных (write) · CLI: seomaster sites remove · MCP: remove_site

Убрать сайт из мониторинга.

Пример:

curl -X DELETE -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" "https://seo.example/api/v1/sites/example.com"

Пример ответа:

{
  "host": "example.com",
  "removed": true
}

GET /overview

Право: чтение (read) · CLI: seomaster sites overview · MCP: get_overview

Все сайты в одной таблице: ранг и его изменение, критичные и открытые задачи, доступность, давность проверки, проект и важность; с фильтрами, сортировкой и постраничным выводом. Для сайтов с типом (профилем) ранг учитывает исключения, рядом rank_without_exclusions.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/overview?state=crit&sort=rank&limit=20"

Пример ответа:

{
  "summary": {
    "n": 7,
    "rated": 6,
    "avg": 65,
    "best": 86,
    "worst": 41,
    "crit": 6,
    "open": 21,
    "falling": 2,
    "down": 1,
    "stale": 3,
    "never": 1
  },
  "sites": [
    {
      "host": "mebel-opt.ru",
      "project": "Интернет-магазины",
      "importance": "critical",
      "rank": 41,
      "rank_delta": -11,
      "rank_band": "bad",
      "critical_tasks": 4,
      "open_tasks": 9,
      "potential_gain": 13.5,
      "online": false,
      "last_check": 1791565637,
      "never_checked": false,
      "stale": true,
      "falling": true,
      "interval_h": 6,
      "crawl": false,
      "profile": null,
      "rank_without_exclusions": null
    }
  ],
  "page": {
    "limit": 50,
    "offset": 0,
    "total": 7,
    "next_offset": null
  }
}

Данные сайта

GET /site/{host}

Право: чтение (read) · CLI: seomaster site show · MCP: get_site

Карточка сайта: оценка, задачи, динамика.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/site/example.com"

Поля ответа: host, checked_at, rank{value,label,groups}, search, baseline, master_index, stats, tasks_open, tasks_potential_gain, top_tasks, crawl, uptime, watchdog_changes, watched_pages, events.

GET /report/{host}

Право: чтение (read) · CLI: seomaster site report · MCP: get_report

Последний отчёт по сайту.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/report/example.com"

Поля ответа: host, checked_at, phase, items[], rank{value,label,color,groups,caps}, tech, version.

GET /history/{host}

Право: чтение (read) · CLI: seomaster site history · MCP: get_history

История проверок.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/history/example.com"

Поля ответа: host, runs[].

GET /crawl/{host}

Право: чтение (read) · CLI: seomaster crawl show · MCP: get_crawl

Последний аудит страниц.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/crawl/example.com"

Поля ответа: host, checked_at, pages[], summary, graph, external.

GET /links/{host}

Право: чтение (read) · CLI: seomaster crawl links · MCP: get_links

Перелинковка: сироты, битые ссылки, дубли.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/links/example.com"

Поля ответа: host, checked_at, orphans, broken, duplicates, top_pages.

GET /external/{host}

Право: чтение (read) · CLI: seomaster crawl external · MCP: get_external_links

Внешние ссылки по результатам аудита.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/external/example.com"

Поля ответа: host, checked_at, external-link summary.

GET /uptime/{host}

Право: чтение (read) · CLI: seomaster uptime show · MCP: get_uptime

Доступность: аптайм за 24 часа, 7 и 30 дней, инциденты.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/uptime/example.com"

Поля ответа: host, up, since, interval_min, last_check, uptime_24h, uptime_7d, uptime_30d, incidents[].

GET /issues/{host}

Право: чтение (read) · CLI: seomaster site issues · MCP: get_top_issues

Пять главных проблем простыми словами: что это, чем грозит, сколько баллов ранга даст исправление, трудоёмкость; итог «если исправить всё».

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/issues/example.com"

Пример ответа:

{
  "host": "example.com",
  "checked_at": 1791654000,
  "profile": null,
  "rank": 62,
  "label": "Средне",
  "verdict": "Есть что улучшить",
  "total_issues": 9,
  "problems": [
    {
      "code": "https",
      "name": "…",
      "level": "Критично",
      "status": "bad",
      "gain": 14,
      "lifts_cap": true,
      "effort": 2,
      "how": "…"
    }
  ],
  "after": 84,
  "gain_all": 22,
  "more": 4
}

GET /changes/{host}

Право: чтение (read) · CLI: seomaster site changes · MCP: get_changes

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

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/changes/example.com"

Пример ответа:

{
  "host": "example.com",
  "from": {
    "id": 812,
    "checked_at": 1791500000,
    "rank": 70
  },
  "to": {
    "id": 845,
    "checked_at": 1791600000,
    "rank": 64
  },
  "rank_delta": -6,
  "new": [
    {
      "code": "h1",
      "title": "Заголовок H1",
      "group": "content",
      "from": null,
      "to": "warn",
      "value": "нет"
    }
  ],
  "fixed": [],
  "returned": [
    {
      "code": "title",
      "title": "Title",
      "group": "content",
      "from": "good",
      "to": "bad",
      "value": "—"
    }
  ],
  "worse": [],
  "improved": [],
  "tech_added": [],
  "tech_removed": [],
  "changed": true,
  "returned_known": true
}

GET /performance/{host}

Право: чтение (read) · CLI: seomaster site performance · MCP: get_performance

Скорость и мобильная версия: проверки скорости и адаптации из последнего отчёта и показатели браузера (LCP, CLS, INP, TBT) по телефону и компьютеру.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/performance/example.com"

Пример ответа:

{
  "host": "example.com",
  "checked_at": 1791600000,
  "checks": [
    {
      "code": "ttfb",
      "title": "Время ответа сервера",
      "status": "good",
      "value": "210 мс",
      "group": "speed"
    }
  ],
  "browser": [
    {
      "device": "mobile",
      "url": "https://example.com/",
      "checked_at": 1791590000,
      "score": 71,
      "lcp_ms": 2900,
      "cls": 0.04,
      "inp_ms": 180,
      "tbt_ms": 220
    }
  ],
  "note": "Показатели браузера (LCP, CLS, INP, TBT) есть только после «Проверки в браузере»."
}

Задачи

GET /tasks/{host}

Право: чтение (read) · CLI: seomaster tasks list · MCP: list_site_tasks

Задачи по сайту с идентификаторами и статусами.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/tasks/example.com"

Поля ответа: host, tasks[].

PATCH /tasks/{id}

Право: изменение данных (write) · CLI: seomaster tasks set-status · MCP: set_task_status

Сменить статус задачи: open, done, ignored.

Пример:

curl -X PATCH -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' -d '{"status":"done"}' "https://seo.example/api/v1/tasks/123"

Пример ответа:

{
  "id": 123,
  "status": "done",
  "host": "example.com"
}

GET /plan

Право: чтение (read) · CLI: seomaster plan · MCP: get_plan

Открытые задачи по всем сайтам (или по одному), самые полезные первыми. План пересобирается с учётом типа сайта.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/plan"

Пример ответа:

{
  "tasks": [
    {
      "id": 2,
      "host": "example.com",
      "title": "Проверка title",
      "level": "bad",
      "status": "open",
      "source": "report",
      "group": "content",
      "impact": 20,
      "hint": "Добавьте title 30–65 знаков",
      "detail": "v",
      "first_seen": 1791649775,
      "last_seen": 1791654327,
      "recheck": true
    }
  ],
  "page": {
    "limit": 50,
    "offset": 0,
    "total": 4,
    "next_offset": null
  }
}

POST /tasks/{id}/recheck

Право: запуск проверок (run) · CLI: seomaster tasks recheck · MCP: recheck_task

Перепроверить одну задачу: сайт проверяется заново, ответ — было, стало, исправлено ли. Свежий отчёт (моложе двух минут) используется повторно; действует суточный предел перепроверок.

Пример:

curl -X POST -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" "https://seo.example/api/v1/tasks/123/recheck"

Пример ответа:

{
  "task": {
    "id": 123,
    "status": "done"
  },
  "outcome": "fixed",
  "outcome_label": "исправлено",
  "before": "Title отсутствует",
  "after": "Title: 52 знака",
  "reused_fresh_report": false,
  "rank_from": 62,
  "rank_to": 66,
  "new_tasks": 0
}

GET /effects/{host}

Право: чтение (read) · CLI: seomaster tasks effects · MCP: get_fix_effects

Эффект исправлений: помогла ли выполненная задача (показатель до и после, изменение в процентах, вывод).

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/effects/example.com"

Пример ответа:

{
  "host": "example.com",
  "effects": [
    {
      "task": "Сжать изображения",
      "done_at": 1791000000,
      "metric": "Ранг",
      "verdict": "improved",
      "before": 71,
      "after": 76,
      "change_pct": 7.0,
      "note": ""
    }
  ],
  "page": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "next_offset": null
  },
  "verdicts": "improved — улучшилось, worse — ухудшилось, flat — без изменений, wait — ждём данных, nodata — мало данных"
}

GET /work/{host}

Право: чтение (read) · CLI: seomaster tasks history · MCP: get_work_history

История работ по сайту: что исправлено, какие были инциденты, ваши пометки за период (days, до 90).

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/work/example.com"

Пример ответа:

{
  "host": "example.com",
  "days": 30,
  "fixed": [
    {
      "title": "Добавить заголовок H1",
      "closed_at": 1791200000
    }
  ],
  "incidents": [
    {
      "title": "Сайт был недоступен",
      "first_seen": 1791100000,
      "status": "resolved"
    }
  ],
  "notes": [
    {
      "at": 1791150000,
      "text": "Сменили хостинг"
    }
  ]
}

События

GET /events

Право: чтение (read) · CLI: seomaster events · MCP: list_events

Лента событий с фильтрами и курсором after_id для опроса.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/events"

Поля ответа: total, events[].

Индексация

GET /indexing/{host}

Право: чтение (read) · CLI: seomaster indexing show · MCP: get_indexing

Диагностика индексации: страницы вне индекса и причины по данным Яндекса и Google, собственная проверка, расхождения, действия.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/indexing/example.com"

Поля ответа: host, run, yandex, google, own, robots_ts, gaps, actions, summary.

Рынок

GET /market/{host}

Право: чтение (read) · CLI: seomaster market show · MCP: get_market

Рыночная аналитика по загруженным данным подключённого источника (Ahrefs, Semrush): конкуренты, пересечения, упущенные запросы и потенциал. Данные только ваши и только из разрешённых источников.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/market/example.com"

Поля ответа: host, source, sources, filter, mine, country, ts, domains[], rivals[], overlap, counts, notes, opportunities[], page.

Тип сайта

GET /profile/{host}

Право: чтение (read) · CLI: seomaster profile show · MCP: get_site_profile

Тип сайта (магазин, форум, блог, корпоративный, портал), исключённые проверки, ранг с профилем и без исключений, допустимые типы и исключения.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/profile/example.com"

Пример ответа:

{
  "host": "example.com",
  "profile": "shop",
  "title": "Интернет-магазин",
  "exclude": [
    "text",
    "pwa"
  ],
  "updated": 1791600000,
  "applied": {
    "base": 62,
    "value": 66,
    "delta": 4,
    "warn": false,
    "excluded": [
      {
        "code": "pwa",
        "title": "…",
        "was": 0,
        "reason": "…"
      }
    ]
  },
  "limits": {
    "max_exclusions": 5,
    "max_group_share": 0.5,
    "warn_lift": 5
  }
}

PUT /profile/{host}

Право: изменение данных (write) · CLI: seomaster profile set · MCP: set_site_profile

Задать тип сайта и исключения. Каждое исключение нужно подтвердить в confirm: исключаются только проверки из белого списка, не больше 5 и не больше половины веса группы. Без exclude берутся исключения типа по умолчанию.

Пример:

curl -X PUT -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' -d '{"profile":"shop","exclude":["pwa"],"confirm":["pwa"]}' "https://seo.example/api/v1/profile/example.com"

Пример ответа:

{
  "host": "example.com",
  "profile": "shop",
  "exclude": [
    "pwa"
  ],
  "applied": {
    "base": 62,
    "value": 65,
    "delta": 3
  }
}

DELETE /profile/{host}

Право: изменение данных (write) · CLI: seomaster profile reset · MCP: reset_site_profile

Сбросить тип сайта: применяется стандартный набор проверок.

Пример:

curl -X DELETE -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" "https://seo.example/api/v1/profile/example.com"

Справка

GET /explain

Право: чтение (read) · CLI: seomaster explain list · MCP: list_explanations

Список кодов проверок, для которых есть объяснение и инструкция.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/explain"

Пример ответа:

{
  "codes": [
    {
      "code": "https",
      "has_hint": true,
      "has_guide": true
    }
  ],
  "page": {
    "limit": 100,
    "offset": 0,
    "total": 78,
    "next_offset": null
  }
}

GET /explain/{code}

Право: чтение (read) · CLI: seomaster explain show · MCP: explain_check

Объяснение проверки: что это значит, примеры хорошего и плохого значения, почему важно, трудоёмкость и ссылка на пошаговую инструкцию. Параметр lang=ru|en.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/explain/ttfb?lang=en"

Пример ответа:

{
  "code": "ttfb",
  "hint": {
    "what": "…",
    "good": "Up to 0.6 s.",
    "bad": "1.5 s or more: …",
    "glossary": "/help/terms#ttfb"
  },
  "plain": {
    "name": "…",
    "what": "…",
    "why": "…",
    "benefit": "…",
    "effort": 3,
    "who": "…"
  },
  "guide": {
    "id": "ttfb",
    "title": "…",
    "url": "/fix/ttfb"
  }
}

Проверки

GET /analyze

Право: запуск проверок (run) · CLI: seomaster analyze now · MCP: analyze_site_sync

Проверить сайт (или взять свежий отчёт из кэша).

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/analyze?d=example.com"

Ответ: the full report (same as /report/{host}).

GET /check/{tool}

Право: запуск проверок (run) · CLI: seomaster check page · MCP: check_page

Одна проверка страницы (meta, headings, images и т. д.).

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/check/meta?url=https://example.com/"

Ответ: url and the check result.

GET /full

Право: запуск проверок (run) · CLI: seomaster check full · MCP: check_page_full

Все проверки страницы сразу.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/full?url=https://example.com/"

Поля ответа: url, overall, checks{}.

GET /ssl/{host}

Право: запуск проверок (run) · CLI: seomaster check ssl · MCP: check_ssl

Сертификат сайта (живое подключение).

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/ssl/example.com"

Ответ: certificate details.

GET /dns/{host}

Право: запуск проверок (run) · CLI: seomaster check dns · MCP: check_dns

DNS-записи домена (живой запрос).

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/dns/example.com"

Поля ответа: DNS records and findings.

POST /analyze

Право: запуск проверок (run) · CLI: seomaster analyze start · MCP: start_analysis · долгая операция: ответ 202 и задание

Запустить проверку сайта в фоне: ответ 202 с заданием, ход — GET /jobs/{id}. Свежий отчёт из кэша возвращается как готовое задание; fresh=true — проверить заново.

Пример:

curl -X POST -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' -d '{"host":"example.com"}' "https://seo.example/api/v1/analyze"

Пример ответа:

{
  "job": {
    "id": 15,
    "kind": "analyze",
    "host": "example.com",
    "state": "queued",
    "progress": 0,
    "items": [
      {
        "host": "example.com",
        "state": "queued",
        "progress": 0,
        "step": "",
        "error": null,
        "cached": false
      }
    ],
    "created": 1791600000,
    "age_s": 0,
    "poll_after_s": 3,
    "result": null,
    "self": "/api/v1/jobs/15"
  }
}

POST /crawl/{host}

Право: запуск проверок (run) · CLI: seomaster crawl start · MCP: start_crawl · долгая операция: ответ 202 и задание

Запустить аудит страниц сайта из мониторинга в фоне: ответ 202 с заданием. Считается как три проверки в лимите.

Пример:

curl -X POST -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" "https://seo.example/api/v1/crawl/example.com"

Пример ответа:

{
  "job": {
    "id": 16,
    "kind": "crawl",
    "host": "example.com",
    "state": "queued",
    "progress": 0,
    "poll_after_s": 3,
    "self": "/api/v1/jobs/16"
  }
}

Задания

GET /jobs

Право: чтение (read) · CLI: seomaster jobs list · MCP: list_jobs

Последние фоновые задания, запущенные через API.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/jobs"

Пример ответа:

{
  "jobs": [
    {
      "id": 15,
      "kind": "analyze",
      "host": "example.com",
      "state": "done",
      "progress": 100,
      "result": {
        "report": "/api/v1/report/example.com",
        "issues": "/api/v1/issues/example.com"
      },
      "poll_after_s": null
    }
  ],
  "page": {
    "limit": 20,
    "offset": 0,
    "total": 2,
    "next_offset": null
  }
}

GET /jobs/{id}

Право: чтение (read) · CLI: seomaster jobs show · MCP: get_job

Состояние задания: queued, running, done или error, прогресс, ссылки на результат; poll_after_s — через сколько секунд спрашивать снова.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/jobs/123"

Пример ответа:

{
  "job": {
    "id": 15,
    "kind": "analyze",
    "host": "example.com",
    "state": "running",
    "progress": 55,
    "poll_after_s": 3,
    "self": "/api/v1/jobs/15"
  }
}

Диагностика

GET /diagnosis

Право: чтение (read) · CLI: seomaster diagnosis all · MCP: get_diagnosis_all

Диагноз всех ваших сайтов: уровень, оценка здоровья, первопричина. Самые тяжёлые первыми.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/diagnosis"

Ответ: sites[].

GET /diagnosis/{host}

Право: чтение (read) · CLI: seomaster diagnosis show · MCP: get_diagnosis

Полный диагноз сайта: зоны здоровья, первопричина, динамика, полнота данных и рекомендуемый порядок действий с оценкой времени и прироста индекса.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/diagnosis/example.com"

Ответ: diagnosis{}.

GET /diagnosis/{host}/history

Право: чтение (read) · CLI: seomaster diagnosis history · MCP: get_diagnosis_history

Здоровье сайта по дням: оценка, уровень, зоны, первопричина и изменения за неделю.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/diagnosis/example.com/history"

Поля ответа: host, days, stability, points[], week.

Трафик

GET /traffic/{host}

Право: чтение (read) · CLI: seomaster traffic forecast · MCP: get_traffic_forecast

Прогноз органического трафика на 14 дней с диапазоном, тренд, необычные дни, оценка трафика конкурентов по вашим запросам и потенциал роста.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/traffic/example.com"

Поля ответа: host, source, days, real_monthly_organic, verdict, forecast, estimate, potential.

Поиск и ссылки

GET /queries/{host}

Право: чтение (read) · CLI: seomaster search queries · MCP: list_search_queries

Поисковые запросы сайта из Яндекс.Вебмастера и Google Search Console: клики, позиция и их прежние значения.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/queries/example.com"

Пример ответа:

{
  "host": "example.com",
  "queries": [
    {
      "engine": "yandex",
      "query": "купить диван",
      "clicks": 120,
      "clicks_prev": 98,
      "position": 4.2,
      "position_prev": 5.1
    }
  ],
  "page": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "next_offset": null
  }
}

GET /opportunities/{host}

Право: чтение (read) · CLI: seomaster search opportunities · MCP: list_search_opportunities

Возможности роста по данным поиска: запросы «почти в топе», низкий CTR и каннибализация страниц, с ожидаемым приростом кликов.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/opportunities/example.com"

Пример ответа:

{
  "host": "example.com",
  "opportunities": [
    {
      "engine": "google",
      "kind": "near",
      "query": "диван угловой",
      "impressions": 900,
      "clicks": 12,
      "position": 8.4,
      "expected_gain_clicks": 35
    }
  ],
  "page": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "next_offset": null
  }
}

GET /positions/{host}

Право: чтение (read) · CLI: seomaster positions list · MCP: list_positions

Позиции отслеживаемых запросов: сейчас, в прошлую проверку, неделю назад, лучшая; trend=down — просевшие за неделю, up — выросшие, lost — выпавшие из выдачи.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/positions/example.com"

Пример ответа:

{
  "host": "example.com",
  "trend": "down",
  "keywords": [
    {
      "query": "диван",
      "engine": "yandex",
      "device": "desktop",
      "region": 213,
      "group": "",
      "position": 9,
      "previous": 7,
      "week_ago": 5,
      "change_week": -4,
      "best": 3,
      "page": "https://example.com/divany/",
      "checked": "2026-10-09"
    }
  ],
  "page": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "next_offset": null
  }
}

GET /backlinks/{host}

Право: чтение (read) · CLI: seomaster backlinks list · MCP: list_backlinks

Обратные ссылки из подключённых источников: живые или пропавшие, с анкором, типом и рейтингом источника.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/backlinks/example.com"

Пример ответа:

{
  "host": "example.com",
  "state": "live",
  "links": [
    {
      "source": "https://blog.example.org/post",
      "target": "https://example.com/",
      "anchor": "example",
      "nofollow": false,
      "source_rating": 41,
      "first_seen": 1790000000,
      "lost_at": null
    }
  ],
  "page": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "next_offset": null
  }
}

Позиции

GET /positions/{host}/pages

Право: чтение (read) · CLI: seomaster positions pages · MCP: get_position_pages

Какие страницы сайта держат видимость и по каким запросам, плюс каннибализация (по запросу в выдаче разные страницы).

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/positions/example.com/pages"

Поля ответа: host, pages[], cannibalization[].

GET /positions/{host}/volatility

Право: чтение (read) · CLI: seomaster positions volatility · MCP: get_serp_volatility

Волатильность выдачи по дням: смена состава топ-10 и сдвиги ваших позиций, дни, похожие на обновление выдачи.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/positions/example.com/volatility"

Поля ответа: host, days, market_median_pct, series[], shakes[].

Конкуренты

GET /competitors/{host}/history

Право: чтение (read) · CLI: seomaster competitors history · MCP: get_competitor_history

Динамика доли видимости вас и главных конкурентов по срезам выдачи (параметры points до 26, step 7 или 30) и кто вас обогнал или резко вырос.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/competitors/example.com/history"

Поля ответа: host, step_days, valid_points, days, checked_queries, my_share, rivals[], movers[].

GET /competitors/{host}

Право: чтение (read) · CLI: seomaster competitors show · MCP: get_competitors

Доля видимости сайта и конкурентов по вашим запросам, угрозы, площадки в выдаче, кластеры запросов, намерения и сложность.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/competitors/example.com"

Ответ: competitors[].

GET /keyword-gap/{host}

Право: чтение (read) · CLI: seomaster keyword-gap · MCP: get_keyword_gap

Разрыв по запросам: где конкуренты в топ-10, а вас нет (kind=missing) или они выше (kind=behind). С оценкой потенциала и сложности.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/keyword-gap/example.com"

Поля ответа: host, kind, total, rows[].

Глубокий обход

GET /deep/{host}/js

Право: чтение (read) · CLI: seomaster deep js · MCP: get_js_dependency

Зависимость сайта от JS по последней проверке рендерингом: разделы, страницы выборки, что добавляет JS (текст, ссылки, мета-данные), найденные фреймворки.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/deep/example.com/js"

Поля ответа: host, checked_at, summary, verdict, pages[].

Соцсети

GET /social/{host}

Право: чтение (read) · CLI: seomaster social show · MCP: get_social

Ссылки на соцсети на главной, карточки Open Graph, состояние страниц ВКонтакте и Telegram, число подписчиков и замечания аудита (по последней проверке).

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/social/example.com"

Поля ответа: host, checked_at, profiles, cards, card_score, pages, checks.

Сторонние API

GET /providers

Право: чтение (read) · CLI: seomaster providers list · MCP: list_providers

Реестр провайдеров: подключён ли, свежесть данных, бюджет ошибок за 30 суток, атрибуция, можно ли показывать данные публично, срок хранения и когда вы сверяли условия. Параметр all=1 добавляет неиспользуемых провайдеров.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/providers"

Поля ответа: data_states, slo_days, slo_target, providers[].

Утилиты

Утилиты сервиса (страница «Инструменты») как методы API. Всего 86: проверки сайта по адресу, текст, разработчику, сеть и IP, подсказки и превью, изображения, расчёты. Сначала GET /utilities/{id} (поля и пример), затем POST /utilities/{id}. Утилиты, считающие по присланным данным, доступны ключу с правом read; те, что обращаются к чужим сайтам (net: true), требуют run и имеют отдельный предел обращений в час. Данные нигде не сохраняются. Администратор может отключить утилиту: ответ tool_off. Файлы (изображения, .docx) передаются в base64 в поле файла, файл-результат приходит в data_base64.

GET /utilities

Право: чтение (read) · CLI: seomaster utils list · MCP: list_utilities

Каталог утилит: группа, название, обращается ли к чужим сайтам (net), работает ли через API (available), включена ли (enabled). Фильтры: group (site, text, dev, calc, net, seo, img), q (поиск), net (1 или 0).

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/utilities?group=text"

Поля ответа: utilities[] (id, group, group_title, title, description, net, file, available, enabled), page, groups.

GET /utilities/{id}

Право: чтение (read) · CLI: seomaster utils show · MCP: get_utility

Описание одной утилиты: поля ввода (name, type, label, required, а также options, default, max), нужное право (scope), основное поле (primary), пример input_example.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/utilities/hash"

POST /utilities/{id}

Право: чтение (read); для утилит с net: true — запуск проверок (run) · CLI: seomaster utils run · MCP: run_utility

Запустить утилиту. Ответ: result (данные), blocks (готовые блоки: пары, таблицы, код, сравнение, изображения) и warnings. Ошибки: bad_param (поле неизвестно, пустое или вне допустимых значений), tool_failed (утилита не смогла обработать ввод или сайт), tool_off, scope, limit.

Пример:

curl -X POST -H "X-Api-Key: $SEOMASTER_KEY" -H 'Content-Type: application/json' -d '{"input":{"text":"Привет, мир"}}' "https://seo.example/api/v1/utilities/counter"

Тело запроса к утилитам — до 7,6 МБ (тексты до 200 000 знаков, файлы до 5 МБ).

Сводки

GET /today

Право: чтение (read) · CLI: seomaster today · MCP: get_today

Что делать сегодня: индекс и динамика сайтов, самые полезные задачи, открытые инциденты, диагноз, вероятные причины, результаты ваших действий, события за сутки.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/today"

Поля ответа: kpi, sites[], actions[], actions_total, incidents[], diagnosis[], changes[], causes[], results[], verify, events_24h[].

GET /incidents

Право: чтение (read) · CLI: seomaster incidents · MCP: list_incidents

Инциденты: связанные сигналы (падение, недоступность, изменение выдачи) с началом, концом, уровнем и советом. Фильтры: host, days, status.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/incidents?status=open"

Поля ответа: days, host, incidents[], page.

Вебхуки

GET /webhooks

Право: чтение (read) · CLI: seomaster webhooks list · MCP: list_webhooks

Ваши адреса вебхуков и их состояние (без секретов).

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/webhooks"

Ответ: webhooks[].

GET /webhooks/{id}/deliveries

Право: чтение (read) · CLI: seomaster webhooks deliveries · MCP: list_webhook_deliveries

Последние доставки на адрес: статус, код ответа, число попыток.

Пример:

curl -H "X-Api-Key: $SEOMASTER_KEY" "https://seo.example/api/v1/webhooks/123/deliveries"

Поля ответа: total, deliveries[].

POST /webhooks/{id}/test

Право: изменение данных (write) · CLI: seomaster webhooks test · MCP: test_webhook

Отправить на адрес тестовое событие и вернуть результат.

Пример:

curl -X POST -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" "https://seo.example/api/v1/webhooks/123/test"

Поля ответа: ok, code, error, delivery.

POST /webhooks

Право: изменение данных (write) · CLI: seomaster webhooks add · MCP: add_webhook

Создать адрес вебхука. Секрет для проверки подписи показывается один раз.

Пример:

curl -X POST -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' -d '{"url":"https://hooks.example.com/in","events":["rank"],"hosts":["example.com"]}' "https://seo.example/api/v1/webhooks"

Пример ответа:

{
  "id": 4,
  "secret": "whsec_…",
  "note": "Секрет показан один раз…",
  "name": "CI",
  "url": "https://hooks.example.com/in",
  "events": [
    "rank"
  ],
  "hosts": [
    "example.com"
  ],
  "active": true
}

DELETE /webhooks/{id}

Право: изменение данных (write) · CLI: seomaster webhooks remove · MCP: remove_webhook

Удалить адрес вебхука вместе с журналом доставок.

Пример:

curl -X DELETE -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" "https://seo.example/api/v1/webhooks/123"

Пример ответа:

{
  "id": 4,
  "removed": true
}

POST /webhooks/{id}/rotate-secret

Право: изменение данных (write) · CLI: seomaster webhooks rotate-secret · MCP: rotate_webhook_secret

Выпустить новый секрет подписи; старый перестаёт действовать, новый показывается один раз.

Пример:

curl -X POST -H "X-Api-Key: $SEOMASTER_KEY" -H "Idempotency-Key: $(uuidgen)" "https://seo.example/api/v1/webhooks/123/rotate-secret"

Пример ответа:

{
  "id": 4,
  "secret": "whsec_…",
  "note": "Старый секрет больше не действует…"
}