Семантика

API собирает семантический план сайта и связывает запросы со страницами. Сценарии — в гайде.

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 продолжают работать со своим форматом ответа.

Метод	Путь	Действие
GET	`/data/seo.semantic`	Прочитать семантический план (бета)
PUT	`/data/seo.semantic`	Импортировать запросы (бета)
PUT	`/data/seo.semantic.sync`	Сопоставить запросы со страницами (бета)
PUT	`/data/seo.semantic.groups`	Создать группу (бета)
PATCH	`/data/seo.semantic.groups`	Изменить группу (бета)
DELETE	`/data/seo.semantic.groups`	Удалить группу (бета)
PUT	`/data/seo.semantic.page`	Создать страницу для группы (бета)
PATCH	`/data/seo.semantic.keywords`	Изменить запрос (бета)
DELETE	`/data/seo.semantic.keywords`	Удалить запрос (бета)

Прочитать семантический план (бета)

GET /data/seo.semantic

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

curl -s "$API/site/$SITE/data/seo.semantic" -H "Authorization: Bearer $OP_TOKEN"

Параметр адресации передается в строке запроса; тела нет.

Ответ

{
  "success": true,
  "name": "seo.semantic",
  "origin": "system",
  "total": 1,
  "items": [
    {
      "version": 3,
      "groups": [
        {
          "id": "0b6f2c1e-6d0a-4c43-9a51-2f6e1c7d9a10",
          "title": "чат бот онлайн",
          "lang": "ru",
          "intent": "",
          "type": "article",
          "priority": "1",
          "status": "todo",
          "planned_url": "/chat-bot/",
          "page_id": null,
          "keywords": [
            {
              "id": "4d1c0e2a9b7f6e5d4c3b2a19",
              "phrase": "чат бот онлайн",
              "frequency": 12000,
              "page": null,
              "match_count": 0
            }
          ],
          "page": null,
          "match": null,
          "candidates": []
        }
      ],
      "total": 1,
      "pages": [
        {
          "id": 6261,
          "parent": 0,
          "title": "Данные",
          "status": "publish",
          "lang": "ru",
          "url": "/docs/v2/ru/guides/data/"
        }
      ],
      "limit": 5000
    }
  ]
}

Поле	Описание
`version`	версия плана для записи; у пустого плана `0`
`groups`	группы, поля — в таблице ниже
`total`	число запросов во всех группах
`pages`	все страницы сайта: `id`, `parent`, `title`, `status`, `lang`, `url`
`limit`	сколько запросов вмещает план

Поле группы	Описание
`id`	id группы
`title`	название группы
`lang`	язык группы; `""` — без языка, тогда подходят страницы любого языка
`intent`	интент, свободный текст
`type`	`review`, `article`, `landing`, `hub`, `comparison` или `instruction`
`priority`	`1`, `2` или `none`
`status`	`todo`, `progress`, `published` или `paused`
`planned_url`	плановый адрес страницы
`page_id`	привязанная страница; `null` — привязки нет
`keywords`	запросы группы: `id`, `phrase`, `frequency` (`null` — частотность неизвестна), `page` — страница запроса, `match_count` — сколько страниц совпало с фразой
`page`	страница группы: `id`, `parent`, `title`, `status`, `url`, `link`, `lang`; `null` — не найдена
`match`	как найдена страница: `manual` — по `page_id`, `exact` — одна страница по совпадению, `ambiguous` — совпало несколько, `null` — ни одной
`candidates`	страницы, которые совпали с группой

Ошибки

Специальные коды — в таблице ошибок. Общие ошибки авторизации — в общих кодах.

Импортировать запросы (бета)

PUT /data/seo.semantic

Добавляет запросы списком или таблицей. Подробнее в гайде.

curl -s -X PUT "$API/site/$SITE/data/seo.semantic" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"version": 3, "lang": "ru", "group": "чат бот онлайн", "keywords": [{"phrase": "чат бот без регистрации", "frequency": 3400}, "бесплатный чат бот"]}'

