Менеджер пакетов¶

Эндпоинты для управления пакетами Grav (плагинами и темами) через GPM, включая установку, удаление, обновления и поиск по репозиторию, а также эндпоинты, которые отдают Admin2 страницы админки плагинов и скрипты веб-компонентов.

Список плагинов¶

GET /gpm/plugins

Выводит все установленные плагины с флагами включения, состоянием обновления и сведениями о том, установлен ли каждый плагин через символическую ссылку (это важно для контроля обновлений — пакеты, подключённые символической ссылкой, не следует перезаписывать). Требуется api.gpm.read.

Ответ

{"data": [{"slug": "simplesearch", "name": "SimpleSearch", "version": "3.0.0", "type": "plugin", "description": "A simple search plugin for Grav.", "description_html": "<p>A simple search plugin for Grav.</p>", "author": {"name": "Team Grav", "email": "devs@getgrav.org", "url": "https://getgrav.org"}, "homepage": "https://github.com/getgrav/grav-plugin-simplesearch", "enabled": true, "is_symlink": false, "available_version": "3.0.1", "updatable": true}]}

Коды ответов

Каждый элемент — объект пакета. version — установленная версия; available_version появляется только когда updatable равно true. Необязательные поля схемы (docs, bugs, dependencies, compatibility, keywords, icon) появляются только если плагин их задаёт, а премиум-плагины добавляют premium, licensed, а когда известно — vendor и purchase_url. Плагин, настройки которого выводятся на странице админки, добавляет settings_route (маршрут-хеш), а если эта страница принадлежит другому плагину — ещё и settings_page. name или description, записанные как ключ перевода, переводятся на язык админки вызывающей стороны.

Получение плагина¶

GET /gpm/plugins/{slug}

Возвращает сведения об одном установленном плагине: тот же объект пакета, что и в разделе «Список плагинов», плюс custom_fields, если плагин поставляет компоненты полей Admin Next. Требуется api.gpm.read.

Параметры

Ответ

{"data": {"slug": "simplesearch", "name": "SimpleSearch", "version": "3.0.0", "type": "plugin", "description": "A simple search plugin for Grav.", "description_html": "<p>A simple search plugin for Grav.</p>", "author": {"name": "Team Grav", "email": "devs@getgrav.org", "url": "https://getgrav.org"}, "homepage": "https://github.com/getgrav/grav-plugin-simplesearch", "enabled": true, "is_symlink": false, "available_version": "3.0.1", "updatable": true, "custom_fields": {"simplesearch-preview": "simplesearch-preview"}}}

Коды ответов

Ответ содержит заголовок ETag. Отправьте его обратно как If-None-Match, и API ответит 304 Not Modified с пустым телом, если ничего не изменилось. custom_fields сопоставляет каждый тип поля, который плагин поставляет в admin-next/fields/, с самим собой.

Установка пакета¶

POST /gpm/install

Устанавливает плагин или тему из репозитория GPM вместе со всеми нужными зависимостями. Требуется api.gpm.write. Вызывает onApiBeforePackageInstall и onApiPackageInstalled.

Параметры

Запрос

{"package": "sitemap", "type": "plugin"}

Ответ

{"data": {"message": "Plugin 'sitemap' installed successfully.", "package": "sitemap", "type": "plugin", "dependencies": []}}

Коды ответов

Удаление пакета¶

POST /gpm/remove

Удаляет установленный плагин или тему. Требуется api.gpm.write. Вызывает onApiBeforePackageRemove и onApiPackageRemoved.

Параметры

Запрос

{"package": "sitemap"}

Коды ответов

Проверка обновлений¶

GET /gpm/updates

Проверяет наличие обновлений для плагинов, тем и ядра Grav. Перечисляются только пакеты, у которых есть обновление. total учитывает как сам Grav, так и обновления плагинов и тем. Объект grav содержит is_symlink, чтобы интерфейсы админки могли отключать действие обновления ядра, когда Grav подключён символической ссылкой. Требуется api.gpm.read.

Параметры

Ответ

{"data": {"grav": {"current": "2.1.0", "available": "2.1.1", "updatable": true, "date": "2026-09-18", "is_symlink": false}, "plugins": [{"slug": "form", "name": "Form", "version": "8.1.0", "type": "plugin", "description": "Enables forms handling and processing.", "description_html": "<p>Enables forms handling and processing.</p>", "author": {"name": "Team Grav", "email": "devs@getgrav.org", "url": "https://getgrav.org"}, "homepage": "https://github.com/getgrav/grav-plugin-form", "enabled": true, "is_symlink": false, "available_version": "8.1.1", "updatable": true}], "themes": [], "total": 2, "installed": 14}}

