Справочник: данные

Ручки сайта: $API/site/$SITE/data…. Как устроены наборы и источники — наборы данных, повторитель — onpress/repeat.

GET /data

Наборы сайта (без системных источников).

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

{
  "success": true,
  "site_id": "x9HTLHECq",
  "home_url": "https://test.onpress.pro",
  "registry_option": "onpress_datasets",
  "option_prefix": "onpress_dataset_",
  "resolution_order": ["system", "site", "inline"],
  "system_sources": "/data/sources",
  "total": 4,
  "datasets": [
    {
      "name": "docs_primer",
      "lang": null,
      "origin": "site",
      "contextual": false,
      "items": 3,
      "bytes": 243,
      "sha256": "…",
      "fields": [ { "field": "id", "types": ["number"], "in_items": 3 }, { "field": "q", "types": ["string"], "in_items": 3 }, { "field": "a", "types": ["string"], "in_items": 3 } ],
      "created_at_gmt": "2026-09-12 20:39:03",
      "updated_at_gmt": "2026-09-12 20:39:05",
      "updated_by": 1,
      "option": "onpress_dataset_docs_primer"
    },
    { "name": "docs_primer", "lang": "ru", "items": 1, "option": "onpress_dataset_docs_primer__ru", "…": "…" }
  ]
}

Каждый языковой вариант — отдельная запись с lang. site_id приходит и на устаревшем адресе (?blog_id=).

GET /data/sources

Системные источники: имя, контекстный ли, пишется ли и как.

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/data/sources" | jq '{total, writable, sources: [.sources[] | {name, contextual, writable}]}'

Ответ: total (14), writable — имена записываемых, sources[] с name, origin, contextual, description, writable и либо write (method, at, forwards_to, changes, body, also), либо readonly_because. Плюс пояснения note, readonly_note, reserved_note, contextual_note.

GET /data/{name}

Содержимое набора или системного источника — в одной форме.

Параметр	Смысл
`lang`	язык: вариант набора, меню языка
`page`	текущая страница: id, слаг или путь со слешами; нужна контекстным источникам и `page.*` в `match`
`match`	фильтр JSON-строкой, например `{"page":"page.slug"}`
`limit`, `offset`	окно, как у повторителя
`paged`	значение `page.paged` для окна
`statuses`	статусы для `pages.*` через запятую; по умолчанию `publish`
`theme`	читать области меню другой темы

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/data/docs-proba-faq?lang=ru"

{
  "success": true,
  "site_id": "x9HTLHECq",
  "name": "docs-proba-faq",
  "origin": "site",
  "contextual": false,
  "option": "onpress_dataset_docs-proba-faq__ru",
  "lang": "ru",
  "fields": [ { "field": "id", "types": ["number"], "in_items": 1 }, "…" ],
  "updated_at_gmt": "2026-09-25 20:21:32",
  "total": 1,
  "items": [ { "id": 1, "page": "proba-api", "q": "Сколько стоит?", "a": "Бесплатно" } ]
}

Поле	Когда	Смысл
`origin`	всегда	`system`, `site` или `inline`
`contextual`, `page_id`, `needs_page`	всегда	зависит ли от страницы; какая страница взята; нужна ли страница, а её не дали
`lang`, `lang_fallback`	наборы	вариант, который отдан; почему не тот, что просили
`writable`, `write` / `readonly_because`, `description`	системные	можно ли и как менять
`meta`	меню	`{menu_id, invalid_items}`
`same_name_dataset`	пустое меню и есть набор с таким же коротким именем	подсказка
`match`, `match_total`, `match_unresolved`, `match_note`	с `match`	во что разрешились токены; сколько было до фильтра
`window`, `window_total`	с `limit`/`offset`	применённое окно; сколько было до среза
`registry_stale`	реестр отстал от содержимого	цифры реестра и настоящие
`total`, `items`	всегда	результат

Отказы: 404 source_not_found, 404 page_not_found (для page), 400 match_token_unsupported (supported), 422 unknown_language.

PUT /data/{name}

Положить набор целиком.

Поле	Смысл
`items`	массив элементов (синоним `data`); объект оборачивается в список из одного
`lang`	записать вариант этого языка (также в строке запроса)
`dry_run`	проверить без записи; можно и `?dry_run=1`

curl -s -X PUT "$API/site/$SITE/data/docs-proba-faq" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"items": [{"id": 1, "page": "proba-api", "q": "Сколько стоит?", "a": "Бесплатно"}]}'