Тело запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`version`	number, string	да	—	обязательно; версия из `GET /data/seo.semantic`, можно и строкой запроса `?version=`
`keywords`	array	нет	—	запросы: строка или объект `{phrase, frequency, group, lang}`; от 1 до 5000; нужно `keywords` или `text`
`text`	string	нет	—	таблица текстом, строка на запрос: фраза, частотность, группа; колонки через табуляцию или `;`
`lang`	string	нет	`""`	язык запросов, код вроде `ru` или `en`
`group`	string	нет	`Без группы`	группа для запросов, у которых она не указана

Ответ

Запрос, который в плане уже есть на том же языке, API пропускает. Группу API ищет по названию и языку и создает, если ее нет; без названия группы запрос попадает в группу «Без группы». Ответ — {"success": true, "name": "seo.semantic", "origin": "system", "total": 1, "items": [{"version": 4, "added": 2, "skipped": 1}]}.

В text первая строка — заголовок, если первая ячейка запрос, keyword, query или phrase; только с заголовком API читает четвертую колонку — язык строки. Фраза — до 400 знаков, частотность — целое число от 0, пробелы внутри числа API убирает.

Ошибки

Код	HTTP	Когда	Что делать
`invalid_keywords`	422	список пустой, больше 5000 строк, строка не строка и не объект или таблица не читается	исправьте список
`invalid_semantic_text`	422	пустая фраза или название группы, длиннее 400 знаков	исправьте строку
`invalid_frequency`	422	частотность не целое число от 0	исправьте число
`invalid_language`	422	язык не код вроде `ru` или `en`	исправьте `lang`
`semantic_limit`	422	в плане станет больше 5000 запросов	удалите лишние запросы

Сопоставить запросы со страницами (бета)

PUT /data/seo.semantic.sync

Забирает в план ключи страниц: по запросу на каждую страницу, у которой задан focus_keyword. Подробнее в гайде.

curl -s -X PUT "$API/site/$SITE/data/seo.semantic.sync" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"version": 4}'

Тело запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`version`	number, string	да	—	обязательно; версия из `GET /data/seo.semantic`, можно и строкой запроса `?version=`

Ответ

Запрос попадает в группу, привязанную к этой странице, а если такой нет — в новую группу с названием страницы. Группа получает page_id, плановый адрес — адрес страницы, статус published у опубликованной страницы и progress у остальных. Частотность приходит из keywordFrequencyYandex страницы, которую задает PUT /pages/{ref}/keyword-frequency. Запрос, который в плане уже есть, API пропускает. Ответ — {"success": true, "name": "seo.semantic.sync", "origin": "system", "total": 1, "items": [{"version": 5, "added": 12, "skipped": 3}]}.

Ошибки

Код	HTTP	Когда	Что делать
`semantic_limit`	422	в плане станет больше 5000 запросов	удалите лишние запросы

Создать группу (бета)

PUT /data/seo.semantic.groups

Создает пустую группу. Подробнее в гайде.

curl -s -X PUT "$API/site/$SITE/data/seo.semantic.groups" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"version": 5, "title": "чат бот для сайта", "lang": "ru"}'

Тело запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`version`	number, string	да	—	обязательно; версия из `GET /data/seo.semantic`, можно и строкой запроса `?version=`
`title`	string	нет	`Новая группа`	название, до 400 знаков
`lang`	string	нет	`""`	язык группы

Ответ

Ответ — {"success": true, "name": "seo.semantic.groups", "origin": "system", "total": 1, "items": [{"version": 6, "group_id": "…"}]}. Новая группа получает тип review, приоритет 1 и статус todo.

Ошибки

Код	HTTP	Когда	Что делать
`semantic_limit`	422	на сайте уже 1000 групп	удалите лишние группы
`invalid_semantic_text`	422	название длиннее 400 знаков	сократите
`invalid_language`	422	язык не код вроде `ru` или `en`	исправьте `lang`

