Страницы¶

Эндпоинты для управления страницами Grav: список, создание, обновление, удаление, копирование, перемещение и изменение порядка, а также переводы страниц, пакетные операции, токены предпросмотра черновиков, таксономия и список языков сайта.

Список страниц¶

GET /pages

Выводит страницы с фильтрацией, сортировкой и постраничной разбивкой. Использует директорию страниц Flex, когда она доступна (с индексацией и кэшированием), а в остальных случаях — стандартную службу Pages. При translations=true каждый элемент содержит has_default_file и explicit_language_files, чтобы клиенты могли отличить настоящие файлы переводов от подстановки языка по умолчанию.

Параметры

Ответ

{"data": [{"route": "/blog", "slug": "blog", "title": "Blog", "template": "blog", "published": true, "visible": true, "routable": true, "has_children": true, "permissions": {"create": true, "read": true, "update": true, "delete": true, "publish": true, "list": true}}], "meta": {"pagination": {"page": 1, "per_page": 20, "total": 42, "total_pages": 3}}, "links": {"self": "/api/v1/pages?page=1&per_page=20", "next": "/api/v1/pages?page=2&per_page=20", "last": "/api/v1/pages?page=3&per_page=20"}}

Коды ответов

Получение страницы¶

GET /pages/{route}

Возвращает одну страницу с полным содержимым, метаданными и медиафайлами, а также объект permissions с возможностями вызывающей стороны для этой страницы. Возвращает ETag; используйте If-None-Match для условных запросов. Требуется api.pages.read с учётом собственного правила read страницы. Для страницы с process.twig: true также нужно разрешение на Twig в контенте.

Параметры

Ответ

{"data": {"route": "/blog/my-post", "slug": "my-post", "title": "My Post", "template": "post", "content": "# Hello World", "header": {"published": true}, "media": [], "has_default_file": true, "explicit_language_files": ["fr"]}}

Коды ответов

Создание страницы¶

POST /pages

Создаёт новую страницу. Родительская страница должна уже существовать (кроме страниц верхнего уровня), а целевая папка должна быть свободна. Метаданные страницы формируются из значений по умолчанию схемы шаблона, затем из title, затем из переданного header. Возвращает 201 с новой страницей и заголовком Location. Требуется api.pages.write с учётом собственного правила create родительской страницы; установка process.twig: true также требует разрешения на Twig в контенте.

Параметры

Запрос

{"route": "/blog/new-post", "title": "New Post", "template": "post", "content": "# New Post\nContent here"}

Ответ

{"data": {"route": "/blog/new-post", "slug": "new-post", "title": "New Post", "template": "post", "published": true, "content": "# New Post\nContent here", "media": [], "permissions": {"create": true, "read": true, "update": true, "delete": true, "publish": true, "list": true}}}

Коды ответов

Обновление страницы¶

PATCH /pages/{route}

Частичное обновление страницы. Меняются только переданные поля, а результат валидируется по схеме страницы. Возвращает обновлённую страницу с новым ETag. Требуется api.pages.write с учётом собственного правила update страницы; включение process.twig или редактирование страницы, где он уже включён, также требует разрешения на Twig в контенте.

Параметры

Запрос

{"title": "Updated Title", "header": {"subtitle": "New subtitle"}}

Ответ

{"data": {"route": "/blog/my-post", "slug": "my-post", "title": "Updated Title", "template": "post", "header": {"title": "Updated Title", "subtitle": "New subtitle"}, "content": "# Hello World", "media": [], "permissions": {"create": true, "read": true, "update": true, "delete": true, "publish": true, "list": true}}}

Коды ответов

Поддерживает оптимистичный контроль конкурентного доступа через заголовок If-Match. Передавайте ETag из последнего GET-запроса, чтобы не перезаписать параллельные изменения.

Удаление страницы¶

DELETE /pages/{route}

Удаляет страницу и её папку. Дочерние страницы тоже удаляются, если не указано children=false; в этом случае страница с дочерними страницами отклоняется с кодом 422. С ?lang= на многоязычном сайте удаляется только файл этого языка; если это единственный перевод страницы, удаляется вся папка, и children=false действует так же. Требуется api.pages.write с учётом собственного правила delete страницы.

Параметры

Коды ответов

Перемещение страницы¶

POST /pages/{route}/move

Перемещает страницу к новому родителю, при необходимости переименовывая её slug или меняя префикс порядка. Возвращает перемещённую страницу с ETag; если страницу не удаётся получить по новому маршруту, возвращаются только route и slug. Требуется api.pages.write с учётом собственного правила update страницы и правила create целевого родителя.

Параметры

Запрос

{"parent": "/blog", "slug": "moved-post"}

Ответ

{"data": {"route": "/blog/moved-post", "slug": "moved-post", "title": "My Post", "template": "post", "content": "# Hello World", "media": []}}

Коды ответов

Изменение порядка страниц¶

POST /pages/{route}/reorder

