System

Endpoints for system-level operations including information, cache management, translations, and blueprints.

System Info

GET


            /system/info

Rich system information: Grav / PHP versions, loaded extensions, server software, current environment, installed plugins and themes, and a structured PHP configuration summary (uploads, memory, error handling, sessions, OPcache, security, locale). Intended to populate the Admin2 "System Info" / support pages.

JSON

{"data": {"grav_version": "2.0.0-beta.1", "php_version": "8.3.2", "php_extensions": ["Core", "date", "pcre"], "server_software": "Apache/2.4.58", "environment": "localhost", "plugins": [...], "themes": [...], "php_config": {"Upload & POST": {"file_uploads": "On", "upload_max_filesize": "64M"}}}}

Response Codes

200 Info returned.

401 Unauthorized.

403 Missing `api.system.read` permission.

Clear Cache

DELETE


            /cache

Clear the system cache. Defaults to `standard` scope (the same as `bin/grav cache clear`), matching the typical "flush cache" button. Use `scope=all` to also drop images/assets caches.

Parameters

Name	Type	Description
scope optional	string	One of `all`, `standard`, `images`, `assets`, `tmp`. Defaults to `standard`.

JSON

{"data": {"scope": "standard", "message": "Cache cleared successfully (scope: standard).", "details": {"cache": "cleared"}}}

Response Codes

200 Cache cleared.

400 Invalid cache scope.

401 Unauthorized.

403 Missing `api.system.write` permission.

Get Translations

GET


            /translations/{lang}

Get translation strings for a language.

Parameters

Name	Type	Description
lang required	string	Language code (e.g. en, fr, de)

Response Codes

200 Success

401 Unauthorized

List Blueprints

GET


            /blueprints/pages/{template}

Get the blueprint schema for a page template.

Parameters

Name	Type	Description
template required	string	The page template name (e.g. default, blog, post)

Response Codes

200 Success

401 Unauthorized

404 Template blueprint not found

Ping

GET


            /ping

Lightweight health check and keep-alive endpoint. Validates the authentication token and returns a minimal response.

JSON

{"data": {"pong": true}}

Response Codes

200 Success

401 Unauthorized

List Environments

GET


            /system/environments

List available Grav environments. Scans user/env/ for environment-specific configuration directories.

JSON

{"data": {"current": "localhost", "environments": [{"name": "default", "active": false}, {"name": "localhost", "active": true}]}}

Response Codes

200 Success

401 Unauthorized

Get Logs

GET


            /system/logs

Read system log entries from grav.log with pagination and optional level filtering. Entries are returned in reverse chronological order.

Parameters

Name	Type	Description
page optional	integer	Page number for pagination (default: 1)
per_page optional	integer	Number of results per page (default: 20, max: 100)
level optional	string	Filter by log level (e.g. DEBUG, INFO, WARNING, ERROR, CRITICAL)

JSON

{"data": [{"date": "2025-03-15 10:30:00", "logger": "grav", "level": "WARNING", "message": "Plugin X deprecated method"}], "meta": {"total": 150, "page": 1, "per_page": 20}}

Response Codes

200 Success

401 Unauthorized

Reports

GET


            /reports

Get plugin-extensible diagnostic reports. Built-in reports include a Security Check (XSS scan) and YAML Linter. Plugins can add their own reports via the onApiGenerateReports event.

JSON

{
    "data": [
        {
            "id": "security-check",
            "title": "Grav Security Check",
            "provider": "core",
            "component": null,
            "status": "success",
            "message": "Security Scan complete: No issues found.",
            "items": []
        },
        {
            "id": "yaml-linter",
            "title": "Grav Yaml Linter",
            "provider": "core",
            "component": null,
            "status": "success",
            "message": "YAML Linting: No errors found.",
            "items": []
        },
        {
            "id": "problems",
            "title": "Grav Potential Problems",
            "provider": "problems",
            "component": "problems-report",
            "status": "success",
            "message": "No critical problems detected.",
            "items": [
                {
                    "id": "PHP Minimum Version",
                    "level": "critical",
                    "status": true,
                    "msg": "Your PHP 8.5.4 is greater than the minimum of 8.3.0 required"
                }
            ]
        }
    ]
}