Изменить группу (бета)

PATCH /data/seo.semantic.groups

Меняет переданные поля группы. Подробнее в гайде.

curl -s -X PATCH "$API/site/$SITE/data/seo.semantic.groups" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"id": "0b6f2c1e-6d0a-4c43-9a51-2f6e1c7d9a10", "version": 6, "planned_url": "/chat-bot/", "type": "article"}'

Поля адресации в теле запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`id`	string	да	—	Id ресурса из ответа чтения.

Тело запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`version`	number, string	да	—	обязательно; версия из `GET /data/seo.semantic`, можно и строкой запроса `?version=`
`title`	string	нет	—	название, до 400 знаков
`intent`	string	нет	—	интент, до 200 знаков; `""` — очистить
`planned_url`	string	нет	—	путь от корня с `/` на конце, до 500 знаков: `/guide/topic/`; `""` — очистить
`lang`	string	нет	—	язык группы; `""` — без языка
`type`	string	нет	—	`review`, `article`, `landing`, `hub`, `comparison` или `instruction`
`priority`	string	нет	—	`1`, `2` или `none`
`status`	string	нет	—	`todo`, `progress`, `published` или `paused`
`page_id`	number	нет	—	привязать страницу сайта того же языка; `null` — снять привязку

Ответ

Ответ — {"success": true, "name": "seo.semantic.groups", "origin": "system", "total": 1, "items": [{"version": 7}]}.

Ошибки

Код	HTTP	Когда	Что делать
`semantic_group_not_found`	404	группы нет	возьмите `id` из `GET /data/seo.semantic`
`invalid_semantic_text`	422	пустое или длинное название или интент	исправьте поле
`invalid_planned_url`	422	адрес не путь вида `/guide/topic/`	исправьте `planned_url`
`invalid_language`	422	язык не код вроде `ru` или `en`	исправьте `lang`
`invalid_semantic_field`	422	`type`, `priority` или `status` вне списка	возьмите значение из таблицы
`semantic_page_not_found`	422	страницы нет на сайте или она на другом языке	возьмите `id` из `pages`
`duplicate_keyword`	422	после смены языка фразы группы повторят запросы другой группы того же языка	уберите повторы

Удалить группу (бета)

DELETE /data/seo.semantic.groups

Удаляет группу вместе с ее запросами; страницу сайта эндпоинт не трогает. Подробнее в гайде.

curl -s -X DELETE "$API/site/$SITE/data/seo.semantic.groups" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"id": "0b6f2c1e-6d0a-4c43-9a51-2f6e1c7d9a10", "version": 7}'

Поля адресации в теле запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`id`	string	да	—	Id ресурса из ответа чтения.

Тело запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`version`	number, string	да	—	обязательно; версия из `GET /data/seo.semantic`, можно и строкой запроса `?version=`

Ответ

Ответ — {"success": true, "name": "seo.semantic.groups", "origin": "system", "total": 1, "items": [{"version": 8}]}.

Ошибки

Код	HTTP	Когда	Что делать
`semantic_group_not_found`	404	группы нет	возьмите `id` из `GET /data/seo.semantic`

Создать страницу для группы (бета)

PUT /data/seo.semantic.page

Дает группе страницу. Подробнее в гайде.

curl -s -X PUT "$API/site/$SITE/data/seo.semantic.page" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"id": "0b6f2c1e-6d0a-4c43-9a51-2f6e1c7d9a10", "version": 8}'

Поля адресации в теле запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`id`	string	да	—	Id ресурса из ответа чтения.

Тело запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`version`	number, string	да	—	обязательно; версия из `GET /data/seo.semantic`, можно и строкой запроса `?version=`

Ответ

