Справочник REST API¶

Базовый URL¶

Все эндпоинты имеют префикс: {site_url}/api/v1

Аутентификация¶

Публичные эндпоинты, не требующие аутентификации, — это всё под /auth/ (токен, проверка 2FA, обновление, отзыв, восстановление и сброс пароля, настройка, принятие приглашения, политика паролей, капча и SSO), GET /translations/{lang}, GET /thumbnails/{file} и GET /ping. Плагины могут добавлять собственные публичные маршруты через событие onApiCollectPublicRoutes. Всё остальное требует аутентификации через:

• ключ API (заголовок X-API-Key или параметр запроса ?api_key=),
• JWT-токен доступа (предпочтительно как X-API-Token, принимается и как Authorization: Bearer), или
• активную сессию Grav (проброс).

Подробности, включая причины, по которым X-API-Token предпочтительнее Authorization: Bearer на хостах FastCGI / PHP-FPM, см. в разделе Аутентификация.

Окружения¶

API учитывает окружения Grav. Передайте X-Grav-Environment: <hostname>, чтобы использовать конфигурацию конкретного окружения.

Общие коды ответов¶

В этом разделе¶

• Аутентификация — Эндпоинты для входа и выхода по JWT, сброса пароля, двухфакторной проверки, первоначальной настройки, политики паролей, принятия приглашения, капчи при входе, входа через SSO и получения текущей сессии. Всё под /auth/…
• Страницы — Эндпоинты для управления страницами Grav: список, создание, обновление, удаление, копирование, перемещение и изменение порядка, а также переводы страниц, пакетные операции, токены предпросмотра черновиков, таксономия и список языков сайта.
• Медиафайлы — Эндпоинты для управления медиафайлами, прикреплёнными к страницам, и медиафайлами уровня сайта, их метаданными в .meta.yaml, ручным порядком папок медиафайлов сайта и файлами, сохранёнными полями схем с типом «файл». Для чтения нужен api.media.read и…
• Конфигурация — Эндпоинты для чтения, обновления и отката областей конфигурации Grav, включая system, site, media, security, plugins, themes и пользовательские области, задаваемые сайтом, а также конфигурацию учётных записей Flex. Для чтения нужны…
• Пользователи — Эндпоинты для управления учётными записями пользователей (список, создание, обновление и удаление пользователей, аватары, ключи API и 2FA), группами пользователей и приглашениями.
• Менеджер пакетов — Эндпоинты для управления пакетами Grav (плагинами и темами) через GPM, включая установку, удаление, обновления и поиск по репозиторию, а также эндпоинты, которые отдают плагинам страницы админки и скрипты веб-компонентов…
• Система — Эндпоинты для операций уровня системы, включая информацию, управление кэшем, окружения, журналы, резервные копии, переводы и отчёты.
• Схемы — Эндпоинты для получения схем, используемых для шаблонов страниц, учётных записей пользователей, групп, плагинов, тем, конфигурации и определений разрешений, а также GET /blueprint-files, который перечисляет файлы для папок схем…
• Боковая панель — Собирает элементы навигации боковой панели, зарегистрированные плагинами. Вызывает событие onApiSidebarItems, отбрасывает элементы, на которые у пользователя нет разрешения authorize, удаляет authorize, переводит метки, являющиеся ключами перевода, в…
• Панель управления — Эндпоинты для данных панели управления, включая статистику, уведомления, ленту новостей, популярность просмотров страниц, проверку доступности хранилища и настраиваемый макет виджетов.
• Планировщик — Управление планировщиком Grav на основе cron. Просмотр зарегистрированных заданий, проверка статуса установки cron, просмотр истории выполнения и запуск вручную.
• Вебхуки — Регистрируйте исходящие HTTP-вебхуки, которые срабатывают при событиях записи в API (изменения страниц, медиафайлов и пользователей, обновления конфигурации, установки через GPM, обновления Grav). У каждого вебхука есть URL, список фильтров событий, необязательные собственные заголовки…
• Интеграция с Admin2 — Эндпоинты, обеспечивающие расширяемость и предпочтения Admin2: элементы панели инструментов, плавающие виджеты, выезжающие контекстные панели, панели страниц настроек, реестр пользовательских компонентов полей от плагинов, markdown…
• Flex-объекты — Эндпоинты для управления директориями Flex-объектов и их записями: список директорий и схем, полный CRUD для объектов, экспорт YAML и медиафайлы отдельных объектов (файлы, хранящиеся рядом с объектом в его собственной папке).
• Журнал аудита — Чтение журнала аудита админки: журнала действий, выполненных через API, с указанием кто, когда, с какого IP и над чем их совершил. Поскольку Admin Next делает всё через API, журнал охватывает весь Admin Next…
• Редактор переводов — Эндпоинты, лежащие в основе редактора переводов Admin Next. Они позволяют просматривать каждую строку перевода, поставляемую ядром Grav, плагинами и темами, видеть, насколько полон каждый язык, и переопределять любую строку для этого сайта…
• MCP — Манифесты инструментов для серверов Model Context Protocol. У сервера MCP, такого как Grav MCP Server, уже есть инструменты для всего, что делает сам плагин API, но он не может знать о маршрутах, которые добавляют другие плагины через…
• Демо-режим — Управление движком сброса демо-режима для публичных демо-сайтов. Демо-учётная запись — это любая учётная запись с access.api.demo. Демо-учётные записи могут читать, но запись заблокирована, кроме разрешений, перечисленных в…