Данные

Данные — это одна точка входа ко всему, что можно поменять на сайте: меню, языкам, настройкам, главной странице, текстам лендинга. Всё это доступно через один эндпоинт /data/{name}, и меняется в нём только имя: menu.header, site.languages, site.settings, pages.content.

Поэтому AI-агенту не нужно разбираться в устройстве OnPress: читать, править и записывать всё он будет по одной схеме. Агент работает только с нужным куском JSON, а не со всей страницей: правка меню — два коротких запроса, а не перезаливка вёрстки. Так правки идут быстро, тратят мало токенов, и агент не путается в чужом HTML.

Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Полный перечень эндпоинтов — в справочнике API.

Зачем они нужны

Допустим, в шапке нужно добавить пункт меню. Агент читает menu.header, добавляет пункт и записывает обратно, и новое меню сразу появляется на всех страницах сайта.

Другой пример — перевод лендинга. Вёрстка у всех языков общая, а у каждого набора и у меню есть вариант на нужный язык. Переводятся только несколько JSON-массивов, поэтому HTML лендинга не нужно копировать на каждый язык.

А если агенту нужно разобраться, как устроен сайт, он читает pages.tree, site.languages и menu.header и за три запроса видит структуру страниц, языки и навигацию, не открывая ни одной страницы.

Типы данных

Пользовательские данные — списки, которые завели вы или агент: блоки лендинга, отзывы, логотипы клиентов. Это массив объектов с любыми полями. Имя — латиница в нижнем регистре, цифры, - и _, до 64 символов; размер — до 512 КБ.

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

Имя	Что это	Подробно
`menu.header`, `menu.footer_1` … `menu.footer_3`	меню сайта по областям	Меню
`site.settings`, `site.front_page`	название, иконка, главная страница	Настройки сайта
`site.languages`	языки сайта	Языки и переводы
`css.variables`, `css`	CSS-переменные темы и собственный CSS сайта	Стили и оформление
`pages.all`, `pages.tree`, `pages.children` …, `breadcrumbs`	списки страниц и хлебные крошки, только чтение	Страницы
`pages.content`	текст одной страницы в Markdown, чтение и запись	Страницы

Создать или изменить данные

Схема одна для всего: прочитать GET /data/{name}, поправить JSON, записать PUT /data/{name}. После записи страницы, где используются эти данные, пересобираются сами.

Например, агент добавляет пункт в меню шапки на русском:

curl -s "$API/site/$SITE/data/menu.header?lang=ru" -H "Authorization: Bearer $OP_TOKEN"

curl -s -X PUT "$API/site/$SITE/data/menu.header" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"lang": "ru", "items": [
        {"page": 6231, "title": "Документация"},
        {"page": 6238, "title": "Примеры"},
        {"url": "https://example.com", "title": "Партнёры", "target": "_blank"}
      ]}'

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

Точечная правка

Когда в большом наборе меняется один элемент, агенту незачем пересылать весь список. PATCH /data/{name} правит отдельные элементы: токенов меньше, и остальное не задеть по ошибке. Так агент правит пользовательские данные, а меню записывает целиком через PUT.

curl -s -X PATCH "$API/site/$SITE/data/home_features" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"patch": [
        {"action": "merge",  "match": {"id": "speed"}, "fields": {"title": "Сайт за пять минут"}},
        {"action": "append", "item": {"id": "seo", "title": "SEO из коробки"}}
      ]}'

В patch — список правок, каждая меняет один элемент. В правке три части: action — что сделать, match или index — какой элемент, и новые значения. В примере агент меняет заголовок у элемента speed, а остальные его поля не трогает, и добавляет новый элемент seo в конец.

`action`	Что делает	Что передать
`merge`	меняет отдельные поля элемента	`fields` — поля с новыми значениями
`set`	заменяет элемент целиком	`item` — новый элемент
`append`, `prepend`	добавляет элемент в конец или в начало	`item`
`remove`	удаляет элемент	—
`move`	переставляет элемент	`to` — новая позиция

Правки применяются вместе: если хоть одна не прошла, набор остаётся прежним.

Прочитать

Прочитать данные можно одним из четырёх запросов:

GET /data — все данные сайта: имена пользовательских и системных;
GET /data/user — только пользовательские;
GET /data/system — только системные, с пометкой, можно ли в них писать;
GET /data/{name} — одни данные по имени, например GET /data/menu.header. С lang — на нужном языке, с page — для конкретной страницы, как хлебные крошки.

Например, меню шапки на русском:

curl -s "$API/site/$SITE/data/menu.header?lang=ru" -H "Authorization: Bearer $OP_TOKEN"

В ответе — пункты меню: название, адрес и вложенные пункты в children.

Данные в консоли

Все данные сайта, их содержимое и эндпоинты, которыми их меняют, можно посмотреть в консоли, в разделе «Данные» (/dashboard/data). Слева — список пользовательских и системных данных. Откройте набор, и справа будут три вкладки: «Записи» — содержимое в JSON, «Поля» — какие поля есть в элементах, «Эндпоинты» — готовые адреса для чтения и записи. Адрес можно скопировать и передать AI-агенту, а кнопка «Промпт для AI» копирует готовую инструкцию для работы с данными сайта.

Удалить

DELETE /data/{name} удаляет набор, а страницы, где он выводился, пересобираются без него. Например, агент удаляет набор с отзывами клиентов:

curl -s -X DELETE "$API/site/$SITE/data/reviews" -H "Authorization: Bearer $OP_TOKEN"

Локализация

Чтобы перевести сайт, достаточно перевести данные. У каждого языка своё меню и свои варианты пользовательских наборов, а вёрстка у всех языков общая. Переведённые тексты записывают с lang нужного языка. Подробно — в разделе Языки и переводы.

Вопросы и ответы

Почему страница не изменилась после записи?

Проверьте, что имя набора совпадает с именем во фрейме страницы. Если совпадает, откройте страницу с ?nc=<время>: браузер мог показать старую копию.

Как проверить запись, ничего не меняя?

Пользовательские данные и текст страницы (pages.content) принимают ?dry_run=1: API покажет результат, но ничего не запишет. У меню, настроек и языков сухого прогона нет, поэтому сохраните прочитанный JSON: из него можно вернуть прежнее состояние.

Видят ли мои пользовательские данные другие сайты?

Нет, каждый набор принадлежит одному сайту.

Где коды ошибок?

В справочнике API. Ответ с ошибкой сам называет причину и нужный эндпоинт.