Меняет порядок дочерних страниц под родителем. Перечисленные slug'и получают числовые префиксы папок 1, 2, 3 в указанном порядке с сохранением самой широкой ширины префикса, уже используемой соседними страницами. Дочерние страницы, которых нет в списке, сохраняют текущее имя папки. Возвращает всех потомков страницы в новом порядке. Требуется api.pages.write с учётом собственного правила update родительской страницы.

Параметры

Запрос

{"order": ["first-post", "second-post", "third-post"]}

Ответ

{"data": [{"route": "/blog/first-post", "slug": "first-post", "title": "First Post", "order": "01."}, {"route": "/blog/second-post", "slug": "second-post", "title": "Second Post", "order": "02."}, {"route": "/blog/third-post", "slug": "third-post", "title": "Third Post", "order": "03."}]}

Коды ответов

Копирование страницы¶

POST /pages/{route}/copy

Дублирует страницу (включая всё содержимое и медиафайлы) по новому маршруту. Целевой родитель должен существовать, а целевой путь должен быть свободен. Если в метаданных источника задан slug:, у копии он переписывается на новое имя папки. Возвращает 201 с новой страницей (только route и slug, если копию потом не удаётся получить). Добавляет теги инвалидации кэша pages:create:<dest> и pages:list. Требуется api.pages.write с учётом правила read исходной страницы и правила create целевого родителя.

Параметры

Запрос

{"route": "/blog/my-post-copy"}

Ответ

{"data": {"route": "/blog/my-post-copy", "slug": "my-post-copy", "title": "My Post", "template": "post"}}

Коды ответов

Список языков страницы¶

GET /pages/{route}/languages

Выводит переведённые и непереведённые языки страницы. Используется для переключателя языков в редакторах страниц: translated — языки, для которых есть содержимое, untranslated — языки, настроенные для сайта, но отсутствующие у этой страницы. translated сопоставляет каждый код языка с маршрутом страницы на этом языке. На одноязычном сайте оба списка пусты. Требуется api.pages.read с учётом собственного правила read страницы.

Параметры

Ответ

{"data": {"route": "/blog/my-post", "default_language": "en", "translated": {"en": "/blog/my-post", "fr": "/blog/mon-article"}, "untranslated": ["de", "es"]}}

Коды ответов

Создание перевода¶

POST /pages/{route}/translate

Создаёт новый перевод страницы на указанном языке. Записывает новый файл {template}.{lang}.md рядом с существующей страницей. Результат валидируется по схеме страницы. Вызывает onApiBeforePageTranslate (изменяемое), onAdminSave/onAdminAfterSave и onApiPageTranslated. Возвращает 201 со страницей на новом языке; в заголовке Location нет параметра lang, поэтому добавьте ?lang=<code>, чтобы получить перевод. Требуется включённая многоязычность и api.pages.write с учётом собственного правила update страницы. Включение process.twig в header также требует разрешения на Twig в контенте.

Параметры

Запрос

{"lang": "fr", "title": "Mon article", "content": "# Bonjour"}

Ответ

{"data": {"route": "/blog/my-post", "slug": "my-post", "title": "Mon article", "template": "post", "language": "fr", "header": {"title": "Mon article"}, "content": "# Bonjour", "media": []}}

Коды ответов

Принятие языка¶

POST /pages/{route}/adopt-language

Объявляет базовый файл страницы без языкового суффикса (например, default.md) определённым языком, переименовывая его на месте в {template}.{lang}.md. Это чисто переименование в файловой системе плюс сброс кэша — содержимое не затрагивается. Предназначено для сайтов, которые начинали как одноязычные, а позже включили многоязычность: позволяет администратору объявить «этот существующий контент — английская версия», не редактируя YAML. Вызывает onApiBeforePageAdoptLanguage и onApiPageLanguageAdopted. Возвращает страницу в том виде, в каком она загружается на принятом языке. Требуется api.pages.write с учётом собственного правила update страницы.

Параметры

Запрос

{"lang": "en"}

Ответ

{"data": {"route": "/blog/my-post", "slug": "my-post", "title": "My Post", "template": "default", "language": "en", "content": "# Hello", "media": []}}

Коды ответов

Синхронизация перевода¶

POST /pages/{route}/sync

Перезаписывает содержимое и заголовок одного языка содержимым и заголовком другого. Удобно для сценариев «вернуть эту французскую страницу к английской версии». Файлы перевода источника и цели должны уже существовать. Действуют те же проверки Twig в контенте и валидация по схеме, что и при обычном сохранении страницы. Вызывает onApiBeforePageSync (изменяемые заголовок и содержимое) и onApiPageSynced. Возвращает обновлённую целевую страницу. Требуется включённая многоязычность и api.pages.write с учётом собственного правила update страницы.

Параметры

Запрос

{"source_lang": "en", "target_lang": "fr"}

Ответ

{"data": {"route": "/blog/my-post", "slug": "my-post", "title": "My Post", "template": "post", "language": "fr", "content": "# Hello", "media": []}}

Коды ответов

Сравнение переводов¶

