Справочник: фреймы

Ручки сайта: $API/site/$SITE/frames…. {ref} — id фрейма (16 шестнадцатеричных символов) или слаг. Что такое фрейм — фреймы.

Общее для всех записей:

type во входе игнорируется (warnings: ["type_ignored"]), default/is_default — тоже (default_ignored), name — тоже (name_ignored);
url во входе — 400 frame_url_not_supported: у фрейма нет адреса;
bake: false — не просить сборку на стороне сайта (по умолчанию просится);
ответ записи несёт bake (сборка этого фрейма) и rebaked (пересборка фреймов, вкладывающих его).

GET /frames

Параметр	Смысл
`block`	только фреймы блока: `?block=article` — `article`, `article__faq`, `article__faq--simple`
`q`	подстрока слага, без учёта регистра
`include_html`	`1` — с разметкой каждого фрейма

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/frames?q=shapka"

{
  "success": true,
  "site_id": "x9HTLHECq",
  "home_url": "https://test.onpress.pro",
  "total": 2,
  "registry_option": "onpress_frames",
  "page_meta": "_onpress_frame",
  "slug_pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*(?:__[a-z0-9]+(?:-[a-z0-9]+)*)?(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?$",
  "frames": [
    {
      "id": "cb7ccee58078d1fb",
      "slug": "shapka-sajta",
      "block": "shapka-sajta",
      "element": null,
      "modifier": null,
      "bytes": 7762,
      "sha256": "…",
      "inserts": { "op/lang-switcher": 2, "op/menu": 1 },
      "sources": [],
      "frame_refs": [],
      "binds": 8,
      "created_at_gmt": "2026-09-12 19:08:38",
      "updated_at_gmt": "2026-09-13 11:34:34",
      "updated_by": 1,
      "option": "onpress_frame_cb7ccee58078d1fb"
    }
  ]
}

Фреймы отсортированы по слагу. У фрейма, на котором стоят страницы, есть pages — их id. renders_on_request: true — фрейм зависит от страницы. ?type= игнорируется с предупреждением.

POST /frames

Загрузить новый фрейм.

Поле	Тип	Смысл
`slug`	string	обязательно; `блок__элемент--модификатор`, приводится к нижнему регистру
`html`	string	обязательно; синонимы `markup`, `content`. Хранится байт в байт
`dry_run`	bool	проверить и вернуть отчёт без записи
`bake`	bool	просить сборку (по умолчанию `true`)

curl -s -X POST "$API/site/$SITE/frames" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d "$(jq -n --arg html '<section class="proba-card"><h2 data-op-bind='"'"'{"text":"site.name"}'"'"'></h2><!-- onpress/menu {"place":"header","class":"proba-card__menu"} /--></section>' '{slug: "docs-proba__kartochka", html: $html}')"

{
  "success": true,
  "applied": true,
  "updated": false,
  "site_id": "x9HTLHECq",
  "frame": {
    "id": "20a39aa2b124c145",
    "slug": "docs-proba__kartochka",
    "bytes": 146,
    "sha256": "…",
    "inserts": { "op/menu": 1 },
    "sources": [],
    "frame_refs": [],
    "binds": 1,
    "created_at_gmt": "2026-09-25 20:18:25",
    "updated_at_gmt": "2026-09-25 20:18:25",
    "updated_by": 1,
    "block": "docs-proba",
    "element": "kartochka",
    "modifier": null,
    "option": "onpress_frame_20a39aa2b124c145"
  },
  "inserts": { "op/menu": 1 },
  "inserts_total": 1,
  "sources": [],
  "frame_refs": [],
  "binds": 1,
  "renders_on_request": false,
  "has_doctype": false,
  "has_body": false,
  "warnings": [],
  "bake": {
    "status": "ok",
    "response": {
      "baked": true,
      "frame_id": "20a39aa2b124c145",
      "bytes": 685,
      "source_bytes": 146,
      "baked_option": "onpress_frame_20a39aa2b124c145_baked",
      "renders_on_request": false,
      "lang": "",
      "default_lang": "en",
      "blocks": 1,
      "inserts": 1,
      "unknown_inserts": [],
      "binds": 1,
      "bind_tags": 1,
      "repeats": [],
      "frames": [],
      "unresolved": [],
      "warnings": [],
      "published": { "published": false, "pages": [] },
      "pages": []
    }
  }
}

Отчёт о разметке: inserts, inserts_total, sources, frame_refs (ссылки по id приведены к слагам), binds, renders_on_request и live_reasons, has_doctype, has_body, warnings, frame_refs_missing. Что значат поля bake.response — в сборке. dry_run отвечает тем же отчётом с dry_run: true, applied: false и без bake.

Отказы: 400 invalid_slug (pattern, hint), 400 frame_html_required, 400 frame_url_not_supported, 400 frame_ref_conflict (во вставке onpress/frame два ключа ссылки называют разные фреймы; conflicts — пары ключей и значений; слаг и id одного фрейма конфликтом не считаются), 409 slug_taken (id занявшего — замените его разметку через PUT), 413 frame_too_large (больше 2 МБ; max_bytes).

GET /frames/{ref}

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/frames/shapka-sajta" | jq '.frame | {id, slug, referenced_by, pages, html}'

Ответ {success, frame}: всё, что в элементе списка, плюс html — разметка как загружена, referenced_by — слаги фреймов, которые его вкладывают, pages — id страниц на этом фрейме. Отказы: 404 frame_not_found, 400 frame_ref_required.

PUT /frames/{ref}