Коды ответов

В grav поле current — установленная версия, а available — последняя версия в репозитории (null, если репозиторий не удалось прочитать). В plugins и themes каждый элемент — объект пакета, где version — установленная версия, а available_version — новая. installed — общее число установленных плагинов и тем.

Поиск по репозиторию¶

GET /gpm/search

Ищет плагины и темы в репозитории GPM. Плагины выводятся раньше тем, и каждый результат содержит флаг installed. Требуется api.gpm.read.

Параметры

Ответ

{"data": [{"slug": "simplesearch", "name": "SimpleSearch", "version": "3.0.1", "type": "plugin", "description": "A simple search plugin for Grav.", "description_html": "<p>A simple search plugin for Grav.</p>", "author": {"name": "Team Grav", "email": "devs@getgrav.org", "url": "https://getgrav.org"}, "homepage": "https://github.com/getgrav/grav-plugin-simplesearch", "installed": true}], "meta": {"pagination": {"page": 1, "per_page": 20, "total": 1, "total_pages": 1}}, "links": {"self": "/api/v1/gpm/search?page=1&per_page=20"}}

Коды ответов

Список тем¶

GET /gpm/themes

Выводит все установленные темы с URL миниатюры и скриншота, состоянием обновления и флагом is_symlink. Для тем enabled означает, что тема активна. Требуется api.gpm.read.

Ответ

{"data": [{"slug": "quark", "name": "Quark", "version": "2.0.4", "type": "theme", "description": "Quark is the default theme for Grav.", "description_html": "<p>Quark is the default theme for Grav.</p>", "author": {"name": "Team Grav", "email": "devs@getgrav.org", "url": "https://getgrav.org"}, "homepage": "https://github.com/getgrav/grav-theme-quark", "enabled": true, "is_symlink": false, "updatable": false, "thumbnail": "/api/v1/thumbnails/8c1f2a9e4b.jpg", "screenshot": "/api/v1/thumbnails/0d3e7b61fa.jpg"}]}

Коды ответов

thumbnail (не больше 500px) и screenshot (не больше 2000px) — это URL вида /thumbnails/{file}, построенные из собственных изображений темы thumbnail и screenshot. Если у темы есть только одно из двух, оба поля используют его; если нет ни одного, оба равны null.

Получение темы¶

GET /gpm/themes/{slug}

Возвращает сведения об одной установленной теме: тот же объект пакета, что и в разделе «Список тем», плюс custom_fields, если тема поставляет компоненты полей Admin Next. Требуется api.gpm.read.

Параметры

Ответ

{"data": {"slug": "quark", "name": "Quark", "version": "2.0.4", "type": "theme", "description": "Quark is the default theme for Grav.", "description_html": "<p>Quark is the default theme for Grav.</p>", "author": {"name": "Team Grav", "email": "devs@getgrav.org", "url": "https://getgrav.org"}, "homepage": "https://github.com/getgrav/grav-theme-quark", "enabled": true, "is_symlink": false, "updatable": false, "thumbnail": "/api/v1/thumbnails/8c1f2a9e4b.jpg", "screenshot": "/api/v1/thumbnails/0d3e7b61fa.jpg"}}

Коды ответов

Ответ содержит заголовок ETag. Отправьте его обратно как If-None-Match, и API ответит 304 Not Modified с пустым телом, если ничего не изменилось.

Обновление пакета¶

POST /gpm/update

Обновляет конкретный установленный плагин или тему до последней версии, сначала устанавливая или обновляя нужные зависимости. Требуется api.gpm.write. Вызывает onApiBeforePackageUpdate и onApiPackageUpdated.

Параметры

Запрос

{"package": "form"}

Ответ

{"data": {"message": "Package 'form' updated successfully.", "package": "form", "type": "plugin", "dependencies": []}}

Коды ответов

Обновление всех пакетов¶

POST /gpm/update-all

Обновляет все обновляемые плагины и темы за один запрос, используя свежие данные репозитория. Каждый пакет обрабатывается независимо — один сбой не прерывает пакет. Требуется api.gpm.write.

Ответ

{"data": {"updated": ["simplesearch", "seo-magic"], "failed": [{"package": "broken-plugin", "error": "Dependency unmet"}], "skipped": [{"package": "form", "reason": "already up to date (installed as a dependency)"}], "cascaded_dependencies": ["form"]}}