Ответ: applied, updated (набор уже был), dataset (name, lang, items, bytes, sha256, fields, даты, option), warnings, rebaked.

Для системного имени PUT работает только у menu.* (пункты меню в области) и site.front_page (главная); тело — как у ручки, куда уходит запись (наборы данных). Ответ — ответ той ручки плюс source, wrote, rebaked.

Отказы: 400 bad_dataset_items (нет items), 400 bad_dataset_name, 409 reserved_dataset_name, 413 dataset_too_large, 422 unknown_language; для системных — 404 menu_not_assigned, 400 bad_menu_items, 405 wrong_method_for_source, 409 computed_source.

PATCH /data/{name}

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

Поле	Смысл
`ops`	массив операций; одну можно прислать без обёртки
`lang`	вариант языка
`dry_run`	применить операции к копии и показать результат без записи (`items` — набор после правки); можно и `?dry_run=1`

Операции: set (index или match, item), merge (index или match, fields), append и prepend (item или items), remove (index или match), move (index или match, to).

curl -s -X PATCH "$API/site/$SITE/data/docs-proba-faq" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"ops": [{"op": "merge", "match": {"id": 2}, "fields": {"a": "Нет, не нужна"}}, {"op": "append", "item": {"id": 4, "q": "Есть API?", "a": "Да"}}]}'

Ответ: dataset, applied — по записи на операцию ({op, index, fields}, {op, added, total}, {op, from, to}, {op, index, total}), total, rebaked. Операции — в одной транзакции.

Для системного имени PATCH работает у site.settings (настройки сайта) и site.languages (один язык или default). Запись в системный источник (PUT и PATCH) пробного прогона не знает: с dry_run — 400 dry_run_not_supported, ничего не меняется.

Отказы: 400 nothing_to_update, 400 bad_patch_op, 400 item_ref_required, 404 item_not_found, 404 dataset_not_found; для системных — 400 field_belongs_elsewhere, 400 whole_list_not_accepted, 400 lang_required, 400 nothing_to_change, 405 wrong_method_for_source, 409 computed_source.

DELETE /data/{name}

Удалить набор или вариант языка (lang в теле или строке запроса). dry_run (в теле или ?dry_run=1) ничего не удаляет и отвечает would_delete с именем, языком и числом элементов.

curl -s -X DELETE "$API/site/$SITE/data/docs-proba-faq?lang=ru" -H "Authorization: Bearer $OP_TOKEN"

{ "success": true, "site_id": "x9HTLHECq", "deleted": { "name": "docs-proba-faq", "lang": "ru", "items": 1, "option": "onpress_dataset_docs-proba-faq__ru" }, "rebaked": { "status": "nothing", "total": 0, "baked": 0, "frames": [], "reason": "no frame depends on this change" } }

Отказы: 404 dataset_not_found, 409 system_source_not_deletable.

POST /data/resolve

Разрешить источник так, как это сделает повторитель. По смыслу — чтение.

Поле	Смысл
`source`	имя (синоним `name`); без него проверяется `items`
`items`	список в атрибуте
`page`	страница (синоним `page_id`)
`lang`	язык варианта
`match`	объект или JSON-строка
`limit`, `offset`, `paged`	окно
`statuses`	статусы для `pages.*`
`theme`	тема для областей меню

curl -s -X POST "$API/site/$SITE/data/resolve" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"source": "docs-proba-faq", "page": "proba-api", "match": {"page": "page.slug"}}'

{
  "success": true,
  "site_id": "x9HTLHECq",
  "name": "docs-proba-faq",
  "origin": "site",
  "contextual": true,
  "option": "onpress_dataset_docs-proba-faq",
  "lang": null,
  "lang_fallback": "there is no dataset \"docs-proba-faq\" for language \"en\", the shared one was returned",
  "total": 2,
  "items": [ { "id": 1, "page": "proba-api", "q": "Сколько стоит?", "a": "Бесплатно" }, { "id": 2, "page": "proba-api", "q": "Нужна карта?", "a": "Нет" } ],
  "page_id": 6428,
  "match": { "page": "proba-api" },
  "match_total": 3
}

Ответ той же формы, что у GET /data/{name}. Токены, которые сервис считает в match: page.id, page.slug, page.title, page.status, page.type, page.parent_id, page.paged, site.lang, site.blog_id, raw:. Отказы: 404 source_not_found, 400 match_token_unsupported, 404 page_not_found.