GET /pages/{route}/compare

Возвращает параллельно заголовок, содержимое, метаданные и дату изменения для двух языковых версий страницы. Используется интерфейсами сравнения переводов в Admin2. Сторона равна null, если страница не существует на этом языке, а exists равно false, если она находится только через подстановку языка по умолчанию, а не через собственный файл, — так клиенты всё равно могут показывать состояние «цель отсутствует». Требуется включённая многоязычность и api.pages.read, причём ни исходная, ни целевая версия не должны запрещать вызывающей стороне чтение.

Параметры

Ответ

{"data": {"route": "/blog/my-post", "source": {"lang": "en", "exists": true, "title": "My Post", "content": "# Hello", "header": {"title": "My Post"}, "modified": "2026-04-17T10:00:00+00:00"}, "target": {"lang": "fr", "exists": false, "title": "My Post", "content": "# Hello", "header": {"title": "My Post"}, "modified": null}}}

Коды ответов

Пакетные операции со страницами¶

POST /pages/batch

Выполняет одну и ту же операцию (publish, unpublish, delete или copy) над несколькими страницами за один запрос. Результаты по каждой странице возвращаются отдельно, поэтому один сбой не прерывает пакет; страница, правила которой запрещают действие, возвращается как результат с error. До запуска любой операции каждый маршрут должен указывать на существующую страницу. Ограничено plugins.api.batch.max_items (по умолчанию 50). Добавляет теги инвалидации кэша по каждой странице в соответствии с операцией. Требуется api.pages.write.

Параметры

Запрос

{"operation": "publish", "routes": ["/blog/post-1", "/blog/post-2"]}

Ответ

{"data": {"operation": "publish", "results": [{"route": "/blog/post-1", "status": "success"}, {"route": "/blog/post-2", "status": "error", "message": "Page permissions deny 'publish' on this page."}], "total": 2, "successful": 1, "failed": 1}}

Коды ответов

Реорганизация страниц¶

POST /pages/reorganize

Атомарно перемещает и/или изменяет порядок нескольких страниц за один запрос. Все операции проверяются до внесения изменений в файловую систему, а затем выполняются по двухфазной стратегии с временным переименованием и откатом по возможности при сбое. Нельзя переместить страницу в её собственное поддерево или в родителя, который сам перемещается в этом же запросе. Ограничено plugins.api.batch.max_items (по умолчанию 50). Вызывает onApiBeforePagesReorganize, onApiPagesReorganized и onApiPageMoved для каждой фактически перемещённой страницы. Требуется api.pages.write; если правила страницы запрещают update или целевой родитель запрещает create, весь запрос завершается с 403.

Параметры

Запрос

{"operations": [{"route": "/blog/post-1", "parent": "/archive", "position": 1}, {"route": "/blog/post-2", "position": 3}]}

Ответ

{"data": [{"route": "/archive/post-1", "slug": "post-1", "title": "Post 1", "order": 1, "parent": "/archive"}, {"route": "/blog/post-2", "slug": "post-2", "title": "Post 2", "order": 3, "parent": "/blog"}]}

Коды ответов

Список таксономии¶

GET /taxonomy

Возвращает каждый тип таксономии (например, category, tag) с полным списком значений, используемых на всех страницах. Включается каждый тип, объявленный в site.taxonomies, с пустым списком, если его пока не использует ни одна страница. Внутренние пути к файлам удаляются, поэтому возвращаются только значения терминов.

Ответ

{"data": {"category": ["blog", "docs"], "tag": ["php", "grav", "api"], "author": []}}

Коды ответов

Список языков сайта¶

GET /languages

Возвращает настроенные языки сайта с отображаемыми названиями, флагами RTL и кодами по умолчанию и активного языка. Если многоязычность выключена, возвращает enabled: false, пустой список languages и null для default/active. Используется переключателями языков и интерфейсами переводов.

Ответ

{"data": {"enabled": true, "languages": [{"code": "en", "name": "English", "native_name": "English", "rtl": false, "is_default": true}, {"code": "fr", "name": "French", "native_name": "Français", "rtl": false, "is_default": false}], "default": "en", "active": "en"}}

Коды ответов

Получение токена предпросмотра¶

POST /pages/{route}/preview-token

Выдаёт кратковременный подписанный токен, который позволяет фронтенду отрендерить эту страницу, даже если она не опубликована, — для предпросмотра черновиков. Загрузите фронтенд-URL страницы с ?admin_preview=1&preview_token=<token>; токен открывает доступ только к этой странице. Для модульной секции route — это родительская страница, которую нужно загрузить, а anchor предлагает идентификатор элемента для прокрутки (в остальных случаях он равен null). Токен действует plugins.api.preview_token_ttl секунд (по умолчанию 300, минимум 30). Требуется api.pages.read и доступ на чтение страницы, а при предпросмотре модуля — и её родительской страницы.

Параметры

Ответ

{"data": {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 300, "route": "/blog/my-post", "anchor": null}}

Коды ответов