Если API находит страницу группы, эндпоинт привязывает ее и отвечает reused: true. Иначе он создает черновик: название и H1 — название группы, адрес — planned_url или адрес из названия группы, focus_keyword — первый запрос группы, а без запросов — название группы, язык — язык группы; группа получает page_id, этот адрес в planned_url и статус progress. Ответ — {"success": true, "name": "seo.semantic.page", "origin": "system", "total": 1, "items": [{"version": 9, "page_id": 7150, "reused": false}]}.

Отказы публикации черновика — как у POST /pages/markdown.

Ошибки

Код	HTTP	Когда	Что делать
`semantic_group_not_found`	404	группы нет	возьмите `id` из `GET /data/seo.semantic`
`ambiguous_page`	409	с группой совпало несколько страниц	привяжите нужную через `PATCH` с `page_id`
`semantic_url_taken`	409	плановый адрес занят другой страницей того же языка	привяжите ее через `page_id` или смените `planned_url`
`semantic_home_page`	422	плановый адрес — `/`	привяжите главную через `page_id`
`semantic_page_failed`	502	черновик не создан	повторите запрос

Изменить запрос (бета)

PATCH /data/seo.semantic.keywords

Меняет частотность запроса, переносит его в другую группу того же языка или ставит первым в группе. Подробнее в гайде.

curl -s -X PATCH "$API/site/$SITE/data/seo.semantic.keywords" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"id": "4d1c0e2a9b7f6e5d4c3b2a19", "version": 9, "group_id": "0b6f2c1e-6d0a-4c43-9a51-2f6e1c7d9a10", "primary": true}'

Поля адресации в теле запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`id`	string	да	—	Id ресурса из ответа чтения.

Тело запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`version`	number, string	да	—	обязательно; версия из `GET /data/seo.semantic`, можно и строкой запроса `?version=`
`frequency`	number	нет	—	частотность, целое от 0; `null` — неизвестна
`group_id`	string	нет	—	группа, в которую перенести запрос
`primary`	bool	нет	—	`true` — поставить запрос первым в группе

Ответ

Первый запрос группы становится focus_keyword черновика, который создает PUT /data/seo.semantic.page. Ответ — {"success": true, "name": "seo.semantic.keywords", "origin": "system", "total": 1, "items": [{"version": 10}]}.

Ошибки

Код	HTTP	Когда	Что делать
`semantic_keyword_not_found`	404	запроса нет	возьмите `id` из `keywords`
`semantic_group_not_found`	404	группы `group_id` нет	возьмите `id` из `GET /data/seo.semantic`
`language_mismatch`	422	группа на другом языке	выберите группу того же языка
`invalid_frequency`	422	частотность не целое число от 0	исправьте число

Удалить запрос (бета)

DELETE /data/seo.semantic.keywords

Удаляет запрос из плана. Подробнее в гайде.

curl -s -X DELETE "$API/site/$SITE/data/seo.semantic.keywords" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"id": "4d1c0e2a9b7f6e5d4c3b2a19", "version": 10}'

Поля адресации в теле запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`id`	string	да	—	Id ресурса из ответа чтения.

Тело запроса

Поле	Тип	Обязательное	По умолчанию	Описание
`version`	number, string	да	—	обязательно; версия из `GET /data/seo.semantic`, можно и строкой запроса `?version=`

Ответ

Ответ — {"success": true, "name": "seo.semantic.keywords", "origin": "system", "total": 1, "items": [{"version": 11}]}.

Ошибки

Код	HTTP	Когда	Что делать
`semantic_keyword_not_found`	404	запроса нет	возьмите `id` из `keywords`

Общие отказы записи

Код	Статус	Когда	Что делать
`semantic_version_required`	422	нет `version` или это не целое число от 0 и не строка из цифр	передайте `version` из `GET /data/seo.semantic`
`semantic_changed`	409	план поменяли после чтения; ничего не записано, текущая версия — в `version`	перечитайте план и повторите с новой версией
`semantic_busy`	409	план сейчас записывает другой запрос	повторите через несколько секунд