SEO
API проверяет SEO сайта и управляет файлами для поисковых систем. Сценарии — в гайде. Отправка страниц на индексацию — на странице «Индексация».
API — https://onpress.pro/api/v2, SITE — id сайта, OP_TOKEN — токен op_XXXX. Пути на этой странице начинаются с $API/site/$SITE. Токен и права — в «Авторизации», общий формат — в «Общих правилах».
Эндпоинты
Профильные операции /data/… возвращают результат в items[0]; наружные name, origin: "system" и total: 1 описывают системные данные. Названия полей результата ниже относятся к items[0]. Неподдерживаемый метод дает 405 wrong_method_for_source, пробный прогон без поддержки — 400 dry_run_not_supported. Прежние URL продолжают работать со своим форматом ответа.
Проверить SEO сайта
PUT /data/seo.audit
Проверяет весь чеклист раздела SEO на сервере и сохраняет итог: SEO-настройки и настройки сайта, тему, языки и главные, набор author, счетчики и консоли, файлы robots.txt и llms.txt, визиты ботов и обход страниц. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.audit" -H "Authorization: Bearer $OP_TOKEN"
Дополнительных полей строки запроса нет.
Ответ
Длится столько же, сколько обход страниц: от секунд до минуты; второй POST, пока идет первый, получает его результат. Источник, который не ответил, переводит свои пункты в unknown и называется в errors, остальные пункты считаются.
{
"success": true,
"name": "seo.audit",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "x9HTLHECq",
"checked": true,
"format": 1,
"checked_at": "2026-09-29T09:25:16.998Z",
"took_ms": 1202,
"site_url": "https://example.com",
"totals": {
"counted": 38,
"ok": 19,
"todo": 16,
"warn": 3,
"na": 1,
"unknown": 0
},
"sitemap": {
"url": "https://example.com/sitemap_index.xml",
"consoles": {
"gsc": {
"state": "not_connected"
},
"ywm": {
"state": "not_connected"
}
},
"error": null
},
"files": {
"robots": {
"state": "ok",
"http": 200,
"url": "https://example.com/robots.txt"
},
"llms": {
"state": "none",
"http": 404,
"url": "https://example.com/llms.txt"
}
},
"bots": {
"…": "…"
},
"errors": [],
"checks": [
{
"id": "identity",
"group": "Basics",
"status": "ok",
"title": {
"key": "seo.checks.identity.title"
},
"why": {
"key": "seo.checks.identity.why"
},
"summary": "Example",
"fields": [
{
"label": {
"key": "seo.checks.identity.fields.title"
},
"value": "Example"
}
],
"fix": {
"title": "…",
"command": "curl -X PATCH …"
}
}
]
}
]
}
| Поле ответа | Описание |
|---|---|
checked_at, took_ms | когда прошла проверка и сколько длилась |
totals | counted, ok, todo, warn, na, unknown; na и unknown в counted не входят |
sitemap | адрес карты сайта и что о ней знают Search Console и Вебмастер — в форме GET /data/seo.sitemap |
files | живые robots.txt и llms.txt: robots.state — ok, warn (закрывает весь сайт Disallow: /, так бывает у закрытого сайта) или fail (не отдается, http); llms.state — ok, none (404, файл не собран) или fail |
bots | когда поисковые и ИИ-боты последний раз заходили за robots.txt и картой сайта |
errors | источники, которые не ответили |
checks | пункты чеклиста, см. пункты проверки |
Пункт: id, group (Basics, Indexing, Languages, Markup, Speed, Pages — в консоли «Контент»), status — ok, todo (сделать), warn (требует внимания), na (неприменимо), unknown (источник не ответил); summary, fields, note, rows — строки таблицы пункта, pages — страницы с нарушением; fix — готовая команда curl с этим сайтом; builtin: true — то, что платформа делает сама. Тексты — не фразы, а ключи словаря консоли: {"key", "params"}, {"list": […]}, {"join": […], "sep"}, {"age": iso}; простая строка — значение как есть.
Своих отказов у эндпоинта нет: сломанный источник не останавливает проверку, а попадает в errors.
Ошибки
Общие коды — на странице «Ошибки».
Прочитать итог проверки
GET /data/seo.audit
Отдает сохраненный итог без новой проверки — раздел SEO консоли при открытии делает ровно этот вызов. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.audit" -H "Authorization: Bearer $OP_TOKEN"
Параметр адресации передается в строке запроса; тела нет.
Ответ
Ответ — в форме PUT /data/seo.audit и еще два поля, прочитанные вживую: running: true, пока идет проверка, и access — состояние «сайт открыт / закрыт» (closed, supported, reason, url, retry_after; null, если прочитать не удалось). До первой проверки — checked: false, checked_at: null, checks: [].
Ошибки
Общие коды — на странице «Ошибки».
Проверить страницы
GET /data/seo.pages
Обходит опубликованные страницы по HTTP и читает ту разметку, которую сервер отдает на самом деле: до 2000 страниц, 8 одновременно, 15 с на страницу. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.pages?lang=ru" -H "Authorization: Bearer $OP_TOKEN"
Параметры запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
lang | string | нет | all | язык страниц |
Ответ
Пункты pages-*, headings, images-alt и keywords проверки считаются по этому же обходу.
{
"success": true,
"name": "seo.pages",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "x9HTLHECq",
"lang": "ru",
"checked_at": "2026-10-28T06:37:00.882Z",
"took_ms": 2808,
"totals": {
"pages": 35,
"crawled": 35,
"checked": 30,
"skipped_noindex": 5,
"unreachable": 0
},
"meta": {
"count": 0,
"pages": []
},
"lengths": {
"count": 22,
"title_max": 65,
"description_max": 165,
"pages": [
{
"id": 6231,
"url": "/ru/docs/",
"long": [
"title"
],
"title_text": "…"
}
]
},
"headings": {
"count": 3,
"pages": [
{
"id": 6234,
"url": "/ru/docs/install/",
"problems": [
{
"kind": "many_h1",
"count": 2,
"text": "Установка"
}
],
"outline": [
"…"
]
}
]
},
"noindex": {
"count": 5,
"pages": [
{
"id": 6240,
"url": "/ru/errors/",
"status": 404
}
]
},
"unreachable": [],
"signals": {
"pages": 30,
"canonical": {
"…": "…"
},
"schema": {
"…": "…"
},
"images": {
"…": "…"
},
"preload": {
"…": "…"
},
"hreflang": {
"…": "…"
},
"og": {
"…": "…"
},
"redirects": {
"…": "…"
},
"not_found": {
"…": "…"
}
},
"summary": {
"…": "…"
},
"pages": [
"…"
]
}
]
}
meta.pages[] — страницы с пустым <title> или meta description (missing, title_text, description_text). lengths.pages[] — title длиннее title_max или описание длиннее description_max (long, тексты и длины). headings.pages[] — нарушения заголовков. noindex.pages[] — страницы, которые отдаются с noindex, с кодом ответа; на заголовки они не проверяются. unreachable — открытые страницы, ответившие не 2xx (reason: http_error, timeout, unreachable, not_html). signals — то, что платформа делает сама: canonical (with, self, other, missing), redirects, not_found, schema, images (img, webp, without_webp), preload, hreflang (missing_return), home.x_default, og; списки режутся до 50 адресов. Больше 2000 страниц — в totals появляется truncated_at.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
unknown_language | 422 | такого языка на сайте нет; языки — в languages | возьмите слаг из ответа |
no_public_pages | 409 | ни у одной опубликованной страницы нет адреса | опубликуйте страницы |
Запустить проверку ссылок
PUT /data/seo.links
Ставит фоновую проверку ссылок и сразу возвращает HTTP 202. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.links" -H "Authorization: Bearer $OP_TOKEN"
Дополнительных полей строки запроса нет.
Ответ
{
"success": true,
"name": "seo.links",
"origin": "system",
"total": 1,
"items": [
{
"status": "running",
"started_at": "2026-10-30T12:00:00Z"
}
]
}
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
check_running | 409 | на сайте уже идет проверка | дождитесь итога в GET /data/seo.links |
checks_busy | 429 | сервер проверяет ссылки других сайтов | повторите через несколько минут |
Прочитать проверку ссылок
GET /data/seo.links
Отдает состояние или итог фоновой проверки ссылок. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.links" -H "Authorization: Bearer $OP_TOKEN"
Параметр адресации передается в строке запроса; тела нет.
Ответ
Ответ GET: status — none (проверки не было), running, done, failed, interrupted; started_at, finished_at; в итоге — dead, wrong_lang, unconfirmed и totals. Причина мертвой ссылки — http_404, http_410, http_5xx, dns, soft_404; неподтвержденной — timeout, tls, redirect_loop или код ответа, который закрывает страницу от роботов.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
check_running | 409 | на сайте уже идет проверка | дождитесь итога в GET /data/seo.links |
checks_busy | 429 | сервер проверяет ссылки других сайтов | повторите через несколько минут |
Получить граф ссылок
GET /data/seo.link_graph
Строит граф внутренних ссылок по телам опубликованных страниц: входящие и исходящие ссылки, сироты и вес страницы. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.link_graph?lang=ru" -H "Authorization: Bearer $OP_TOKEN"
Параметры запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
lang | string | нет | all | язык страниц |
fresh | 1 | нет | — | пересчитать мимо кэша |
Ответ
Граф кэшируется и пересчитывается сам, когда меняются страницы.
{
"success": true,
"name": "seo.link_graph",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "x9HTLHECq",
"lang": "ru",
"scope": "body",
"cached": false,
"built_at": "2026-10-28T06:37:00.882Z",
"weight": {
"method": "…",
"iterations": 20,
"damping": 0.85,
"scale": "…"
},
"summary": {
"pages": 120,
"orphans": 4,
"avg_inbound": 3.2,
"site_pages": 120,
"site_edges": 410,
"site_unresolved_links": 2
},
"pages": [
{
"id": 6231,
"url": "/ru/docs/",
"lang": "ru",
"inbound": 12,
"inbound_links": 15,
"outbound": 8,
"outbound_links": 9,
"orphan": false,
"front": false,
"weight": 4.1
}
]
}
]
}
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
unknown_language | 422 | такого языка на сайте нет | возьмите слаг из languages |
polylang_inactive | 409 | lang передан сайту с одним языком | уберите lang |
too_many_pages | 413 | опубликовано больше 5000 страниц | — |
Проверить индексацию страницы
GET /data/seo.index_status
Отдает вердикт Search Console URL Inspection по одной странице. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.index_status?ref=5776" -H "Authorization: Bearer $OP_TOKEN"
Параметры запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
ref | string | да | — | Id, слаг или путь страницы, обязательно |
refresh | bool | нет | false | спросить Google заново; не чаще раза в час на страницу |
lang | string | нет | — | язык, если слаг есть в нескольких языках |
Ответ
Результат держится сутки.
Ответ: property — ресурс Search Console, quota — остаток квоты, page (у POST — pages и summary: total, live, cached, deferred, failed). У страницы — verdict, coverage_state, indexing_state, robots_txt_state, page_fetch_state, last_crawl_time, google_canonical, checked_at, source (live, cache, none). Квота — 1900 проверок в сутки на ресурс; что не влезло в квоту, в POST приходит с deferred, а не отказом всего пакета.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
ref_required, refs_required | 400 | нет ref или пустой refs | передайте страницу |
too_many_refs | 400 | больше 100 страниц | разбейте на части |
invalid_ref | 400 | элемент refs не число и не строка | исправьте список |
unknown_field | 400 | в теле POST поле кроме refs, refresh, lang | уберите поле |
page_not_found | 404 | страницы нет | проверьте ref |
not_published | 409 | страница не опубликована | опубликуйте ее |
gsc_not_connected | 409 | Search Console не подключена | PUT /data/settings/gsc |
gsc_quota_exhausted | 429 | квота на сутки кончилась; Retry-After | повторите после срока |
gsc_busy | 503 | Google не ответил в срок | повторите запрос |
Проверить индексацию нескольких страниц
PUT /data/seo.index_status
Отдает вердикты Search Console URL Inspection для списка до 100 страниц. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.index_status" -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' -d '{"refs": [5776]}'
Тело запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
refs | array | да | — | До 100 id, слагов или путей, обязательно |
refresh | bool | нет | false | спросить Google заново; не чаще раза в час на страницу |
lang | string | нет | — | язык, если слаг есть в нескольких языках |
Ответ
Результат держится сутки.
Ответ: property — ресурс Search Console, quota — остаток квоты, page (у POST — pages и summary: total, live, cached, deferred, failed). У страницы — verdict, coverage_state, indexing_state, robots_txt_state, page_fetch_state, last_crawl_time, google_canonical, checked_at, source (live, cache, none). Квота — 1900 проверок в сутки на ресурс; что не влезло в квоту, в POST приходит с deferred, а не отказом всего пакета.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
ref_required, refs_required | 400 | нет ref или пустой refs | передайте страницу |
too_many_refs | 400 | больше 100 страниц | разбейте на части |
invalid_ref | 400 | элемент refs не число и не строка | исправьте список |
unknown_field | 400 | в теле POST поле кроме refs, refresh, lang | уберите поле |
page_not_found | 404 | страницы нет | проверьте ref |
not_published | 409 | страница не опубликована | опубликуйте ее |
gsc_not_connected | 409 | Search Console не подключена | PUT /data/settings/gsc |
gsc_quota_exhausted | 429 | квота на сутки кончилась; Retry-After | повторите после срока |
gsc_busy | 503 | Google не ответил в срок | повторите запрос |
Прочитать SEO-настройки
GET /data/seo
Возвращает настройки SEO, общие для сайта. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo" -H "Authorization: Bearer $OP_TOKEN"
Параметр адресации передается в строке запроса; тела нет.
Ответ
{
"success": true,
"name": "seo",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "SITE_ID",
"seo": {
"separator": "sc-dash",
"separator_char": "-",
"sitemap": {
"enabled": true,
"entries_per_page": 1000
}
}
}
]
}
Полный состав seo и допустимые значения — в описании записи. Постраничные SEO-поля описывает справочник «Страницы».
Ошибки
Общие коды — на странице «Ошибки».
Изменить SEO-настройки
PATCH /data/seo
API использует SEO-настройки сайта — разделитель и шаблоны заголовков, метаописания, флаги noindex, хлебные крошки, организацию для SEO-графа, Open Graph, карту сайта; Передайте только изменяемые разделы. Подробнее в гайде.
curl -s -X PATCH "$API/site/$SITE/data/seo" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"sitemap": {"enabled": true}}'
Тело запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
separator | string | нет | без изменения | Ключ из чтения, например sc-dash. |
titles | object | нет | без изменения | Шаблоны home, page, post, 404, author, archive, search. |
metadesc | object | нет | без изменения | Шаблоны home, page, post, author, archive. |
noindex | object | нет | без изменения | archive, author, author_noposts, карты post_types, taxonomies. |
attachments | object | нет | без изменения | redirect_to_parent. |
breadcrumbs | object | нет | без изменения | enabled, separator, home, prefix, bold_last. |
organization | object | нет | без изменения | type, name, alternate_name, logo, person_user_id, person_name, person_logo. |
social | object | нет | без изменения | open_graph, twitter, twitter_card, default_image, profiles. |
sitemap | object | нет | без изменения | enabled, entries_per_page, author. |
index_now | object | нет | без изменения | enabled, key. Для отправки адресов используйте /data/seo.indexnow. |
Ответ
Постраничные title, description и noindex здесь не живут: они в свойствах страницы.
{
"success": true,
"name": "seo",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "x9HTLHECq",
"changed": [
"sitemap.enabled"
],
"seo": {
"separator": "sc-dash",
"separator_char": "-",
"sitemap": {
"enabled": true,
"entries_per_page": 1000,
"author": false,
"index_url": "https://example.com/sitemap_index.xml",
"…": "…"
},
"robots_url": "https://example.com/robots.txt",
"…": "…"
},
"cache": {
"…": "…"
}
}
]
}
| Раздел | Ключи |
|---|---|
separator | строка — ключ разделителя: sc-dash, sc-pipe, sc-middot… |
titles | шаблоны: home, page, post, 404, author, archive, search |
metadesc | home, page, post, author, archive |
noindex | archive, author, author_noposts (bool), post_types, taxonomies — карты {имя: да или нет} |
attachments | redirect_to_parent (bool) |
breadcrumbs | enabled, bold_last (bool), separator, home, prefix |
organization | type (company, person), name, alternate_name, logo (id картинки), person_user_id, person_name, person_logo (id); при чтении — logo_id, logo_url, person_logo_id |
social | open_graph, twitter (bool), twitter_card (summary, summary_large_image), default_image (id картинки), profiles — facebook, twitter (без @), instagram, linkedin, youtube, wikipedia, mastodon, pinterest, other (массив адресов); при чтении — default_image_id |
sitemap | enabled, author (bool; не действует — архивов авторов нет), entries_per_page (1–10 000); при чтении еще post_types, taxonomies, governed_by, index_url |
index_now | enabled, key; при чтении еще supported. Отправка IndexNow идет через PUT /data/seo.indexnow, этот раздел ее не включает |
При чтении рядом еще separator_char и robots_url. Ответ записи — changed (измененные ключи), seo после записи и cache. Состав карты сайта задают noindex.post_types и noindex.taxonomies, в карте только страницы. Свою организацию лучше задавать в данных — PATCH /data/site.organization: пока там пусто name, узел Organization строится из раздела organization этого эндпоинта.
Передайте хотя бы одно поле. Типы вложенных полей и допустимые значения — в описании ответа.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
nothing_to_change | 400 | пустое тело | пришлите раздел |
unknown_field | 400 | незнакомый раздел или ключ, в том числе незнакомая соцсеть или тип записей; допустимые — в message | уберите поле |
invalid_{раздел}, invalid_{ключ} | 400 | раздел не объект или значение не той формы: строка, целое число, да/нет | исправьте значение |
invalid_separator | 400 | не ключ вида sc-dash | возьмите ключ из чтения |
invalid_organization_type | 400 | type не company и не person | исправьте тип |
invalid_logo, invalid_default_image | 400 | картинки с таким id на сайте нет | возьмите id из GET /media |
invalid_person_user | 400 | пользователя person_user_id нет | проверьте id |
invalid_twitter_card | 400 | не summary и не summary_large_image | исправьте значение |
invalid_profiles | 400 | social.profiles не объект или other не массив | исправьте профили |
invalid_entries_per_page | 400 | не от 1 до 10 000 | исправьте число |
sitemap_composition_readonly | 400 | прислан sitemap.post_types или sitemap.taxonomies | состав карты задают noindex.post_types и noindex.taxonomies |
invalid_index_now_key | 400 | index_now.key не 8–128 знаков a-f0-9 и не "auto" | исправьте ключ |
index_now_key_missing | 400 | index_now.enabled: true без ключа | пришлите key |
index_now_unsupported | 409 | index_now.enabled: true | отправляйте адреса через PUT /data/seo.indexnow |
yoast_missing | 409 | SEO-настройки на сайте недоступны | — |
Прочитать карточку приложения
GET /data/seo.app
Возвращает карточку приложения и варианты значений app.choices. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.app" -H "Authorization: Bearer $OP_TOKEN"
Параметр адресации передается в строке запроса; тела нет.
Ответ
{
"success": true,
"name": "seo.app",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "SITE_ID",
"app": {
"enabled": true,
"name": "Example",
"category": "BrowserApplication",
"operating_systems": [],
"currency": "USD",
"rating_value": null,
"rating_count": null
}
}
]
}
Поля карточки — в описании записи.
Ошибки
Общие коды — на странице «Ошибки».
Изменить карточку приложения
PATCH /data/seo.app
Карточка приложения — узел SoftwareApplication на главной. Подробнее в гайде.
curl -s -X PATCH "$API/site/$SITE/data/seo.app" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"name": "Example", "category": "WebApplication", "operating_systems": ["Chrome", "Windows"], "price": 0, "currency": "USD", "rating_value": 4.8, "rating_count": 127}'
Тело запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
enabled | bool | нет | true | выводить узел; выключенный не выводится при любых полях |
name | string | нет | — | название приложения, обязательно для вывода |
description | string | нет | — | описание |
category | string | нет | BrowserApplication | applicationCategory, одно из choices.category |
operating_systems | string[] | нет | [] | платформы из choices.operating_systems: Chrome, Firefox, Edge, Safari, Opera, Brave, Windows, macOS, Linux, Android, iOS; выходят строкой через запятую |
price | number | нет | — | цена, 0 и больше; 0 — бесплатно |
currency | string | нет | USD | валюта из choices.currency |
rating_value | number | нет | — | оценка от 1 до 5, обязательна для вывода |
rating_count | integer | нет | — | число оценок, от 1, обязательно для вывода |
Ответ
Тема выводит узел, когда карточка включена и заполнены name, rating_value и rating_count; картинка узла — иконка сайта. PATCH принимает любое подмножество полей, null или "" очищают поле.
{
"success": true,
"name": "seo.app",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "x9HTLHECq",
"changed": [
"name",
"category",
"operating_systems",
"price",
"rating_value",
"rating_count"
],
"app": {
"enabled": true,
"name": "Example",
"description": "",
"category": "WebApplication",
"operating_systems": [
"Chrome",
"Windows"
],
"price": 0,
"currency": "USD",
"rating_value": 4.8,
"rating_count": 127,
"image": "https://example.com/…/icon-512.png",
"missing": [],
"output": true,
"choices": {
"category": {
"BrowserApplication": "Browser Application",
"BusinessApplication": "Business Application",
"EducationalApplication": "Educational Application",
"UtilitiesApplication": "Utilities Application",
"WebApplication": "Web Application"
},
"operating_systems": {
"Chrome": "Google Chrome",
"Windows": "Windows",
"…": "…"
},
"currency": {
"USD": "USD",
"EUR": "EUR",
"GBP": "GBP",
"RUB": "RUB"
}
}
},
"cache": {
"…": "…"
}
}
]
}
GET отдает app в той же форме без changed и cache. missing — каких из трех обязательных полей не хватает, output — выйдет ли узел на главной, choices — допустимые значения, их задает тема сайта. changed называет только реально изменившиеся поля; после записи кэш страниц сбрасывается, узел виден на главной сразу.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
nothing_to_change | 400 | в теле ни одного поля | пришлите хотя бы одно |
unknown_field | 400 | поле вне списка | уберите поле |
invalid_enabled | 400 | не да/нет | пришлите true или false |
invalid_name, invalid_description | 400 | не строка | пришлите строку |
invalid_category, invalid_currency | 400 | значение вне choices | возьмите значение из choices |
invalid_operating_systems | 400 | не массив строк или платформа вне choices | возьмите ключи из choices.operating_systems |
invalid_price, invalid_rating_value, invalid_rating_count | 400 | число вне диапазона | исправьте число |
theme_fields_missing | 409 | тема сайта не знает настроек приложения | — |
Прочитать состояние карты
GET /data/seo.sitemap
Возвращает сведения Search Console и Вебмастера о карте сайта. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.sitemap" -H "Authorization: Bearer $OP_TOKEN"
Параметр адресации передается в строке запроса; тела нет.
Ответ
{
"success": true,
"name": "seo.sitemap",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "SITE_ID",
"sitemap": "https://example.com/sitemap_index.xml",
"gsc": {
"state": "not_submitted",
"known": []
},
"ywm": {
"state": "not_added",
"known": []
}
}
]
}
Поля сервисов и состояния — в описании отправки карты.
Ошибки
Общие коды — на странице «Ошибки».
Отправить карту сайта
PUT /data/seo.sitemap
GET отдает, что Search Console и Вебмастер знают о карте сайта sitemap_index.xml; POST отправляет карту в подключенные консоли. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.sitemap" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"service": "all"}'
Тело запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
service | string | нет | all | gsc, ywm или all |
sitemap_url | string | нет | карта сайта | абсолютный адрес карты |
Ответ
Отправляет сам сайт через подключенную аналитику.
{
"success": true,
"name": "seo.sitemap",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "x9HTLHECq",
"service": "all",
"sitemap": "https://example.com/sitemap_index.xml",
"gsc": {
"state": "submitted",
"sitemap": "https://example.com/sitemap_index.xml"
},
"ywm": {
"state": "already",
"already": true,
"sitemap": "https://example.com/sitemap_index.xml",
"sitemap_id": "d1a3d870-ab57-32f5-bc04-fec6d92f3bb2"
}
}
]
}
Ответ по каждому сервису, поле state. Google при чтении: submitted (last_submitted, last_downloaded, is_pending, errors, warnings) или not_submitted (known — какие карты Google знает); при отправке — submitted, Google перечитает карту. Яндекс при чтении: added (sitemap_id, added_date) или not_added (known); при отправке — added или already: отдельного «перечитай» у Вебмастера нет, добавленные карты он обходит сам. Отказ сервиса — тоже state: not_connected (не подключен), not_verified (сайт не подтвержден, 401/403), api_error (code, message — как ответил сервис). Итог проверки несет то же состояние в sitemap.consoles.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
invalid_service | 400 | service не gsc, ywm или all | исправьте значение |
invalid_sitemap_url | 400 | не абсолютный адрес http(s) | пришлите полный адрес |
Прочитать адреса карты
GET /data/seo.sitemap.urls
Отдает все адреса, которые сайт отдает поисковикам в карте: индекс sitemap_index.xml и каждую дочернюю карту из него. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.sitemap.urls" -H "Authorization: Bearer $OP_TOKEN"
Параметр адресации передается в строке запроса; тела нет.
Ответ
Список читается с самого сайта в момент запроса и совпадает с XML строка в строку, в том же порядке.
{
"success": true,
"name": "seo.sitemap.urls",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "x9HTLHECq",
"sitemap": "https://example.com/sitemap_index.xml",
"total": 73,
"sitemaps": [
{
"url": "https://example.com/page-sitemap.xml",
"path": "/page-sitemap.xml",
"lastmod": "2026-10-03T10:30:00+00:00",
"status": 200,
"count": 73
}
],
"urls": [
{
"loc": "https://example.com/",
"images": 0,
"lastmod": "2026-09-12T17:48:01+00:00",
"sitemap": "/page-sitemap.xml"
},
{
"loc": "https://example.com/primery/",
"images": 2,
"lastmod": "2026-09-12T18:04:47+00:00",
"sitemap": "/page-sitemap.xml"
}
],
"took_ms": 516
}
]
}
total — сколько адресов в картах; у дочерней карты, которая не ответила, — error и count: 0; images — сколько картинок у адреса в карте.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
sitemap_unavailable | 502 | индекс карты не ответил; sitemap, status, при обрыве — reason | проверьте карту в GET /data/seo и повторите |
site_home_missing | 409 | у сайта нет адреса | — |
Прочитать robots.txt
GET /data/seo.robots
Возвращает текст robots.txt и признаки его состояния. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.robots" -H "Authorization: Bearer $OP_TOKEN"
Параметр адресации передается в строке запроса; тела нет.
Ответ
{
"success": true,
"name": "seo.robots",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "SITE_ID",
"content": "User-agent: *\n",
"url": "https://example.com/robots.txt",
"site_closed": false,
"custom": false,
"default_content": "User-agent: *\n"
}
]
}
custom показывает наличие собственного текста, default_content — шаблон сайта.
Ошибки
Общие коды — на странице «Ошибки».
Записать robots.txt
PUT /data/seo.robots
GET отдает robots.txt, который сайт отдает сейчас, PUT записывает свой текст, DELETE возвращает общий шаблон сети: закрыты служебные разделы, ленты, поиск, /page/, плюс Sitemap: своей карты. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.robots" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"content": "User-agent: *\nDisallow: /private/\n"}'
Тело запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
content | string | да | — | PUT: текст файла до 64 КБ, обязательно |
Ответ
Свой текст отдается как есть, строка Sitemap: дописывается, только если ее в тексте нет.
{
"success": true,
"name": "seo.robots",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "x9HTLHECq",
"content": "User-agent: *\nDisallow: /private/\n\nSitemap: https://example.com/sitemap_index.xml\n",
"custom": true,
"default_content": "User-agent: *\n…",
"url": "https://example.com/robots.txt",
"site_closed": false,
"changed": true,
"warnings": []
}
]
}
Строка — пустая, # комментарий или Директива: значение. Незнакомая директива, правило до первого User-agent и Sitemap не абсолютным адресом запись не останавливают — они в warnings (line, text, message). У закрытого сайта robots.txt отдает User-agent: * / Disallow: / без Sitemap: (site_closed: true), свой текст сохраняется и возвращается при открытии.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
invalid_robots | 400 | строка не той формы; errors (line, text, message) и warnings | исправьте строки |
invalid_content | 400 | не строка или управляющие символы | пришлите текст |
empty_content | 400 | пустой текст | вернуть шаблон — DELETE /data/seo.robots |
too_large | 413 | больше 64 КБ; limit | сократите текст |
Вернуть шаблон robots.txt
DELETE /data/seo.robots
Возвращает шаблон robots.txt. Подробнее в гайде.
curl -s -X DELETE "$API/site/$SITE/data/seo.robots" -H "Authorization: Bearer $OP_TOKEN"
Дополнительных полей строки запроса нет.
Ответ
{
"success": true,
"name": "seo.robots",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "SITE_ID",
"content": "User-agent: *\n",
"url": "https://example.com/robots.txt",
"site_closed": false,
"custom": false,
"default_content": "User-agent: *\n",
"changed": true
}
]
}
Ошибки
Общие коды — на странице «Ошибки».
Прочитать llms.txt
GET /data/seo.llms
Возвращает текст llms.txt и признаки его состояния. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.llms" -H "Authorization: Bearer $OP_TOKEN"
Параметр адресации передается в строке запроса; тела нет.
Ответ
{
"success": true,
"name": "seo.llms",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "SITE_ID",
"content": "# Example\n",
"url": "https://example.com/llms.txt",
"site_closed": false,
"exists": true,
"auto": false
}
]
}
exists показывает наличие файла, auto — автоматическое обновление собранного текста.
Ошибки
Общие коды — на странице «Ошибки».
Записать llms.txt
PUT /data/seo.llms
GET отдает llms.txt сайта, PUT записывает свой текст, DELETE снимает текст — /llms.txt снова отвечает 404. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.llms" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"content": "# Example\n\n## Pages\n\n- [Тарифы](https://example.com/pricing.md): цены и планы.\n"}'
Тело запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
content | string | да | — | PUT: текст файла до 64 КБ, обязательно |
Ответ
Своего умолчания нет: без текста файл отвечает 404, собрать его по страницам — PUT /data/seo.llms.build.
Ответ: content, exists, auto (текст собран сборкой и пересобирается сам), url, site_closed; у записи — еще changed и warnings (первая строка не # Название — предупреждение). Свой текст, сохраненный PUT, автоматическим не бывает и сам не меняется; вернуть автоматику — снова вызвать сборку. У закрытого сайта /llms.txt отвечает 404, что бы ни было сохранено.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
invalid_content | 400 | не строка или управляющие символы | пришлите текст |
empty_content | 400 | пустой текст | снять текст — DELETE /data/seo.llms |
too_large | 413 | больше 64 КБ; limit | сократите текст |
Удалить llms.txt
DELETE /data/seo.llms
Удаляет текст llms.txt. Подробнее в гайде.
curl -s -X DELETE "$API/site/$SITE/data/seo.llms" -H "Authorization: Bearer $OP_TOKEN"
Дополнительных полей строки запроса нет.
Ответ
После удаления публичный файл отвечает 404.
{
"success": true,
"name": "seo.llms",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "SITE_ID",
"content": "",
"url": "https://example.com/llms.txt",
"site_closed": false,
"exists": false,
"auto": false,
"changed": true
}
]
}
Ошибки
Общие коды — на странице «Ошибки».
Показать результат сборки llms.txt
GET /data/seo.llms.build
Собирает предварительный текст llms.txt без записи. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.llms.build" -H "Authorization: Bearer $OP_TOKEN"
Параметр адресации передается в строке запроса; тела нет.
Ответ
{
"success": true,
"name": "seo.llms.build",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "SITE_ID",
"content": "# Example\n",
"pages": 1,
"bytes": 10,
"saved": false,
"dry_run": true,
"url": "https://example.com/llms.txt"
}
]
}
Состав страниц и ограничения — в описании сборки.
Ошибки
Общие коды — на странице «Ошибки».
Собрать llms.txt
PUT /data/seo.llms.build
Собирает llms.txt в формате llmstxt.org по опубликованным страницам всех языков и сохраняет; GET /data/seo.llms.build или {"dry_run": true} показывают результат без записи. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.llms.build" -H "Authorization: Bearer $OP_TOKEN"
Тело запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
dry_run | bool | нет | false | показать текст без записи |
Ответ
Каждая ссылка ведет на markdown-копию страницы — адрес с .md. Собрать разом llms.txt и все markdown-копии — PUT /data/seo.markdown.
{
"success": true,
"name": "seo.llms.build",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "x9HTLHECq",
"content": "# Example\n\n## Pages\n\n- [Тарифы](https://example.com/pricing.md): …",
"pages": 60,
"bytes": 18140,
"saved": true,
"dry_run": false,
"url": "https://example.com/llms.txt"
}
]
}
Не попадают страницы с noindex, без фрейма, под паролем, служебная 404 и страницы с неопубликованным родителем. Разделы: сначала страницы без раздела, потом по разделу на каждую корневую страницу с детьми, в конце записи. До 600 ссылок, из них записей до 100; если текст не укладывается в 64 КБ, сначала укорачиваются описания, потом хвосты разделов. Собранный текст помечается auto: true и пересобирается сам после каждой публикации, правки, снятия с публикации, переноса и удаления страницы. Флаг «не индексировать сайт» сборку не останавливает.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
too_large | 413 | собранный текст не уложился в 64 КБ | закройте лишние страницы noindex |
Прочитать состояние IndexNow
GET /data/seo.indexnow
Возвращает состояние ключа, файла подтверждения и последние отправки. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.indexnow" -H "Authorization: Bearer $OP_TOKEN"
Параметр адресации передается в строке запроса; тела нет.
Ответ
{
"success": true,
"name": "seo.indexnow",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "SITE_ID",
"host": "example.com",
"endpoint": "https://api.indexnow.org/indexnow",
"key": {
"configured": true,
"location": "https://example.com/KEY.txt",
"served": true
},
"log": []
}
]
}
key содержит configured, source, location, served; при ошибке файла — status и error. log содержит последние 50 отправок.
Ошибки
Общие коды — на странице «Ошибки».
Отправить адреса в IndexNow
PUT /data/seo.indexnow
POST бесплатно отправляет адреса сайта в IndexNow, оттуда их получают Bing, Яндекс, Seznam, Naver и другие участники протокола; GET отдает ключ, файл подтверждения на домене и журнал последних отправок. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.indexnow" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"urls": ["https://example.com/", "/pricing/"]}'
Тело запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
urls | array | нет | — | полные адреса или пути сайта (/about/), до 50 000; нужен urls или all |
all | bool | нет | false | все опубликованные страницы всех языков, кроме закрытых noindex и паролем (skipped_hidden — сколько пропущено) |
dry_run | bool | нет | false | проверить адреса и ключ без отправки |
Ответ
Ключ один на сеть, файл https://<домен>/<ключ>.txt сайт отдает сам и перед отправкой проверяет. Автоотправки при публикации нет.
{
"success": true,
"name": "seo.indexnow",
"origin": "system",
"total": 1,
"items": [
{
"site_id": "x9HTLHECq",
"host": "example.com",
"mode": "urls",
"dry_run": false,
"count": 2,
"sent": 2,
"rejected": [],
"batches": [
{
"count": 2,
"status": 200,
"ok": true,
"took_ms": 412
}
],
"key_location": "https://example.com/01a6….txt"
}
]
}
Адрес чужого хоста, в том числе www-варианта, не уходит, а возвращается в rejected с причиной (foreign_host, invalid_url, invalid_scheme, not_a_string). Адреса уходят пачками по 10 000. GET отдает host, endpoint, key (configured, source, location, served; файл не отдается — status и error: http_status — домен ответил не 200, content_mismatch — в файле другой ключ, timeout, unreachable) и log — последние 50 отправок.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
urls_required | 400 | нет ни urls, ни all | передайте одно из двух |
conflicting_fields | 400 | переданы и urls, и all | оставьте одно |
invalid_urls | 400 | urls не массив | пришлите массив |
no_urls | 400 | ни одного адреса этого сайта; host, rejected | проверьте домен в адресах |
too_many_urls | 413 | больше 50 000 адресов | разбейте на части |
indexnow_not_configured | 409 | у сети нет ключа IndexNow | — |
indexnow_key_file_missing | 409 | файл ключа не отдается с домена | проверьте key в GET /data/seo.indexnow |
indexnow_bad_request, indexnow_key_rejected, indexnow_url_rejected, indexnow_quota, indexnow_network | 502 | IndexNow отказал или не ответил; batches | повторите позже |
Прочитать настройки проверки позиций
GET /data/seo.serp
Позиции сайта в выдаче Google и Яндекса по запросам снимает SerpApi; на этих эндпоинтах стоит страница «Позиции» раздела SEO консоли. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.serp" -H "Authorization: Bearer $OP_TOKEN"
Параметры запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
refresh | 1 | нет | — | Перечитать остаток поисков своего ключа без расхода поисков. |
Ответ
API отдает способ съема, плановую проверку, маску ключа, цену, лимиты и расход. Способ, свой ключ и суточные счетчики принадлежат владельцу токена и общие для всех его сайтов; запросы и история позиций принадлежат сайту.
{
"success": true,
"name": "seo.serp",
"origin": "system",
"total": 1,
"items": [
{
"mode": "credits",
"auto": false,
"key": null,
"platform": {
"configured": true
},
"credits": {
"action": "serp_position",
"price": 1,
"available": 20,
"balance": 20,
"topup_path": "/settings/credits"
},
"limits": {
"max_queries_per_site": 50,
"max_checks_per_day": 50,
"manual_cooldown_minutes": 60,
"manual_checks_per_hour": 10,
"min_interval_days": 7,
"platform_max_depth": 30,
"own_max_depth": 100,
"concurrency": 2,
"queue_max": 20
},
"budget": {
"mode": "credits",
"auto": false,
"queries_total": 0,
"planned_checks_month": 0,
"planned_checks_month_site": 0,
"checks_today": 0,
"manual_last_hour": 0,
"price": 1,
"planned_credits_month": 0,
"credits_available": 20,
"credits_known": true,
"allowance_today": 50
}
}
]
}
Способы. За кредиты кредит сначала резервируется, списывается после сохранения позиции, в том числе когда сайт не нашелся в пределах глубины, и возвращается, если съем не удался. Один поиск — страница из десяти результатов; съем останавливается, как только нашелся адрес сайта или его поддомена, поэтому позиция в топ-10 стоит один поиск, а запрос глубиной 30 — до трех. Позиция за пределами глубины сохраняется как position: null. Плановая проверка использует интервалы запросов и доступные лимиты аккаунта.
| Лимит | Предел |
|---|---|
| запросов на сайт | 50 |
| снятых позиций в сутки на пользователя | 50 — плановые и ручные вместе, сутки по UTC |
| как часто снимается запрос | interval_days от 7 до 90 |
| ручная проверка одного запроса | раз в 60 минут |
| ручных проверок на пользователя | 10 в час, по одной за раз |
| глубина | за кредиты — до 30, свой ключ — до 100 |
| одновременных съемов на сервере | 2, еще 20 ждут в очереди |
platform.configured — есть ли на сервере ключ платформы; credits — цена позиции, баланс и страница пополнения. budget: queries_total (запросов на всех сайтах пользователя), planned_checks_month и planned_checks_month_site, checks_today, manual_last_hour, allowance_today; за кредиты — price, planned_credits_month, credits_available, credits_known; своим ключом — searches_total, searches_left, searches_used, days_left, reserve, per_day, spent_today, planned_searches_month, planned_searches_until_reset, fits и max_queries_weekly.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
invalid_mode | 422 | не credits и не own | исправьте значение |
invalid_auto | 422 | не bool | пришлите true или false |
own_key_required | 409 | own без привязанного ключа | привяжите ключ PUT /data/seo.serp.key |
Изменить настройки проверки позиций
PUT /data/seo.serp
Позиции сайта в выдаче Google и Яндекса по запросам снимает SerpApi; на этих эндпоинтах стоит страница «Позиции» раздела SEO консоли. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.serp" -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' -d '{"mode": "credits", "auto": false}'
Тело запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
mode | string | нет | credits | credits — ключ платформы, 1 кредит за снятую позицию; own — свой ключ SerpApi, платформа ничего не списывает |
auto | bool | нет | false | плановая проверка по interval_days; смена mode без auto переключает и ее: own включает, credits выключает |
Ответ
GET отдает способ съема, плановую проверку, свой ключ, цену, лимиты и расход, PUT меняет способ и плановую проверку. Способ, свой ключ и суточные счетчики принадлежат владельцу токена и общие для всех его сайтов; запросы и история позиций принадлежат сайту.
{
"success": true,
"name": "seo.serp",
"origin": "system",
"total": 1,
"items": [
{
"mode": "credits",
"auto": false,
"key": null,
"platform": {
"configured": true
},
"credits": {
"action": "serp_position",
"price": 1,
"available": 20,
"balance": 20,
"topup_path": "/settings/credits"
},
"limits": {
"max_queries_per_site": 50,
"max_checks_per_day": 50,
"manual_cooldown_minutes": 60,
"manual_checks_per_hour": 10,
"min_interval_days": 7,
"platform_max_depth": 30,
"own_max_depth": 100,
"concurrency": 2,
"queue_max": 20
},
"budget": {
"mode": "credits",
"auto": false,
"queries_total": 0,
"planned_checks_month": 0,
"planned_checks_month_site": 0,
"checks_today": 0,
"manual_last_hour": 0,
"price": 1,
"planned_credits_month": 0,
"credits_available": 20,
"credits_known": true,
"allowance_today": 50
}
}
]
}
Способы. За кредиты кредит сначала резервируется, списывается после сохранения позиции, в том числе когда сайт не нашелся в пределах глубины, и возвращается, если съем не удался. Один поиск — страница из десяти результатов; съем останавливается, как только нашелся адрес сайта или его поддомена, поэтому позиция в топ-10 стоит один поиск, а запрос глубиной 30 — до трех. Позиция за пределами глубины сохраняется как position: null. Плановая проверка использует интервалы запросов и доступные лимиты аккаунта.
| Лимит | Предел |
|---|---|
| запросов на сайт | 50 |
| снятых позиций в сутки на пользователя | 50 — плановые и ручные вместе, сутки по UTC |
| как часто снимается запрос | interval_days от 7 до 90 |
| ручная проверка одного запроса | раз в 60 минут |
| ручных проверок на пользователя | 10 в час, по одной за раз |
| глубина | за кредиты — до 30, свой ключ — до 100 |
| одновременных съемов на сервере | 2, еще 20 ждут в очереди |
platform.configured — есть ли на сервере ключ платформы; credits — цена позиции, баланс и страница пополнения. budget: queries_total (запросов на всех сайтах пользователя), planned_checks_month и planned_checks_month_site, checks_today, manual_last_hour, allowance_today; за кредиты — price, planned_credits_month, credits_available, credits_known; своим ключом — searches_total, searches_left, searches_used, days_left, reserve, per_day, spent_today, planned_searches_month, planned_searches_until_reset, fits и max_queries_weekly.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
invalid_mode | 422 | не credits и не own | исправьте значение |
invalid_auto | 422 | не bool | пришлите true или false |
own_key_required | 409 | own без привязанного ключа | привяжите ключ PUT /data/seo.serp.key |
Подключить ключ SerpApi
PUT /data/seo.serp.key
PUT привязывает свой ключ SerpApi — один на пользователя для всех сайтов, новый заменяет прежний; DELETE отвязывает: способ возвращается на credits, плановая проверка своим ключом выключается, история позиций остается. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.serp.key" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"api_key": "ВАШ_КЛЮЧ_SERPAPI"}'
Тело запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
api_key | string | да | — | приватный ключ SerpApi, от 32 до 128 латинских букв и цифр, обязательно |
Ответ
При привязке ключ проверяется бесплатным запросом сведений об аккаунте SerpApi.
Ответ — как у GET /data/seo.serp. Ключ хранится зашифрованным и обратно не отдается: key — mask (•••• и последние четыре знака), status (ok, exhausted — поиски кончились, invalid — SerpApi ключ не принимает), status_message, plan, searches_total, searches_left, searches_used, hourly_limit, renewal_date, refreshed_at.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
invalid_api_key | 422 | ключ не той формы или SerpApi его отверг | проверьте ключ в кабинете SerpApi |
serpapi_unavailable | 502 | SerpApi не ответил на проверку | повторите запрос |
key_not_found | 404 | DELETE: отвязывать нечего | — |
serp_key_unreadable | 500 | сохраненный ключ не расшифровался | привяжите ключ заново |
serp_not_configured | 503 | на сервере не настроено хранение ключей | — |
Отключить ключ SerpApi
DELETE /data/seo.serp.key
Отключает ключ SerpApi и возвращает режим credits, сохраняя запросы и историю. Подробнее в гайде.
curl -s -X DELETE "$API/site/$SITE/data/seo.serp.key" -H "Authorization: Bearer $OP_TOKEN"
Дополнительных полей строки запроса нет.
Ответ
{
"success": true,
"name": "seo.serp.key",
"origin": "system",
"total": 1,
"items": [
{
"mode": "credits",
"auto": false,
"key": null
}
]
}
Форма ответа — как у чтения настроек.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
key_not_found | 404 | Ключ не привязан. | Прочитайте настройки. |
Прочитать поисковые запросы
GET /data/seo.serp.queries
Возвращает запросы сайта с позициями, историей и расходом. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.serp.queries" -H "Authorization: Bearer $OP_TOKEN"
Параметр адресации передается в строке запроса; тела нет.
Ответ
{
"success": true,
"name": "seo.serp.queries",
"origin": "system",
"total": 1,
"items": [
{
"depths": [
10,
20,
30
],
"limits": {
"max_queries_per_site": 50
},
"queries": [],
"budget": {
"queries_total": 0
}
}
]
}
Поля queries[] — в описании добавления запроса.
Ошибки
Общие коды — на странице «Ошибки».
Добавить поисковый запрос
PUT /data/seo.serp.queries
GET отдает запросы сайта с последней позицией, изменением и историей, POST добавляет запрос. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.serp.queries" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"query": "чат бот онлайн", "lang": "ru"}'
Тело запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
query | string | да | — | текст от 2 до 400 знаков, обязательно |
lang | string | нет | — | язык страницы; из него берутся страна и язык выдачи: ru → ru/ru, en → us/en; без него — us/en |
gl, hl | string | нет | из lang | страна (две буквы) и язык выдачи |
engine | string | нет | google | google или yandex |
device | string | нет | desktop | desktop или mobile |
depth | int | нет | 30 | 10, 20, 30, 50 или 100; за кредиты — не больше 30 |
interval_days | int | нет | 7 | от 7 до 90 |
page_id | int | нет | — | страница сайта, к которой относится запрос |
Ответ
{
"success": true,
"name": "seo.serp.queries",
"origin": "system",
"total": 1,
"items": [
{
"query": {
"id": 23,
"query": "чат бот онлайн",
"engine": "google",
"gl": "ru",
"hl": "ru",
"device": "desktop",
"lang": "ru",
"page_id": null,
"source": "manual",
"depth": 30,
"interval_days": 7,
"last_checked_at": null,
"last_error": "",
"checked": false,
"position": null,
"url": null,
"previous_position": null,
"delta": null,
"history": [],
"expected_searches_per_month": 12.9
}
}
]
}
Ответ GET: queries (сначала взятые из ключей страниц), depths — глубины, доступные в текущем способе, limits, budget. У запроса: source (page — из ключа страницы, manual — добавлен руками), checked, position и url последнего съема, previous_position, delta (положительное — поднялся; null, если одна из позиций вне топа), history — последние 12 съемов {at, position}, expected_searches_per_month.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
invalid_query, invalid_engine, invalid_gl, invalid_hl, invalid_depth | 422 | значение не той формы; поле — в field | исправьте поле |
depth_not_allowed | 422 | глубже 30 за кредиты; max | уменьшите глубину или привяжите свой ключ |
invalid_interval | 422 | не целое от 7 до 90; min | исправьте интервал |
query_exists | 409 | такой запрос с тем же поисковиком, страной, языком и устройством уже есть; id | — |
too_many_queries | 409 | на сайте уже 50 запросов; limit | снимите ненужный |
Удалить поисковый запрос
DELETE /data/seo.serp.queries
Снимает запрос вместе с историей позиций и отвечает {"success": true, "name": "seo.serp.queries", "origin": "system", "total": 1, "items": [{"id": 23}]}. Подробнее в гайде.
curl -s -X DELETE "$API/site/$SITE/data/seo.serp.queries" -H "Authorization: Bearer $OP_TOKEN" \
-H 'Content-Type: application/json' -d '{"id": "23"}'
Поля адресации в теле запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
id | string | да | — | Id ресурса из ответа чтения. |
Дополнительных полей строки запроса нет.
Ответ
Снимает запрос вместе с историей позиций и отвечает {"success": true, "name": "seo.serp.queries", "origin": "system", "total": 1, "items": [{"id": 23}]}. Подробнее в гайде.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
query_not_found | 404 | запроса нет на этом сайте | возьмите id из GET /data/seo.serp.queries |
Взять запросы из ключей страниц
PUT /data/seo.serp.sync
Берет первый ключ каждой опубликованной страницы (свойство focus_keyword) и заводит запрос на языке страницы. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.serp.sync" -H "Authorization: Bearer $OP_TOKEN"
Дополнительных полей строки запроса нет.
Ответ
Запросы, чей ключ со страницы пропал, выключаются, история остается; сверх 50 запросов на сайт не добавляет.
Ответ: pages_with_keyword, added, kept, disabled, skipped_over_limit, limit. Своих отказов нет.
Ошибки
Общие коды — на странице «Ошибки».
Прочитать историю позиций
GET /data/seo.serp.positions?id={id}
Отдает query и positions от старых к новым: at, position (null — вне топа), url — найденный адрес сайта, searches — сколько поисков ушло. Подробнее в гайде.
curl -s "$API/site/$SITE/data/seo.serp.positions?id=23&limit=100" -H "Authorization: Bearer $OP_TOKEN"
Параметры запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
id | string | да | — | Id ресурса из ответа чтения. |
Параметры запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
limit | int | нет | 100 | сколько съемов, не больше 500 |
Ответ
Отдает query и positions от старых к новым: at, position (null — вне топа), url — найденный адрес сайта, searches — сколько поисков ушло. Подробнее в гайде.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
query_not_found | 404 | запроса нет на этом сайте | возьмите id из GET /data/seo.serp.queries |
Проверить позицию запроса
PUT /data/seo.serp.check
Снимает позицию сразу; платит тот, кто вызвал: кредитом или поиском своего ключа. Подробнее в гайде.
curl -s -X PUT "$API/site/$SITE/data/seo.serp.check" -H "Authorization: Bearer $OP_TOKEN" \
-H 'Content-Type: application/json' -d '{"id": "23"}'
Поля адресации в теле запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
id | string | да | — | Id ресурса из ответа чтения. |
Дополнительных полей строки запроса нет.
Ответ
Ответ: searches, credits (1 за кредиты, 0 своим ключом), mode и query с новой позицией.
При любом отказе ничего не снято и не списано; причина последнего отказа, кроме лимитов и нехватки кредитов, остается в last_error запроса.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
insufficient_credits | 402 | не хватает кредитов; required, available, topup_path | пополните баланс |
check_cooldown | 429 | запрос проверяли руками меньше 60 минут назад; retry_after_sec, cooldown_minutes | подождите |
manual_hourly_limit | 429 | 10 ручных проверок за час; retry_after_sec | подождите |
daily_limit_reached | 429 | 50 позиций за сутки; limit, used | дождитесь 00:00 UTC |
queue_full | 429 | очередь сервера полна; retry_after_sec | повторите через минуту |
check_in_progress | 409 | идет другая ваша проверка | дождитесь ее |
no_own_key | 409 | способ own без ключа | привяжите ключ |
invalid_api_key | 409 | привязанный ключ перестал работать | привяжите рабочий |
no_searches_left | 409 | поиски кончились, в том числе посреди съема — тогда результат не сохраняется | дождитесь сброса тарифа |
serpapi_failed | 502 | SerpApi не справился; kind: throttled, network, failed | повторите позже |
platform_key_missing | 503 | на сервере не настроен ключ платформы | снимайте своим ключом |
credits_unavailable | 503 | кредиты недоступны | повторите позже |
query_not_found | 404 | запроса нет на этом сайте | — |
Пункты проверки
Своего хранилища у чеклиста нет: все, что он показывает, лежит в настройках сайта, SEO-настройках, теме и страницах и правится там же. Пункты canonical, redirects, not-found и карта сайта собраны в один tech-basics, Метрика, GA4, Search Console и Вебмастер — в counters, проверки H1 и уровней — в headings. Пункты группы Languages есть только на многоязычном сайте; на одноязычном homes стоит последним пунктом «Основы».
| Пункт | Группа | Что проверяет | Чем чинить |
|---|---|---|---|
identity | Basics | название сайта | PUT /data/settings/name |
site-icon | Basics | иконка сайта: favicon и логотип организации в разметке | PUT /data/settings/icon |
homes | Basics | у каждого языка опубликованная главная | PUT /data/site.front_page, перевод главной |
counters | Indexing | Метрика, GA4, Search Console, Вебмастер; статус — худший из четырех | PUT /data/settings/{field}, поля metrika, ga, gsc, webmaster |
tech-basics | Indexing | карта сайта XML, canonical на саму страницу, 301 после переноса, 404 с noindex | карта — PATCH /data/seo sitemap.enabled; остальное платформа делает сама |
auto-sitemap-hreflang, auto-hreflang, auto-x-default | Languages | карта с альтернативами языков, hreflang с обратными ссылками, x-default на основной язык | делает платформа |
schema-website | Markup | WebSite на главной: name, url, description | описание — PATCH /data/site.settings |
schema-organization | Markup | Organization на главной: name, url, logo, желательно sameAs | PATCH /data/site.organization, PATCH /data/site.socials |
schema-page | Markup | WebPage главной и Article первой статьи | свойство seo_description, набор author |
schema-author | Markup | Person автора статьи и ProfilePage | PUT /data/author |
schema-breadcrumbs | Markup | BreadcrumbList с name у каждого звена | вложенность страниц: свойство url с родителем |
schema-howto | Markup | HowTo с шагами по порядку | фрейм howto или текст страницы |
schema-faq | Markup | FAQPage, один узел на страницу | блок вопросов на странице |
schema-app | Markup | SoftwareApplication: name и offers или aggregateRating | PATCH /data/seo.app |
schema-og | Markup | og:title, og:description, og:url, og:type, og:image, twitter:card | PATCH /data/seo social |
auto-webp | Speed | картинки отдаются в WebP | делает платформа |
auto-lcp-preload | Speed | preload и fetchpriority="high" у картинки первого экрана | делает платформа |
auto-web-vitals | Speed | LCP, INP, CLS домена из Chrome UX Report | — |
page-cache | Speed | страницы отдаются из кэша | делает платформа |
keywords | Pages | ключ страницы стоит в <title> и meta description | свойства seo_title, seo_description |
pages-meta | Pages | у страниц есть <title> и meta description | seo_title, seo_description |
pages-length | Pages | title не длиннее 65 знаков, описание — 165 | seo_title, seo_description |
headings | Pages | ровно один H1 и уровни без пропусков | тело страницы |
pages-noindex | Pages | какие страницы закрыты noindex | свойство noindex |
images-alt | Pages | у картинок тела есть alt |  в теле страницы |
contacts | Pages | политика, условия, контакты и контакты в подвале по каждому языку | публикация страниц, набор footer |
Страницы чинит публикация Markdown с нужными свойствами или текстом — POST /pages/markdown или точечно PATCH /pages/{ref}/markdown. Готовые команды по каждой странице — в fix пункта, до 25 страниц; сайт в них назван в пути, /site/{site_id}/…, а настройки сайта правятся через данные — site.settings, site.organization, site.socials. Например, вписать ключ в title и описание страницы 6949:
curl -s -X POST "$API/site/$SITE/pages/markdown" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"markdown": "---\nid: 6949\nfocus_keyword: \"чат бот\"\nseo_title: \"Чат бот онлайн без регистрации\"\nseo_description: \"Бесплатный чат бот: …\"\n---\n\n<тело из выгрузки без изменений>"}'
homes. Строка на язык: lang, is_default, id, title, url, status, reason. Строка в порядке, когда по / сайт показывает страницу, у языка она есть среди переводов главной, опубликована, у нее есть фрейм и ее адрес отвечает 200 без редиректа этой самой страницей. Иначе reason: posts (вместо страницы — лента записей), noPage (главной на языке нет), notPage, notPublished, noFrame, wrongPage (по адресу другая страница), redirect, closed (сайт закрыт), unreachable, http. Нет главной языка — POST /pages/markdown с translation_of: <id главной> и lang или привязка готовой страницы PATCH /data/translations; нет фрейма — PATCH /pages/{ref} с frame; по адресу другая страница или редирект — POST /cache/flush.
counters. «Метрика» в порядке, когда у сайта есть номер счетчика, «Google Analytics» — measurement ID, «Search Console» и «Вебмастер» — когда права подтверждены (verified: true). Строка в консоли ведет в «Аналитика → Счетчики».
tech-basics. В rows — строка на каждую часть, status ok или warn; сломано хоть что-то — весь пункт не ok. У строки карты — url индекса, count адресов (сумма <url> по дочерним картам живого индекса) и bots — когда боты последний раз забирали карту. Подтверждение остальных частей — signals.canonical, signals.redirects и signals.not_found обхода. На сайте публичны только страницы: архивов авторов, дат, вложений, рубрик и меток, их лент и типа записей post нет (он остается только там, где уже есть опубликованные записи) — такие адреса отвечают 404 и в карту сайта не попадают.
keywords. Проверяются опубликованные страницы обхода, у которых задан ключ — свойство focus_keyword; несколько ключей — через запятую, точку с запятой или с новой строки. Title и Description сверяются с отданной разметкой: фразой целиком по границам слов, без учета регистра и диакритики (é = e), кавычки, тире и знаки препинания отбрасываются; в китайском, японском, тайском и бирманском — вхождением без границ слов. Статус: все страницы с ключом в порядке — ok, есть нарушения — todo, ключ не задан ни у одной — na. Строка: id, title, lang, url, keywords, title_ok, description_ok (null, когда страница не открылась, причина в reason), missing, seen (title, description), status; нарушения идут первыми.
headings. В полях — «Ровно один H1: N из N» и «Уровни без пропусков: N из N», в pages — страницы с нарушениями, статус — худший из двух. problems[].kind: no_h1, many_h1 (count, text второго), jump — скачок уровня (from, to, text), рядом outline — лестница заголовков. Навигация, подвал и боковая колонка не учитываются; H1 — первая строка # … в теле или заголовок, который печатает фрейм.
images-alt. Картинки тела каждой открытой страницы обхода, без шапки, меню, подвала и боковой колонки. Нет атрибута alt — нарушение; alt="" засчитывается только декоративной картинке (role="presentation" или aria-hidden="true"). В rows — src, file, alt (null — атрибута нет, "" — пустой), page. Alt вписывается в тело страницы:  становится <img alt="alt">.
contacts. По каждому языку опубликованы политика конфиденциальности, условия использования и страница контактов, а в подвале главной — почта или телефон (mailto:, tel:) и ссылки на оба документа. Документ находится по слагу страницы языка: privacy, privacy-policy, polite, politika…, политика…; terms, terms-of-use, oferta, оферта; contacts, contact, kontakty, контакты. Строка: lang, is_default, privacy, terms, contacts ({id, title, url} или null), footer_contact, footer_legal, status, reason. Подвал из набора footer правится PUT /data/footer с тем же lang; набора нет — 404 source_not_found, подвал тогда задан фреймом.
Schema-разметка. Пункты schema-* показывают не настройки, а то, что сайт отдает: узлы JSON-LD и теги Open Graph, снятые с живых страниц без кук. Страницы-образцы: главная, первая статья (Article, BlogPosting, NewsArticle), страница с вопросами, страница автора (ProfilePage), страница с крошками и одна внутренняя. Статус: узел есть и обязательные поля заполнены — ok; обязательное поле пустое или ссылка {"@id": …} ведет на объект, которого нет на странице, — warn; узла нет, хотя он нужен, — todo; к сайту не относится — na; образец не открылся — unknown. В rows — строка на образец: page (home, article, faq, profile, breadcrumbs, app, inner), label, id, lang, url, status, title — тип узла, language (json или markup), code — узел как есть или мета-теги строками (null — узла нет), missing, recommended, refs, note. Код режется на 24 КБ.
Отдельные узлы. Organization строит кто-то один: пока в site.organization пусто name, узел выводит SEO-граф из раздела organization /data/seo с sameAs из social.profiles; как только name заполнено, сайт выводит узел из site.organization (логотип — иконка сайта, sameAs — site.socials), поле «Источник» говорит, какой действует. Person тема собирает из набора author только на страницах, чей фрейм объявил набор: набор есть, а Person не выводит ни одна страница — todo. BreadcrumbList строится по вложенности страниц, первое звено — главная языка; плоский сайт — na. HowTo печатает фрейм howto в теле страницы; без него платформа собирает узел из трех и больше подзаголовков «Шаг 1…» или нумерованного списка от трех пунктов под H2/H3 со словом инструкции, а шаги фрейма steps важнее текста. Два FAQPage или два HowTo на странице — warn.
Скорость. auto-webp — warn, если есть картинки не в WebP, в pages до 50 страниц (note — сколько картинок не в WebP), всего — pages_total. auto-web-vitals — по порогам CrUX по p75 (телефоны, если есть): все «хорошо» — ok, есть «нужно улучшить» — warn, есть «плохо» — todo (LCP хорошо ≤ 2,5 с, плохо > 4 с), данных нет — na. page-cache — главная и две страницы обхода по два захода без кук, второй обязан прийти из кэша; в rows — адрес, status, ttfb_ms.
Данные сайта для SEO
Название, иконка, описание, главная, счетчики, организация, соцсети, автор и подвал — это данные сайта, и пишутся они через /data; поля и отказы — на странице Настройки сайта. Например, заполнить описание сайта, которое идет в узел WebSite:
curl -s -X PATCH "$API/site/$SITE/data/site.settings" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"description": "Бесплатный ИИ-чат без регистрации"}'
| Что | Эндпоинт | Пункт проверки | Подробно |
|---|---|---|---|
| название сайта | PUT /data/settings/name | identity | поля настроек |
| иконка: favicon и логотип в разметке | PUT /data/settings/icon | site-icon | поля настроек |
| сайт открыт или закрыт | PUT /data/settings/closed | access в GET /data/seo.audit | поля настроек |
описание и видимость поисковикам blog_public | PATCH /data/site.settings | schema-website | site.settings |
| главная сайта и языков | PUT /data/site.front_page | homes | главная |
| Метрика, GA4, Search Console, Вебмастер | PUT /data/settings/{field}, поля metrika, ga, gsc, webmaster | counters | счетчики |
| организация | PATCH /data/site.organization | schema-organization | организация |
соцсети: sameAs и twitter:site | PATCH /data/site.socials | schema-organization, schema-og | соцсети |
| автор статей | PUT /data/author | schema-author | справочник данных |
| контакты и документы в подвале | PUT /data/footer с lang | contacts | справочник данных |
Закрытый сайт (closed: true) отвечает посетителям 503 с X-Robots-Tag: noindex, robots.txt отдает Disallow: /, карты сайта отвечают 503, llms.txt — 404. Трафик по страницам из Search Console и GA4 — GET /pages/{ref}/traffic, рекомендации по странице — поле advice того же ответа.