Коды ответов

Ответ содержит четыре массива:

• updated: slug'и, которые были обновлены.
• failed: объекты с package и error для пакетов, чьи требования не выполнены или обновление которых не удалось.
• skipped: объекты с package и reason для пакетов, уже обновлённых как зависимость более раннего пакета в рамках этой операции.
• cascaded_dependencies: slug'и, установленные или обновлённые попутно как зависимости.

Просмотр тем репозитория¶

GET /gpm/repository/themes

Выводит все темы, доступные в репозитории GPM, с флагом installed у каждой. Поддерживает постраничную разбивку и текстовый поиск q. 502, если репозиторий недоступен. Требуется api.gpm.read.

Параметры

Ответ

{"data": [{"slug": "quark", "name": "Quark", "version": "2.0.4", "type": "theme", "description": "Quark is the default theme for Grav.", "description_html": "<p>Quark is the default theme for Grav.</p>", "author": {"name": "Team Grav", "email": "devs@getgrav.org", "url": "https://getgrav.org"}, "homepage": "https://github.com/getgrav/grav-theme-quark", "screenshot": "https://getgrav.org/images/quark-screenshot.jpg", "installed": true}], "meta": {"pagination": {"page": 1, "per_page": 20, "total": 120, "total_pages": 6}}, "links": {"self": "/api/v1/gpm/repository/themes?page=1&per_page=20", "next": "/api/v1/gpm/repository/themes?page=2&per_page=20", "last": "/api/v1/gpm/repository/themes?page=6&per_page=20"}}

Коды ответов

В результатах репозитория version — последняя версия в репозитории, а screenshot — полный URL скриншота из репозитория. Премиум-темы добавляют premium, licensed, а когда известно — vendor и purchase_url.

Получение README¶

GET /gpm/plugins/{slug}/readme

Возвращает необработанное содержимое README.md установленного плагина или темы. Также доступно по адресу /gpm/themes/{slug}/readme. Требуется api.gpm.read.

Параметры

Ответ

{"data": {"content": "# My Plugin\n\nThis plugin does..."}}

Коды ответов

Получение журнала изменений¶

GET /gpm/plugins/{slug}/changelog

Возвращает необработанное содержимое CHANGELOG.md установленного плагина или темы. Также доступно по адресу /gpm/themes/{slug}/changelog. Требуется api.gpm.read.

Параметры

Ответ

{"data": {"content": "# v1.2.0\n## 01/15/2025\n\n* Added feature X..."}}

Коды ответов

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

GET /gpm/plugins/{slug}/page

Возвращает описание страницы админки для плагина: тип страницы, ссылку на схему, эндпоинты данных и сохранения, а также кнопки действий. Порядок поиска: 1) событие onApiPluginPageInfo, 2) admin-next/pages/{slug}.yaml, 3) admin-next/pages/{slug}.js (режим выведенного компонента). Требуется только api.access; данные, лежащие в основе страницы, подчиняются собственным разрешениям плагина.

Параметры

Ответ

{"data": {"id": "license-manager", "plugin": "license-manager", "title": "License Manager", "icon": "fa-key", "page_type": "blueprint", "blueprint": "licenses", "data_endpoint": "/licenses/form-data", "save_endpoint": "/licenses", "actions": [{"id": "save", "label": "Save", "icon": "fa-check", "primary": true}], "has_custom_component": false}}

Коды ответов

Описание может также содержать settings_route — маршрут-хеш внутри страницы, где выводятся настройки плагина, и settings_page — slug другого установленного плагина, страница админки которого их выводит. settings_page сохраняется только вместе с действительным settings_route.

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

GET /gpm/plugins/{slug}/page-script

Отдаёт JavaScript-файл веб-компонента уровня страницы для плагина. Файл загружается из admin-next/pages/{slug}.js в папке плагина.

Параметры

Коды ответов

Требуется только api.access, поэтому любой администратор, имеющий доступ к экранам плагина, может загрузить их без прав менеджера пакетов. Скрипт отдаётся как application/javascript с Cache-Control: private, no-cache и ETag, построенным по времени изменения и размеру файла, поэтому повторный запрос с If-None-Match получает пустой 304, пока файл не изменится.

Получение журнала изменений Grav¶

GET /gpm/grav/changelog

Возвращает журнал изменений ядра Grav для всех выпусков новее установленной версии, объединённый в один Markdown-документ с заголовком # v{version} ({date}) для каждого выпуска. content — пустая строка, когда Grav обновлён до последней версии. Требуется api.gpm.read.