Заменить разметку. Тело — как у POST (html обязателен, slug можно сменить — с теми же последствиями, что у PATCH). Ответ — как у POST с updated: true и rebaked — пересборкой фреймов, вкладывающих этот (транзитивно). Отказы: как у POST плюс 404 frame_not_found.

PATCH /frames/{ref}

Переименовать.

Поле	Смысл
`slug`	новый слаг; единственное поле, которое правит `PATCH`
`dry_run`, `bake`	как у `POST`

curl -s -X PATCH "$API/site/$SITE/frames/docs-proba__kartochka" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"slug": "docs-proba__card"}'

{
  "success": true,
  "site_id": "x9HTLHECq",
  "frame": { "id": "20a39aa2b124c145", "slug": "docs-proba__card", "block": "docs-proba", "element": "card", "modifier": null, "…": "…" },
  "renamed": {
    "from": "docs-proba__kartochka",
    "to": "docs-proba__card",
    "frames_updated": ["docs-proba--lending"],
    "details": [ { "id": "53c0ec423d1f7072", "slug": "docs-proba--lending", "replaced": 1 } ]
  },
  "bake": { "status": "ok" },
  "rebaked": { "status": "ok", "…": "…" }
}

Во фреймах сайта, ссылавшихся на старый слаг, ссылки onpress/frame (и onpress/partial) переписываются на новый; ссылка, записанная алиасом ключа (ref, frame, slug, id), переписывается основным ключом name, если его во вставке ещё нет; остальная разметка не меняется. Страницы не трогаются — они хранят id. Отказы: 400 nothing_to_update (в теле только name или ничего), 410 gone (только default/is_default), 400 invalid_slug, 409 slug_taken, 400 frame_url_not_supported, 404 frame_not_found.

DELETE /frames/{ref}

curl -s -X DELETE "$API/site/$SITE/frames/docs-proba__faq" -H "Authorization: Bearer $OP_TOKEN"

{
  "success": true,
  "site_id": "x9HTLHECq",
  "deleted": { "id": "838a082b034be249", "slug": "docs-proba__faq", "block": "docs-proba", "element": "faq", "modifier": null },
  "unbound_pages": [],
  "referenced_by": ["docs-proba"],
  "warnings": ["frames docs-proba still insert \"docs-proba__faq\"; the insert prints nothing until a frame with this slug appears again"],
  "bake": { "status": "ok" }
}

У страниц фрейма снимается привязка (unbound_pages) и статическая копия — на сайте v2 они начинают отвечать 404. Вкладывающие фреймы не правятся (referenced_by). bake: false в теле — не просить сборку. Отказы: 404 frame_not_found.

POST /frames/{ref}/assign

Поставить фрейм на страницу (или снять).

Поле	Смысл
`page`	обязательно: id, слаг или путь страницы
`clear`	`true` — снять фрейм со страницы
`bake`	как у `POST`

curl -s -X POST "$API/site/$SITE/frames/docs-proba--lending/assign" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"page": "proba-api"}'

{
  "success": true,
  "site_id": "x9HTLHECq",
  "frame": { "id": "53c0ec423d1f7072", "slug": "docs-proba--lending", "…": "…" },
  "page": { "id": 6428, "title": "Проба API", "url": "/proba-api/" },
  "meta_key": "_onpress_frame",
  "cleared": false,
  "static": { "published": true, "url": "/proba-api", "bytes": 15368, "reason": "", "message": "", "was_published": true, "was_url": "/proba-api", "removed": false, "changed": false },
  "republish": { "status": "ok", "…": "…" }
}

static — судьба статической копии этой страницы после смены фрейма (поля как у PATCH /pages/{ref}), republish.status — ok, skipped, unavailable, failed; неудача не отменяет привязку. Отказы: 400 page_required, 404 frame_not_found, 404 page_not_found, 409 ambiguous_page.

POST /frames/rebake

Пересобрать фреймы вручную.

Поле	Кого пересобрать
`all`	все фреймы сайта
`menus`	зависимые от меню
`pages`	выводящие страницы, их заголовки и адреса
`languages`	языкозависимые
`settings`	зависимые от настроек сайта
`datasets`	массив имён наборов — читающие их
`frames`	массив слагов или id — вкладывающие их

curl -s -X POST "$API/site/$SITE/frames/rebake" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"datasets": ["docs-proba-faq"]}'

{
  "success": true,
  "site_id": "x9HTLHECq",
  "changed": { "datasets": ["docs-proba-faq"] },
  "rebaked": {
    "status": "ok",
    "total": 2,
    "baked": 0,
    "not_needed": 2,
    "frames": [
      { "id": "838a082b034be249", "slug": "docs-proba__faq", "because": ["datasets: docs-proba-faq"], "bake": "not_needed", "detail": "renders on request from the source, has no baked copy" },
      { "id": "e627bf4dbefcc374", "slug": "docs-proba", "because": ["contains docs-proba__faq"], "bake": "not_needed", "detail": "renders on request from the source, has no baked copy" }
    ],
    "cache": {
      "status": "ok",
      "scope": "pages",
      "pages": [6428],
      "flushed": { "urls": { "status": "flushed", "by": "wpsc_delete_url_cache", "urls": ["https://test.onpress.pro/proba-api/"], "skipped": [] } }
    }
  }
}

Поля rebaked — в сборке. За вызов — не больше 25 фреймов (остальные в skipped). Отказы: 400 nothing_to_rebake.

Снятые ручки

GET, PUT и любые другие методы /frames/defaults, а также POST /frames/{ref}/default отвечают 410 gone: умолчаний и типов у фреймов нет, страница называет фрейм сама.