Response Codes

200 Reports returned successfully

401 Unauthorized

403 Forbidden - requires api.reports.read permission

Report Structure

Each report in the response array contains:

Field	Type	Description
`id`	string	Unique report identifier
`title`	string	Human-readable report title
`provider`	string	Source — `core` for built-in, or plugin slug
`component`	string\|null	Web component ID for custom rendering, or `null` for default
`status`	string	Overall status: `success`, `warning`, or `error`
`message`	string	Summary message
`items`	array	Report-specific detail items

Built-in Reports

Security Check — Scans all pages for potential XSS vulnerabilities. Items contain route and field for each issue found.
YAML Linter — Checks all YAML files for syntax errors. Items contain file and error for each issue found.

Plugin Reports

Plugins add reports by listening for the onApiGenerateReports event. When a report specifies a component, the admin frontend loads the plugin's web component from GET /gpm/plugins/{provider}/report-script/{component}.

See the Plugin API Integration guide for implementation details.

Create Backup

POST


            /system/backup

Trigger a backup of the site. Uses Grav's built-in `Backups` class, writes a dated zip to the configured backup location, and returns the filename, path, size, and creation timestamp. Admin2 uses this for the "Backup now" action on the dashboard.

JSON

{"data": {"filename": "default-20260417120000.zip", "path": "/path/to/backup/default-20260417120000.zip", "size": 1048576, "date": "2026-04-17T12:00:00+00:00"}}

Response Codes

201 Backup created; Location header points to `/system/backups`.

401 Unauthorized.

403 Missing `api.system.write` permission.

List Backups

GET


            /system/backups

List existing backup files (filename, title, date, size), plus the configured purge policy and the number of configured backup profiles.

JSON

{"data": {"backups": [{"filename": "default-20260417120000.zip", "title": "Default", "date": "2026-04-17T12:00:00+00:00", "size": 1048576}], "purge": {"max_backups_count": 25}, "profiles_count": 1}}

Response Codes

200 Backup list returned.

401 Unauthorized.

403 Missing `api.system.read` permission.

Delete Backup

DELETE


            /system/backups/{filename}

Delete a backup zip. The filename is validated to prevent path traversal — must be a bare basename ending in `.zip`.

Parameters

Name	Type	Description
filename required	string	The backup filename (bare basename, e.g. `default-20260417120000.zip`).

Response Codes

204 Backup deleted.

400 Invalid filename.

401 Unauthorized.

403 Missing `api.system.write` permission.

404 Backup not found.

Download Backup

GET


            /system/backups/{filename}/download

Stream a backup zip file to the caller. Returns `application/zip` with a `Content-Disposition: attachment` header.

Parameters

Name	Type	Description
filename required	string	The backup filename (bare basename ending in `.zip`).

Response Codes

200 Backup streamed.

400 Invalid filename.

401 Unauthorized.

403 Missing `api.system.read` permission.

404 Backup not found.

System Info Report

GET


            /systeminfo

Generate a compact, self-contained system report aggregating PHP info (version, SAPI, extensions, memory/upload limits), Grav version, and disk free/total space. Lighter than `/system/info` — intended for the dashboard "System Status" widget rather than the full Admin2 System Info page.

JSON

{"data": {"php": {"version": "8.3.2", "sapi": "fpm-fcgi", "extensions": ["Core", "date"], "memory_limit": "256M", "max_execution_time": "60", "upload_max_filesize": "64M", "post_max_size": "64M"}, "grav": {"version": "2.0.0-beta.1", "php_version": "8.3.2"}, "disk": {"free_space": 10737418240, "total_space": 53687091200}}}

Response Codes

200 Report returned.

401 Unauthorized.

403 Missing `api.system.read` permission.