Параметры

Ответ

{"data": {"content": "# v2.1.1 (09/18/2026)\n\n1. [](#bugfix)\n    * Fixed ..."}}

Коды ответов

Обновление ядра Grav¶

POST /gpm/upgrade

Обновляет ядро Grav. Отказывается работать, если Grav установлен через символическую ссылку (типично для сред разработки и монорепозиториев). Сначала выполняет предварительные проверки обновления. Требуется api.gpm.write. Вызывает onApiBeforeGravUpgrade и onApiGravUpgraded вокруг обновления.

Параметры

Запрос

{"override": false}

Ответ

{"data": {"message": "Grav upgraded successfully.", "previous_version": "2.1.0", "new_version": "2.1.1"}}

Коды ответов

Когда предварительные проверки блокируют обновление, ответ 409 — это обычные данные data, а не ошибка:

{
    "data": {
        "status": "preflight_failed",
        "message": "Upgrade blocked by preflight checks.",
        "blocking": [
            "Some enabled plugins/themes have not been marked as compatible with Grav 2.2. Disable them before continuing."
        ],
        "warnings": [],
        "incompatible_packages": { "target": "2.2" },
        "can_override": true
    }
}

Прямая установка¶

POST /gpm/direct-install

Устанавливает плагин или тему из URL или загруженного zip-архива в обход поиска в репозитории GPM. Принимает либо JSON-тело с url, либо multipart-загрузку с полем file. Удобно для приватных и неопубликованных пакетов, предварительных сборок или локальной разработки. Требуется api.gpm.write.

Параметры

Запрос

{"url": "https://downloads.example.com/builds/my-plugin-1.0.0.zip"}

Ответ

{"data": {"message": "Package installed successfully via direct install."}}

Коды ответов

Список плагинов репозитория¶

GET /gpm/repository/plugins

Выводит все плагины, доступные в репозитории GPM, с флагом installed у каждого. Поддерживает постраничную разбивку (page, per_page — максимум 2000, чтобы модальное окно установки могло получить полный список) и текстовый поиск q. 502, если репозиторий недоступен. Требуется api.gpm.read.

Параметры

Ответ

{"data": [{"slug": "simplesearch", "name": "SimpleSearch", "version": "3.0.1", "type": "plugin", "description": "A simple search plugin for Grav.", "description_html": "<p>A simple search plugin for Grav.</p>", "author": {"name": "Team Grav", "email": "devs@getgrav.org", "url": "https://getgrav.org"}, "homepage": "https://github.com/getgrav/grav-plugin-simplesearch", "keywords": ["search", "plugin"], "installed": true}], "meta": {"pagination": {"page": 1, "per_page": 50, "total": 250, "total_pages": 5}}, "links": {"self": "/api/v1/gpm/repository/plugins?page=1&per_page=50", "next": "/api/v1/gpm/repository/plugins?page=2&per_page=50", "last": "/api/v1/gpm/repository/plugins?page=5&per_page=50"}}

Коды ответов

В результатах репозитория version — последняя версия в репозитории. Чтобы сравнить с установленным, используйте Список плагинов или Проверку обновлений. Премиум-плагины добавляют premium, licensed, а когда известно — vendor и purchase_url.

Получение пакета репозитория¶

GET /gpm/repository/{slug}

Возвращает полные сведения из репозитория о плагине или теме (в зависимости от того, что соответствует slug), плюс флаг installed. Требуется api.gpm.read.

Параметры

Ответ

{"data": {"slug": "simplesearch", "name": "SimpleSearch", "version": "3.0.1", "type": "plugin", "description": "A simple search plugin for Grav.", "description_html": "<p>A simple search plugin for Grav.</p>", "author": {"name": "Team Grav", "email": "devs@getgrav.org", "url": "https://getgrav.org"}, "homepage": "https://github.com/getgrav/grav-plugin-simplesearch", "keywords": ["search", "plugin"], "installed": true}}

Коды ответов

Получение скрипта пользовательского поля¶

GET /gpm/plugins/{slug}/field/{type}

Отдаёт JavaScript-веб-компонент для пользовательского типа поля схемы плагина. Также доступно по адресу /gpm/themes/{slug}/field/{type} для полей, предоставляемых темой. Admin2 загружает их по требованию при рендеринге схемы, использующей неизвестный тип поля. Соглашение: файл находится в admin-next/fields/{type}.js внутри пакета. В отличие от остальных эндпоинтов скриптов, этот отдаёт и поля выключенного плагина, чтобы его форму настроек можно было отредактировать до включения.

