Войти Начать
Markdown
Открыть в ИИ

Общие правила

Здесь адреса запросов, ссылки на ресурсы, защита от перезаписи и пробный прогон. Токен и права описывает «Авторизация», форму ответа — «Ошибки».

Адрес и формат

Эндпоинты сайта используют $API/site/$SITE. Путь /pages в справочнике означает https://onpress.pro/api/v2/site/{siteId}/pages. Запросы и ответы используют UTF-8. Для JSON-тела передайте Content-Type: application/json.

curl -s "$API/site/$SITE/pages?per_page=1" -H "Authorization: Bearer $OP_TOKEN"

SITE — внешний id сайта из списка сайтов. Таблица операции отдельно указывает параметры пути, строки запроса и тела. Не переносите свойство страницы из блока свойств Markdown в соседнее поле JSON, если эндпоинт не описывает такое поле.

Права

Эндпоинты сайта открыты администратору сайта. API проверяет и токен, и доступ к выбранному SITE. Подробности — в «Авторизации».

Ссылка на страницу

{ref} страницы обозначает id, слаг или путь. В пути замените / на ~. Для /ru/o-nas/ передайте ru~o-nas. Если адрес содержит специальные символы URL, закодируйте сегмент пути.

curl -s "$API/site/$SITE/pages/docs~v2~ru~guides~data/markdown" -H "Authorization: Bearer $OP_TOKEN"

Голый слаг API ищет на языке lang, а без lang — на основном языке сайта. Id и полный путь точнее слага. Если lang не совпадает с языком найденной страницы, API отказывает.

КодHTTPКогдаЧто делать
page_not_found404Страницы нет.Проверьте id или путь.
ambiguous_page409Слаг обозначает несколько страниц.Возьмите id или полный путь из candidates либо matches.
page_language_mismatch409Язык страницы отличается от lang.Проверьте actual_lang и исправьте запрос.

Фрейм использует свой {ref} — id или слаг. Меню принимает id, слаг, имя или область с ~, например ~header. Сайдбар документации использует ссылки, подписи групп и координаты пунктов. Формы описаны у профильного эндпоинта.

Защита от перезаписи

Чтение страницы отдает modified. Передайте его полем if_modified в запись. API сравнит версии перед записью и вернет 409 page_changed, если кто-то успел изменить страницу.

curl -s -X PATCH "$API/site/$SITE/pages/example/markdown" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"if_modified":"2026-10-30 12:00:00","patch":[{"action":"replace","find":"Старый текст.","with":"Новый текст."}]}'

Данные используют if_sha256 из поля sha256 чтения. Сайдбар документации использует свою версию меню с тем же именем поля. Семантический план требует version из GET /data/seo.semantic.

ПолеТипОбязательноеПо умолчаниюОписание
if_modifiedstringнет, если операция не требует иногобез сверкиВерсия страницы в формате ответа modified.
if_sha256stringнет, если операция не требует иногобез сверки64 шестнадцатеричных символа из чтения данных или меню.
versionintegerда для записи семантики—Текущая версия семантического плана.
КодHTTPКогдаЧто делать
page_changed409Страница новее переданного if_modified.Перечитайте страницу и примените правку к новой версии.
page_not_matched409Версия передана без найденной страницы.Укажите id существующей страницы.
dataset_changed409Данные изменились после чтения.Перечитайте данные и повторите правку.
bad_if_sha256400Неверная форма версии.Скопируйте sha256 из чтения.
sidebar_changed409Меню изменилось после чтения или во время запроса.Перечитайте сайдбар.
semantic_changed409План изменился после чтения.Перечитайте план и передайте новую version.

Пробный прогон

dry_run: true проверяет изменение без записи только у операций, которые явно описывают этот параметр. Для поддерживаемой строки запроса используйте ?dry_run=1. Если операция читает обе формы, поле тела имеет приоритет.

У публикации POST /pages/markdown, правки свойств PATCH /pages/{ref} и частотности PUT /pages/{id}/keyword-frequency запрос пробного прогона вызывает 400 dry_run_not_supported. Они ничего не записывают при таком отказе. Не добавляйте dry_run произвольной операции. Операции, которые его не читают, выполняют обычную запись.

Обновление кэша

Запись страницы обновляет ее копию и сбрасывает кэш адреса. При смене адреса API затрагивает и старый адрес. Поле cache описывает результат операции.

{"cache":{"status":"flushed","urls":["https://example.com/ru/start/"]}}
ПолеТипОписание
cache.statusstringflushed — API сбросил кэш, nothing — адреса для сброса нет.
cache.urlsstring[]Адреса, по которым API сбросил кэш.

Поля rebaked и отчеты сборки зависят от операции. Их значения описывает «Сборка». Ручной сброс кэша — в «Кэше».

Формат ответа

Не считайте HTTP 200 гарантией конкретного результата. Читайте поля операции, например changed, applied, warnings, pending и verified. Ошибку определяйте по HTTP-статусу и error либо code, а не по тексту message. Примеры — на странице «Ошибки».

Окружение

Рабочий адрес API — https://onpress.pro/api/v2. GET /health возвращает realm, ответы эндпоинтов сайта содержат X-OnPress-Realm. Если API вернул 409 wrong_realm, он отклонил запись. Отправьте запрос на рабочий адрес API. Состояние сервиса — в «Состоянии API».

Бета

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

Лимиты

API допускает 120 запросов в минуту на пользователя и JSON-тело до 10 МБ при стандартной настройке сервиса. Авторизация отдельно ограничивает неверные токены. Заголовки и порядок повторного запроса — в «Авторизации» и «Ошибках».

ЧтоПределОтвет при превышении
Страниц в GET /pages200 на страницу выдачибольше не отдается
Страниц в серии POST /pages/series50413 series_too_large
Наборов в POST /pages/import80413 import_too_large
Страниц под поиском GET /pages/search3000422 too_many_pages
Запрос q поиска500 символов400 q_too_long
Регулярное выражение поиска2 секунды422 regex_timeout
Страниц в сборке ссылок PUT /data/seo.page_links5000 опубликованных413 too_many_pages
Страниц в GET /data/seo.page_links и GET /data/traffic500 за запросбольше не отдается
Сохраненных представлений50 на пользователя на сайте409 views_limit