Русский
Перейти
Язык
Перейти
Документация

Быстрый старт

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

Markdown
Открыть в ИИ

Вся цепочка проходит через API. Браузер может понадобиться только на самом первом шаге, и даже у него есть путь без браузера.

1. Получить токен

API v2 авторизует запрос персональным токеном OnPress: op_ и 64 шестнадцатеричных символа. Получить его можно двумя способами.

В профиле. Откройте wp-admin/profile.php на любом сайте сети, раздел «API Token», и выпустите токен. Он показывается один раз.

Через API v1, без браузера. Ручка выпуска в v1 принимает Application Password (профиль, раздел «Application Passwords»; логин — имя пользователя WordPress, не почта). GET показывает, есть ли токен, POST выпускает:

# есть ли токен: префикс и даты, самого токена в ответе нет
curl -s -u "$LOGIN:$APP_PASSWORD" "$SITE/wp-json/onpress/v1/api-token"

# выпустить или перевыпустить: текст токена показывается один раз
curl -s -X POST -u "$LOGIN:$APP_PASSWORD" "$SITE/wp-json/onpress/v1/api-token"
{ "token": "op_9f3c1a7e…", "prefix": "op_9f3c1a7e", "created_at": "2026-09-12 20:27:45", "last_used_at": null }

POST — это ротация. Токен у пользователя один, и выпуск нового сразу убивает предыдущий — у всех, кто им пользуется. Проверяйте GET-ом, а POST вызывайте только тогда, когда действительно хотите перевыпустить.

2. Задать три переменные

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

export SITE="https://example.onpress.pro"          # сайт, с которым работаете
export BASE="https://stagepress.bond/api/v2"       # API v2
export OP_TOKEN="op_9f3c1a7e…"                     # ваш токен из шага 1

3. Проверить сервис

curl -s "$BASE/health"
{"ok":true,"db":true}

GET /health — единственная ручка без токена; db — настоящий пинг базы. Всё остальное требует токен и сайт сети.

Сайт указывается всегда. Без blog_id или domain запрос уходит в блог 1 — главный сайт сети. Стенд делит базу с продом, поэтому забытый параметр — не ошибка в ответе, а успешная правка на живом сайте. Сайт этой документации — blog_id 233.

4. Первое чтение

Сайдбар документации этого сайта — безопасный вызов, на котором видно сразу токен, выбор сайта и форму ответа:

curl -s -H "Authorization: Bearer $OP_TOKEN" "$BASE/docs/sidebar?blog_id=233&lang=ru"
{
  "success": true,
  "blog_id": 233,
  "home_url": "https://example.onpress.pro",
  "template": "templates/docs.php",
  "statuses": ["publish", "draft", "private", "pending", "future"],
  "include_hidden": false,
  "lang": { "requested": "ru", "applied": "ru", "filtered_out": 24 },
  "total": 12,
  "hidden_total": 0,
  "tree": [
    {
      "id": 6231,
      "title": "Документация",
      "slug": "docs-ru",
      "status": "publish",
      "parent": 0,
      "…": "…",
      "children": [
        { "id": 6233, "title": "Введение", "slug": "vvedenie", "status": "publish", "parent": 6231, "menu_order": 1, "hidden": false, "children": [], "url": "/docs-ru/vvedenie/", "…": "…" },
        { "…": "…" }
      ]
    }
  ]
}

Успех — всегда "success": true плюс поля самой ручки. Ошибка — "success": false с машинным кодом в error, подробно в разделе Ошибки.

5. Первая страница

Страница — это markdown с frontmatter, обязательно только name. Сайт передаётся в JSON-теле рядом с документом:

curl -s -X POST -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  "$BASE/pages/markdown" -d '{
    "blog_id": 233,
    "markdown": "---\nname: \"Проба пера\"\nslug: proba-pera\nstatus: draft\n---\n\nПервый абзац.\n"
  }'
{
  "success": true,
  "updated": false,
  "id": 6229,
  "status": "draft",
  "parent": 0,
  "url": "/proba-pera/",
  "link": null,
  "preview_url": "https://example.onpress.pro/?page_id=6229",
  "visible": false,
  "warnings": ["page is not published (status \"draft\"), the address does not serve it"]
}

Ответ — это состояние страницы после записи, а не эхо запроса. updated говорит, создали страницу или обновили; link — публичный адрес или null, пока его нет, и тогда вместо него приходит preview_url; visible — видна ли страница анонимному посетителю на самом деле, а каждая причина false расписана в warnings. Повторная публикация того же документа обновляет страницу: её находят по slug плюс lang или по id, если он есть во frontmatter.

6. Положить страницу в раздел документации

Страница попадает в этот раздел, когда её url лежит внутри /docs/ и она печатается во фрейме документации. В дерево слева она встаёт отдельным шагом: пункт этого сайдбара — страница с метой _wp_page_template = templates/docs.php, v2 эту мету не пишет, и ставит страницу в сайдбар POST /docs/sidebar/items/{ref}/show — см. Сайдбар документации.

---
name: "Dashboard"
slug: "dashbord"
url: "/docs/dashbord/"
lang: "en"
status: "publish"
frame: "obolochka-dokumentaciya"
excerpt: "A web app outside WordPress for the same work the API does."
---

The dashboard is a single-page app…

Вот ответ ровно на этот документ, снятый при написании документации:

{
  "success": true,
  "updated": false,
  "id": 6350,
  "status": "publish",
  "lang": "en",
  "parent": 6183,
  "url": "/docs/dashbord/",
  "link": "https://example.onpress.pro/docs/dashbord/",
  "visible": true,
  "translations": { "en": 6350 },
  "frame": { "id": "af33214f168f8efd", "slug": "obolochka-dokumentaciya", "meta_key": "_onpress_frame" },
  "lang_changed": { "changed": true, "from": null, "to": "en" },
  "printed": {
    "how": "on_request",
    "url": "/docs/dashbord/",
    "link": "https://example.onpress.pro/docs/dashbord/",
    "frame": { "id": "af33214f168f8efd", "slug": "obolochka-dokumentaciya", "renders_on_request": true }
  },
  "warnings": [],
  "preview_url": null
}

parent разрешён из пути, frame называет фрейм, в котором страница теперь печатается, printed говорит, как она доходит до посетителя, — здесь on_request, потому что оболочка документации печатает текст самой страницы, — а lang_changed сообщает, какой язык получила страница. Поле template во frontmatter добавило бы к ответу предупреждение template_ignored и больше ничего: шаблонов темы в v2 нет, вид задаёт фрейм. Перевод публикуется с lang: ru и url без языкового префикса, а к оригиналу привязывается полем translation_of — по шагам в рецепте Перевод страницы. Порядок пунктов в дереве задаётся отдельно — см. Сайдбар документации.

Куда дальше

Как работают токен, выбор сайта и права — Аутентификация. Все поля frontmatter и дерево страниц — Страницы и markdown. Внешний вид страницы — Фреймы, её живые части — Вставки и Данные. Задачи по шагам — Рецепты. Когда что-то не работает — Ошибки.