Параметры

Коды ответов

Требуется только api.access, поэтому любой администратор, имеющий доступ к экранам плагина, может загрузить их без прав менеджера пакетов. Скрипт отдаётся как application/javascript с Cache-Control: private, no-cache и ETag, построенным по времени изменения и размеру файла, поэтому повторный запрос с If-None-Match получает пустой 304, пока файл не изменится.

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

GET /gpm/plugins/{slug}/report-script/{reportId}

Отдаёт веб-компонент для пользовательского отчёта, показанного на странице отчётов Admin2. Плагины поставляют файл в admin-next/reports/{reportId}.js и регистрируют отчёт через событие onApiGenerateReports. Admin2 загружает скрипт только при рендеринге соответствующего отчёта.

Параметры

Коды ответов

Требуется только api.access, поэтому любой администратор, имеющий доступ к экранам плагина, может загрузить их без прав менеджера пакетов. Скрипт отдаётся как application/javascript с Cache-Control: private, no-cache и ETag, построенным по времени изменения и размеру файла, поэтому повторный запрос с If-None-Match получает пустой 304, пока файл не изменится.

Получение скрипта плавающего виджета¶

GET /gpm/plugins/{slug}/widget-script

Отдаёт веб-компонент для плавающего виджета, предоставленного плагином. Соглашение: файл находится в admin-next/widgets/{slug}.js. Регистрируется через событие onApiFloatingWidgets и выводится в GET /floating-widgets.

Параметры

Коды ответов

Требуется только api.access, поэтому любой администратор, имеющий доступ к экранам плагина, может загрузить их без прав менеджера пакетов. Скрипт отдаётся как application/javascript с Cache-Control: private, no-cache и ETag, построенным по времени изменения и размеру файла, поэтому повторный запрос с If-None-Match получает пустой 304, пока файл не изменится.

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

GET /gpm/plugins/{slug}/panel-script

Отдаёт веб-компонент для контекстной панели, предоставленной плагином (панель в правой панели, показываемая при редактировании страниц или другого контента). Соглашение: файл находится в admin-next/panels/{slug}.js. Регистрируется через событие onApiContextPanels и выводится в GET /context-panels.

Параметры

Коды ответов

Требуется только api.access, поэтому любой администратор, имеющий доступ к экранам плагина, может загрузить их без прав менеджера пакетов. Скрипт отдаётся как application/javascript с Cache-Control: private, no-cache и ETag, построенным по времени изменения и размеру файла, поэтому повторный запрос с If-None-Match получает пустой 304, пока файл не изменится.

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

GET /gpm/plugins/{slug}/modal-script/{modalId}

Отдаёт веб-компонент для модального диалога, предоставленного плагином. Соглашение: файл находится в admin-next/modals/{modalId}.js и монтируется как пользовательский элемент grav-{slug}--modal-{modalId}. Открывается из веб-компонента плагина через window.__GRAV_DIALOGS.open() или напрямую из элемента панели меню с намерением modal. Плагин может поставлять несколько разных модальных окон, каждое со своим modalId.

Параметры

Коды ответов

Требуется только api.access, поэтому любой администратор, имеющий доступ к экранам плагина, может загрузить их без прав менеджера пакетов. Скрипт отдаётся как application/javascript с Cache-Control: private, no-cache и ETag, построенным по времени изменения и размеру файла, поэтому повторный запрос с If-None-Match получает пустой 304, пока файл не изменится.

Получение набора пользовательских полей¶

GET /gpm/plugins/{slug}/fields

Отдаёт все веб-компоненты пользовательских полей пакета одним ответом в виде JSON-объекта, сопоставляющего каждый тип поля с его исходным кодом JavaScript. Admin2 запрашивает его один раз на пакет вместо одного запроса на каждый тип поля. Также доступно по адресу /gpm/themes/{slug}/fields. Отдаётся и для выключенных плагинов, чтобы их формы настроек оставались редактируемыми.

Параметры

Ответ

{"seo-magic-preview": "class SeoMagicPreview extends HTMLElement { ... }", "seo-magic-keywords": "class SeoMagicKeywords extends HTMLElement { ... }"}

Коды ответов

Тело — это чистый JSON-объект, без обычной обёртки data. Он отдаётся с Cache-Control: private, no-cache и ETag, построенным по имени, времени изменения и размеру каждого файла, поэтому повторная проверка стоит только 304, пока какой-либо файл поля не изменится. Требуется только api.access.