Grav

https://learn.getgrav.org/
Admin
Grav is a Fast, Simple, and Flexible file-based Web-platform requiring zero installation; users just...
Tokens:363,477
Snippets:4,867
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Direct Install Request and Response

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Examples for the direct install endpoint, showing the request body for a URL-based installation and the success response.

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

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

--------------------------------

### GET /auth/setup

Source: https://learn.getgrav.org/20/api/endpoints/authentication

Checks whether the instance requires first-run setup. Returns setup_required: true only when no accounts exist.

```APIDOC
## GET /auth/setup

### Description
Check whether the instance requires first-run setup. Returns `setup_required: true` only when `user/accounts/` is empty. Public (no auth required).

### Method
GET

### Endpoint
/auth/setup

### Response
#### Success Response (200)
- **data** (object) - Contains the setup status.
  - **setup_required** (boolean) - Indicates if setup is needed.

#### Response Example
{
  "data": {"setup_required": true}
}
```

--------------------------------

### Check Setup Status

Source: https://learn.getgrav.org/20/api/endpoints/authentication

Returns the setup status of the instance. Use this to determine if the setup wizard should be displayed.

```json
{"data": {"setup_required": true}}
```

--------------------------------

### Full Configuration Example

Source: https://learn.getgrav.org/20/grav-premium/helios

A complete example of the Helios configuration file.

```yaml
enabled: true

appearance:
  theme: system
  selector: true
  storage: true

colors:
  primary: '#3B82F6'
  primary_hover: '#2563EB'
  primary_text: '#FFFFFF'
  accent: '#8B5CF6'
  primary_dark: '#60A5FA'
  primary_dark_hover: '#93C5FD'
  primary_dark_text: '#111827'
  accent_dark: '#A78BFA'

fonts:
  body: inter
  code: jetbrains-mono

logo:
  text: 'My Documentation'
  height: h-8

header:
  menu:
    - route: '/changelog'
      label: 'Changelog'

navigation:
  sidebar_width: 280
  content_width: 768
  toc_position: right
  toc_depth: 3
  breadcrumbs: true
  prev_next: true
  scroll_spy: true

search:
  enabled: true
  provider: simplesearch
  keyboard_shortcut: true

versioning:
  enabled: false

github:
  enabled: false

api:
  enabled: true

htmx:
  enabled: false
```

--------------------------------

### Install Dependencies

Source: https://learn.getgrav.org/20/advanced/grav-cli

Installs required Grav plugins and themes by navigating to the project root and running the install command.

```bash
$ cd ~/webroot/my-grav-project
bin/grav install
```

--------------------------------

### GET /licenses/products-status

Source: https://learn.getgrav.org/20/api/developer-guide

Retrieves the installation status of licensed products.

```APIDOC
## GET /licenses/products-status

### Description
Returns the installation status (enabled, disabled, installed, or not installed) of licensed products. This endpoint requires the X-API-Token header for authentication.

### Method
GET

### Endpoint
/licenses/products-status
```

--------------------------------

### Index Command Examples

Source: https://learn.getgrav.org/20/grav-premium/yetisearch-pro

Common usage examples for rebuilding indices.

```bash
# Full rebuild for one language
bin/plugin yetisearch-pro index --index pages --lang 17 --flush

# Full rebuild for all languages (per_language)
bin/plugin yetisearch-pro index --index pages --flush

# Index a specific suffixed index
bin/plugin yetisearch-pro index --index pages_17 --flush
```

--------------------------------

### Install Downloads Pro

Source: https://learn.getgrav.org/20/grav-premium/downloads-pro

Installs the Downloads Pro plugin via the command line.

```bash
$ bin/gpm install downloads-pro
```

--------------------------------

### Install a Package

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Sends a POST request to install a specific plugin or theme by slug.

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

--------------------------------

### Start the built-in Grav development server

Source: https://learn.getgrav.org/20/basics/installation

Execute this command from the root directory of the Grav installation to launch the local development server.

```bash
bin/grav server
```

--------------------------------

### Install Apache on WSL

Source: https://learn.getgrav.org/20/webservers-hosting/windows-subsystem-for-linux

Use the apt package manager to install the Apache web server.

```bash
sudo apt install apache2
```

--------------------------------

### Query Command Examples

Source: https://learn.getgrav.org/20/grav-premium/yetisearch-pro

Common usage examples for searching indices with various options.

```bash
# Fuzzy search in a per-language index
bin/plugin yetisearch-pro query "install theme" --index pages_17 --fuzzy

# Search with language in single-index strategy
bin/plugin yetisearch-pro query "installer" --index pages --lang fr

# With filters and sort
bin/plugin yetisearch-pro query "config" -x pages_17 -F "taxonomy.category=plugins" -s "title:asc"
```

--------------------------------

### List Repository Plugins Response

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Example JSON response for the GET /gpm/repository/plugins endpoint.

```json
{"data": [{"slug": "simplesearch", "name": "SimpleSearch", "version": "2.4.0", "installed": true, "installed_version": "2.3.0"}], "meta": {"total": 250, "page": 1, "per_page": 50}}
```

--------------------------------

### Install API Documentation Plugin

Source: https://learn.getgrav.org/20/grav-premium/helios

Installs the optional plugin for importing OpenAPI/Swagger specifications.

```bash
$ bin/gpm install api-doc-import
```

--------------------------------

### Install Dokku on a VM

Source: https://learn.getgrav.org/20/webservers-hosting/paas/dokku

Run these commands on a fresh VM with root access to install the latest stable version of Dokku.

```bash
wget https://raw.githubusercontent.com/dokku/dokku/v0.17.9/bootstrap.sh
sudo DOKKU_TAG=v0.17.9 bash bootstrap.sh
```

--------------------------------

### Install Revisions Pro via GPM

Source: https://learn.getgrav.org/20/grav-premium/revisions-pro

Execute this command from the root of your Grav installation to install the plugin.

```bash
bin/gpm install revisions-pro
```

--------------------------------

### Install Plugin via GPM

Source: https://learn.getgrav.org/20/plugins/plugin-install

Execute this command from the root of your Grav installation to download and install a plugin.

```bash
bin/gpm install NAME
```

--------------------------------

### Install Image Optimize via GPM

Source: https://learn.getgrav.org/20/grav-premium/image-optimize

Use the Grav Package Manager to install the plugin from the root of your Grav installation.

```bash
bin/gpm install image-optimize
```

--------------------------------

### Install Shortcode Core plugin

Source: https://learn.getgrav.org/20/content/creating-a-shortcode

Use the Grav Package Manager to install the required Shortcode Core plugin.

```bash
bin/gpm install shortcode-core
```

--------------------------------

### Install YetiSearch Pro

Source: https://learn.getgrav.org/20/grav-premium/yetisearch-pro

Installs the YetiSearch Pro plugin using the Grav Package Manager.

```bash
$ bin/gpm install yetisearch-pro
```

--------------------------------

### Verify Plugin Installation Path

Source: https://learn.getgrav.org/20/grav-premium/email-office365

The expected directory structure after manual installation.

```text
/your/site/grav/user/plugins/email-office365
```

--------------------------------

### Install Language Switcher Plugin

Source: https://learn.getgrav.org/20/content/multi-language

Use the GPM command to install the language switcher plugin.

```bash
bin/gpm install langswitcher
```

--------------------------------

### Install PHP on Ubuntu

Source: https://learn.getgrav.org/20/webservers-hosting/windows-subsystem-for-linux

Installs the latest PHP version available in the repository.

```bash
sudo apt install php
```

--------------------------------

### Install Site Toolbox Plugins

Source: https://learn.getgrav.org/20/grav-premium/site-toolbox

Install the required plugins for the Site Toolbox suite using the Grav Package Manager.

```bash
$ bin/gpm install svg-icons warm-cache zapier-rss mega-frontmatter
```

--------------------------------

### PHP Version Output Example

Source: https://learn.getgrav.org/20/webservers-hosting/windows-subsystem-for-linux

Example output returned by the php -v command.

```text
PHP 7.2.7-0ubuntu0.18.04.2 (cli) (built: Jul  4 2018 16:55:24) ( NTS )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.2.0, Copyright (c) 1998-2018 Zend Technologies
```

--------------------------------

### Install Lightbox Gallery Plugin

Source: https://learn.getgrav.org/20/grav-premium/lightbox-gallery

Installs the Lightbox Gallery plugin and its required dependencies using GPM.

```bash
$ bin/gpm install lightbox-gallery
```

--------------------------------

### Install Grav from GitHub

Source: https://learn.getgrav.org/20/basics/installation

Manually clone the Grav repository and install dependencies using Composer and the Grav CLI.

```bash
cd ~/webroot
git clone -b master https://github.com/getgrav/grav.git
```

```bash
cd ~/webroot/grav
composer install --no-dev -o
```

```bash
cd ~/webroot/grav
bin/grav install
```

--------------------------------

### Get Theme Response

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Example JSON response for the GET /gpm/themes/{slug} endpoint.

```json
{"data": {"slug": "quark", "name": "Quark", "version": "2.0.0", "updatable": false, "is_symlink": false, "screenshot": "/api/v1/thumbnails/quark-screen.jpg"}}
```

--------------------------------

### Clone and Navigate to Heroku PHP Example

Source: https://learn.getgrav.org/20/webservers-hosting/paas/heroku

Downloads the starter repository and enters the project directory.

```bash
git clone https://github.com/heroku/php-getting-started.git your-folder
```

```bash
cd your-folder
```

--------------------------------

### Grav server output example

Source: https://learn.getgrav.org/20/webservers-hosting/servers/grav-built-in

Example output displayed in the terminal when the Grav server is running.

```text
➜ bin/grav server

Grav Web Server
===============

Tailing Web Server log file (/Users/joeblow/.symfony/log/96e710135f52930318e745e901e4010d0907cec3.log)
Tailing PHP-FPM log file (/Users/joeblow/.symfony/log/96e710135f52930318e745e901e4010d0907cec3/53fb8ec204547646acb3461995e4da5a54cc7575.log)
Tailing PHP-FPM log file (/Users/joeblow/.symfony/log/96e710135f52930318e745e901e4010d0907cec3/53fb8ec204547646acb3461995e4da5a54cc7575.log)

[OK] Web server listening
The Web server is using PHP FPM 8.0.8
https://127.0.0.1:8000


[Web Server ] Jul 30 14:54:53 |DEBUG  | PHP    Reloading PHP versions
[Web Server ] Jul 30 14:54:54 |DEBUG  | PHP    Using PHP version 8.0.8 (from default version in $PATH)
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    fpm is running, pid 64992
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    ready to handle connections
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    fpm is running, pid 64992
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    ready to handle connections
[Web Server ] Jul 30 14:54:54 |INFO   | PHP    listening path="/usr/local/Cellar/php/8.0.8_2/sbin/php-fpm" php="8.0.8" port=65140
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    fpm is running, pid 73709
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    ready to handle connections
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    fpm is running, pid 73709
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    ready to handle connections
```

--------------------------------

### Get Repository Package Response

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Example JSON response for the GET /gpm/repository/{slug} endpoint.

```json
{"data": {"slug": "simplesearch", "name": "SimpleSearch", "version": "2.4.0", "description": "...", "author": {"name": "Trilby Media"}, "installed": false}}
```

--------------------------------

### Install Form Plugin

Source: https://learn.getgrav.org/20/forms/forms

Command to install the Form plugin via the Grav Package Manager.

```bash
bin/gpm install form
```

--------------------------------

### Get Page Response

Source: https://learn.getgrav.org/20/api/endpoints/pages

Example JSON response for a successful GET request to retrieve page content and metadata.

```json
{"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 /auth/setup

Source: https://learn.getgrav.org/20/api/endpoints/authentication

Creates the initial super-admin account on a fresh install. Active only while no accounts exist.

```APIDOC
## POST /auth/setup

### Description
One-time first-run setup — creates the initial super-admin account on a fresh Grav 2.0 install. Active only while `user/accounts/` is empty.

### Method
POST

### Endpoint
/auth/setup

### Parameters
#### Request Body
- **username** (string) - Required - Username (3–64 chars; letters, numbers, hyphens, underscores).
- **password** (string) - Required - Password (minimum 8 characters).
- **email** (string) - Required - A valid email address.
- **fullname** (string) - Optional - Display name for the account.
- **title** (string) - Optional - User title (defaults to "Administrator").

### Request Example
{
  "username": "admin",
  "password": "a-good-secret",
  "email": "admin@example.com",
  "fullname": "Site Admin"
}

### Response
#### Success Response (200)
- **data** (object) - Contains the authentication tokens.
  - **access_token** (string) - The JWT access token.
  - **refresh_token** (string) - The JWT refresh token.
  - **token_type** (string) - The type of token (Bearer).
  - **expires_in** (integer) - Token expiration in seconds.

#### Response Example
{
  "data": {"access_token": "eyJ...", "refresh_token": "eyJ...", "token_type": "Bearer", "expires_in": 3600}
}
```

--------------------------------

### Install SEO Magic Plugin

Source: https://learn.getgrav.org/20/grav-premium/seo-magic

Installs the SEO Magic plugin via the GPM command line interface.

```bash
$ bin/gpm install seo-magic
```

--------------------------------

### Verify PHP Setup

Source: https://learn.getgrav.org/20/webservers-hosting/vps/digitalocean

Create a test PHP file to verify the server configuration.

```bash
echo '<?php phpinfo();' > ~/www/html/info.php
exit
```

--------------------------------

### List Pages Response Example

Source: https://learn.getgrav.org/20/api/endpoints/pages

Example JSON response returned by the GET /pages endpoint, including pagination metadata and page data.

```json
{"data": [{"route": "/blog", "slug": "blog", "title": "Blog", "template": "blog", "published": true}], "meta": {"total": 42, "page": 1, "per_page": 20}}
```

--------------------------------

### GET /gpm/repository/themes

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Lists all themes available in the GPM repository with an installed flag.

```APIDOC
## GET /gpm/repository/themes

### Description
List all themes available in the GPM repository with `installed` flag on each. Supports pagination and `q` text search.

### Method
GET

### Endpoint
/gpm/repository/themes

### Parameters
#### Query Parameters
- **q** (string) - Optional - Search query to filter themes (matches name / slug / description).
- **page** (integer) - Optional - Page number (default 1).
- **per_page** (integer) - Optional - Items per page (default from config; max 2000).

### Response
#### Success Response (200)
- **data** (array) - List of themes
- **meta** (object) - Pagination metadata

#### Response Example
{
  "data": [{"slug": "quark", "name": "Quark", "description": "Modern theme", "installed": true}],
  "meta": {"total": 120, "page": 1, "per_page": 20}
}
```

--------------------------------

### Configure setup.php for Multisite

Source: https://learn.getgrav.org/20/advanced/multisite-setup

Returns an associative array defining the environment name and stream collection. This script executes on every page request, so avoid resource-intensive operations.

```php
return [
  'environment' => '<name>',            // A name for the environment
  'streams' => [
    'schemes' => [
      '<stream_name>' => [              // The name of the stream
        'type' => 'ReadOnlyStream',     // Stream object e.g. 'ReadOnlyStream' or 'Stream'
        'prefixes' => [
          '<prefix>' => [
            '<path1>',
            '<path2>',
            '<etc>'
          ]
        ],
        'paths' => [                    // Paths (optional)
          '<paths1>',
          '<paths2>',
          '<etc>'
        ]
      ]
    ]
  ]
]
```

--------------------------------

### Install Migrate Grav Plugin via CLI

Source: https://learn.getgrav.org/20/migration/assisted-migration

Use the Grav Package Manager to install the migration plugin.

```bash
bin/gpm install migrate-grav
```

--------------------------------

### Install Algolia Pro Plugin

Source: https://learn.getgrav.org/20/grav-premium/algolia-pro

Installs the Algolia Pro plugin using the Grav Package Manager.

```bash
$ bin/gpm install algolia-pro
```

--------------------------------

### Install Flex Objects via CLI

Source: https://learn.getgrav.org/20/advanced/flex/quickstart

Use the Grav Package Manager to install the Flex Objects plugin.

```bash
$ bin/gpm install flex-objects
```

--------------------------------

### Install Editor Pro via GPM

Source: https://learn.getgrav.org/20/grav-premium/editor-pro

Installs the Editor Pro plugin using the Grav command-line interface.

```bash
$ bin/gpm install editor-pro
```

--------------------------------

### List Themes Response

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Example JSON response for the GET /gpm/themes endpoint.

```json
{"data": [{"slug": "quark", "name": "Quark", "version": "2.0.0", "updatable": false, "is_symlink": false, "thumbnail": "/api/v1/thumbnails/quark-thumb.jpg"}]}
```

--------------------------------

### Back Up Live Site

Source: https://learn.getgrav.org/20/migration/manual-migration

Create a backup of the current Grav installation using the CLI.

```bash
cd /path/to/grav-site
bin/grav backup
```

--------------------------------

### List Blueprints Response

Source: https://learn.getgrav.org/20/api/endpoints/flex-objects

Example JSON response for the GET /flex-objects/blueprints endpoint.

```json
{"data": [{"url": "blueprints://flex-objects/contacts.yaml", "legacy_url": null, "type": "contacts", "title": "Contacts", "description": "Address book"}]}
```

--------------------------------

### Install Dependencies and Build CSS

Source: https://learn.getgrav.org/20/grav-premium/helios

Commands for installing NPM dependencies and running development or production build scripts.

```shell
cd user/themes/helios
npm install
```

```shell
npm run dev
```

```shell
npm run prod
```

--------------------------------

### Start Apache Service

Source: https://learn.getgrav.org/20/webservers-hosting/windows-subsystem-for-linux

Initialize the Apache service within the WSL environment.

```bash
sudo service apache2 start
```

--------------------------------

### GET /gpm/themes/{slug}

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Retrieve detailed information for a specific installed theme by its slug.

```APIDOC
## GET /gpm/themes/{slug}

### Description
Get details for a specific installed theme, including screenshot URL, updatable status, and the is_symlink flag.

### Method
GET

### Endpoint
/gpm/themes/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The theme slug.

### Response
#### Success Response (200)
- data (object) - Theme details

#### Response Example
{"data": {"slug": "quark", "name": "Quark", "version": "2.0.0", "updatable": false, "is_symlink": false, "screenshot": "/api/v1/thumbnails/quark-screen.jpg"}}
```

--------------------------------

### GET /gpm/plugins/{slug}

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Retrieve detailed information for a specific installed plugin by its slug.

```APIDOC
## GET /gpm/plugins/{slug}

### Description
Get details for a single installed plugin, including enabled, updatable, installed_version, available_version, and the is_symlink flag.

### Method
GET

### Endpoint
/gpm/plugins/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The plugin slug.

### Response
#### Success Response (200)
- **data** (object) - Plugin details

#### Response Example
{
  "data": {"slug": "simplesearch", "name": "SimpleSearch", "enabled": true, "is_symlink": false, "installed_version": "2.3.0", "available_version": "2.4.0", "updatable": true}
}
```

--------------------------------

### Install Composer locally

Source: https://learn.getgrav.org/20/cli-console/scripted-upgrades

Run these commands within the project directory to install Composer locally as composer.phar.

```bash
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
```

--------------------------------

### Create a Dokku App

Source: https://learn.getgrav.org/20/webservers-hosting/paas/dokku

Initialize a new application container on the Dokku server.

```bash
dokku apps:create my-grav-site
```

--------------------------------

### List Objects Response

Source: https://learn.getgrav.org/20/api/endpoints/flex-objects

Example JSON response for the GET /flex-objects/{type} endpoint.

```json
{"data": [{"key": "ada", "name": "Ada Lovelace", "email": "ada@example.com"}], "meta": {"total": 1, "page": 1, "per_page": 20}}
```

--------------------------------

### Deployment Output Example

Source: https://learn.getgrav.org/20/webservers-hosting/paas/dokku

A sample of the terminal output generated during a successful application deployment.

```text
Counting objects: 231, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (162/162), done.
Writing objects: 100% (231/231), 36.96 KiB | 0 bytes/s, done.
Total 231 (delta 93), reused 147 (delta 53)
-----> Cleaning up...
-----> Building ruby-getting-started from herokuish...
-----> Adding BUILD_ENV to build environment...
-----> Ruby app detected
-----> Compiling Ruby/Rails
-----> Using Ruby version: ruby-2.2.1
-----> Installing dependencies using 1.9.7
       Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment
       Fetching gem metadata from https://rubygems.org/...........
       Fetching version metadata from https://rubygems.org/...
       Fetching dependency metadata from https://rubygems.org/..
       Using rake 10.4.2

...

=====> Application deployed:
       http://ruby-getting-started.dokku.me
```

--------------------------------

### GET /gpm/themes

Source: https://learn.getgrav.org/20/api/endpoints/gpm

List all installed themes with their metadata, including update status and symlink information.

```APIDOC
## GET /gpm/themes

### Description
List all installed themes with thumbnail URLs, update status, and the is_symlink flag.

### Method
GET

### Endpoint
/gpm/themes

### Response
#### Success Response (200)
- data (array) - List of installed themes

#### Response Example
{"data": [{"slug": "quark", "name": "Quark", "version": "2.0.0", "updatable": false, "is_symlink": false, "thumbnail": "/api/v1/thumbnails/quark-thumb.jpg"}]}
```

--------------------------------

### Install License Manager via CLI

Source: https://learn.getgrav.org/20/grav-premium/license-manager

Use the Grav Package Manager to install the required License Manager plugin.

```bash
$ bin/gpm install license-manager
```

--------------------------------

### GET /gpm/plugins

Source: https://learn.getgrav.org/20/api/endpoints/gpm

List all installed plugins with their enablement status, update availability, and symlink status.

```APIDOC
## GET /gpm/plugins

### Description
List all installed plugins with enablement flags, update status, and whether each plugin is installed via a symlink.

### Method
GET

### Endpoint
/gpm/plugins

### Response
#### Success Response (200)
- **data** (array) - List of installed plugins

#### Response Example
{
  "data": [{"slug": "admin2", "name": "Admin2", "version": "3.0.0-beta.1", "enabled": true, "is_symlink": false, "updatable": false}]
}
```

--------------------------------

### Get Scheduler Status

Source: https://learn.getgrav.org/20/api/endpoints/scheduler

Returns the current crontab installation state and health diagnostics for the scheduler.

```json
{"data": {"crontab_status": "installed", "cron_command": "* * * * * cd /path/to/grav && /usr/bin/php bin/grav scheduler", "scheduler_command": "bin/grav scheduler", "whoami": "www-data", "health": {}, "triggers": [], "webhook_installed": false, "webhook_enabled": false}}
```

--------------------------------

### GET /scheduler/status

Source: https://learn.getgrav.org/20/api/endpoints/scheduler

Report the scheduler's crontab installation state, health diagnostics, and configuration details.

```APIDOC
## GET /scheduler/status

### Description
Report the scheduler's crontab installation state, the cron + scheduler commands Grav would expect, the effective user, health diagnostics, and whether the optional scheduler-webhook plugin is installed/enabled.

### Method
GET

### Endpoint
/scheduler/status

### Response
#### Success Response (200)
- **data** (object) - Status information including crontab_status, cron_command, and health diagnostics.

#### Response Example
{
  "data": {"crontab_status": "installed", "cron_command": "* * * * * cd /path/to/grav && /usr/bin/php bin/grav scheduler", "scheduler_command": "bin/grav scheduler", "whoami": "www-data", "health": {}, "triggers": [], "webhook_installed": false, "webhook_enabled": false}
}
```

--------------------------------

### Create New Grav Project

Source: https://learn.getgrav.org/20/advanced/grav-cli

Initialize a new Grav instance and download necessary dependencies at the specified destination.

```bash
bin/grav new-project ~/webroot/portfolio
```

--------------------------------

### Install Sample Data for Contacts Directory

Source: https://learn.getgrav.org/20/advanced/flex/administration/introduction

Copies the provided sample JSON data for the Contacts directory into the user data directory.

```shell
$ cp user/plugins/flex-objects/data/flex-objects/contacts.json user/data/flex-objects/contacts.json
```

--------------------------------

### Get Webhook Response

Source: https://learn.getgrav.org/20/api/endpoints/webhooks

Example response for retrieving a single webhook by its ID, showing the redacted secret field.

```json
{"data": {"id": "wh_abc123", "url": "https://example.com/hook", "events": ["page.updated"], "secret": "grav_a****************_xyz", "enabled": true}}
```

--------------------------------

### List Webhooks Response

Source: https://learn.getgrav.org/20/api/endpoints/webhooks

Example JSON response returned by the GET /webhooks endpoint, showing redacted secrets.

```json
{"data": [{"id": "wh_abc123", "url": "https://example.com/hook", "events": ["page.created", "page.updated"], "secret": "grav_a****************_xyz", "enabled": true}]}
```

--------------------------------

### Compile SCSS with Gulp

Source: https://learn.getgrav.org/20/themes/customization

Commands to install dependencies and start the Gulp watch process for automatic SCSS compilation.

```bash
npm install -g gulp
```

```bash
yarn install
```

```bash
gulp watch
```

--------------------------------

### Initialize Migration via CLI

Source: https://learn.getgrav.org/20/migration/assisted-migration

Start the migration staging process from the command line.

```bash
bin/plugin migrate-grav init
```

--------------------------------

### GET /gpm/repository/plugins

Source: https://learn.getgrav.org/20/api/endpoints/gpm

List all plugins available in the GPM repository, including an installed flag. Supports pagination and text search.

```APIDOC
## GET /gpm/repository/plugins

### Description
List all plugins available in the GPM repository, with an installed flag on each. Supports pagination and text search.

### Method
GET

### Endpoint
/gpm/repository/plugins

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (default 1).
- **per_page** (integer) - Optional - Items per page (default from config; max 2000).
- **q** (string) - Optional - Search filter matched against name / slug / description.

### Response
#### Success Response (200)
- **data** (array) - List of plugins.
- **meta** (object) - Pagination metadata.

#### Response Example
{"data": [{"slug": "simplesearch", "name": "SimpleSearch", "version": "2.4.0", "installed": true, "installed_version": "2.3.0"}], "meta": {"total": 250, "page": 1, "per_page": 50}}
```

--------------------------------

### Browse Repository Themes Response

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Example JSON response for the GET /gpm/repository/themes endpoint, including theme details and pagination metadata.

```json
{"data": [{"slug": "quark", "name": "Quark", "description": "Modern theme", "installed": true}], "meta": {"total": 120, "page": 1, "per_page": 20}}
```

--------------------------------

### Deployer Task Output Example

Source: https://learn.getgrav.org/20/cli-console/scripted-upgrades

Example output showing the result of a package upgrade task executed via Deployer.

```text
Executing task packages

GPM Releases Configuration: Stable

Found 8 packages installed of which 1 need updating

01. Email           [v2.5.2 -> v2.5.3]

GPM Releases Configuration: Stable

Preparing to install Email [v2.5.3]
  |- Downloading package...   100%
  |- Checking destination...  ok
  |- Installing package...    ok
  '- Success!

Clearing cache

Cleared:  /home/username/public_html/deployer/grav/cache/twig/*
Cleared:  /home/username/public_html/deployer/grav/cache/doctrine/*
Cleared:  /home/username/public_html/deployer/grav/cache/compiled/*

Touched: /home/username/public_html/deployer/grav/user/config/system.yaml
```

--------------------------------

### Create Web Directory

Source: https://learn.getgrav.org/20/webservers-hosting/vps/digitalocean

Switch to the grav user and create the directory structure for the website.

```bash
su - grav
mkdir -p ~/www/html
```

--------------------------------

### GET /sidebar/items

Source: https://learn.getgrav.org/20/api/endpoints/sidebar

Retrieves a list of sidebar navigation items registered by installed plugins. This endpoint triggers the onApiSidebarItems event to collect contributions.

```APIDOC
## GET /sidebar/items

### Description
Collect sidebar navigation items registered by plugins. Fires the onApiSidebarItems event and returns all items contributed by installed plugins.

### Method
GET

### Endpoint
/sidebar/items

### Response
#### Success Response (200)
- **data** (array) - A list of sidebar items, each containing an id, plugin, label, icon, route, and priority.

#### Response Example
{
  "data": [{"id": "license-manager", "plugin": "license-manager", "label": "Licenses", "icon": "fa-key", "route": "/plugin/license-manager", "priority": 10}]
}

### Response Codes
- 200 Success
- 401 Unauthorized
```

--------------------------------

### POST /gpm/direct-install

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Install a plugin or theme from a URL or uploaded zip.

```APIDOC
## POST /gpm/direct-install

### Description
Install a plugin or theme from a URL or uploaded zip, bypassing the GPM repository lookup.

### Method
POST

### Endpoint
/gpm/direct-install

### Parameters
#### Request Body
- **url** (string) - Optional - URL of the package zip (mutually exclusive with file)
- **file** (file) - Optional - Uploaded zip file (multipart; mutually exclusive with url)

### Response
#### Success Response (201)
- **data** (object) - Contains success message

#### Response Example
{
  "data": {"message": "Package installed successfully via direct install."}
}
```

--------------------------------

### List User Tabs Response

Source: https://learn.getgrav.org/20/api/endpoints/users

Example JSON response for the GET /users/filters endpoint, showing the structure of available user filter tabs.

```json
{
    "data": {
        "tabs": [
            { "id": "all", "plugin": "api", "label": "All Users" },
            { "id": "active", "plugin": "my-plugin", "label": "Active", "icon": "fa-bolt", "priority": 10 }
        ],
        "defaultFilter": "all",
        "showAll": true
    }
}
```

--------------------------------

### Flex Plugin Configuration Answers

Source: https://learn.getgrav.org/20/plugins/plugin-flex

Example inputs for the interactive plugin creation process.

```text
 Enter Plugin Name:
 > myflexplugin

 Enter Plugin Description:
 > A little Flex plugin test

 Enter Developer Name:
 > grav@example.com

 Enter GitHub ID (can be blank):
 > gravcms

 Enter Developer Email:
 > grav@example.com

 Please choose an option:
  [blank] Basic Plugin
  [flex ] Basic Plugin prepared for custom Flex Objects
 > flex

 Enter Flex Object Name:
 > book

 Please choose a storage type:
  [simple] Basic Storage (1 file for all objects) - no media support
  [file  ] File Storage (1 file per object)
  [folder] Folder Storage (1 folder per object)
 > folder
```

--------------------------------

### Retrieve Menubar Items

Source: https://learn.getgrav.org/20/api/endpoints/admin-integration

Example JSON response for the GET /menubar/items endpoint, showing registered toolbar items with actions and routing intents.

```json
{"data": [{"id": "warm-cache", "plugin": "warm-cache", "label": "Warm Cache", "icon": "fa-tachometer", "action": "warm", "confirm": "Warm the cache?"}, {"id": "new-article", "plugin": "my-plugin", "label": "New Article", "icon": "fa-plus", "route": "/pages/new?parent=/blog&template=item"}]}
```

--------------------------------

### Example Folder Structure

Source: https://learn.getgrav.org/20/content/multi-language

A sample nested folder structure for a multi-language site.

```yaml
 1- 01.animals
 2  - 01.mammals
 3    - 01.bats
 4    - 02.bears
 5    - 03.foxes
 6    - 04.cats
 7  - 02.reptiles
 8  - 03.birds
 9  - 04.insets
10  - 05.aquatic
```

--------------------------------

### Install Helios Theme

Source: https://learn.getgrav.org/20/grav-premium/helios

Installs the Helios theme and prompts for dependency installation.

```bash
$ bin/gpm install helios
```

--------------------------------

### Interactive plugin creation process

Source: https://learn.getgrav.org/20/plugins/plugin-tutorial

The CLI prompts for metadata including name, description, and developer contact information.

```bash
bin/plugin devtools new-plugin
Enter Plugin Name: Randomizer
Enter Plugin Description: Sends the user to a random page
Enter Developer Name: Acme Corp
Enter Developer Email: contact@acme.co

SUCCESS plugin Randomizer -> Created Successfully

Path: /www/user/plugins/randomizer

Make sure to run `composer update` to initialize the autoloader
```

--------------------------------

### Start the PHP Built-in Web Server

Source: https://learn.getgrav.org/20/webservers-hosting/php-built-in-web-server

Execute this command from the Grav root directory to launch the development server on port 8080.

```bash
php -S localhost:8080 system/router.php
PHP 7.3.27 Development Server started at Thu Jun 17 09:24:46 2021
Listening on http://localhost:8080
Document root is /Users/somerandom/Desktop/quick-grav-test
Press Ctrl-C to quit.
```

--------------------------------

### Example Plugin Blueprint

Source: https://learn.getgrav.org/20/forms/blueprints/example-plugin-blueprint

A complete example of a plugin blueprint file including identity, author details, and dependency definitions.

```yaml
 1name: Assets
 2slug: assets
 3type: plugin
 4version: 1.0.4
 5description: "This plugin provides a convenient way to add CSS and JS assets directly from your pages."
 6icon: list-alt
 7author:
 8  name: Team Grav
 9  email: devs@getgrav.org
10  url: https://getgrav.org
11homepage: https://github.com/getgrav/grav-plugin-assets
12demo: https://learn.getgrav.org
13keywords: assets, javascript, css, inline
14bugs: https://github.com/getgrav/grav-plugin-assets/issues
15license: MIT
16
17dependencies:
18  - { name: afterburner2 }
19  - { name: github }
20  - { name: email, version: '~2.0' }
```

--------------------------------

### Install Email Office365 via GPM

Source: https://learn.getgrav.org/20/grav-premium/email-office365

Execute this command in the root of your Grav installation to install the plugin.

```bash
bin/gpm install email-office365
```

--------------------------------

### Initialize Git and Add Remote

Source: https://learn.getgrav.org/20/webservers-hosting/paas

Configures the local Grav directory as a Git repository and links it to the Fortrabbit deployment remote.

```bash
$ cd grav
$ git init .
$ git remote add fortrabbit git@deploy.eu2.frbit.com:your-app.git
```

--------------------------------

### Install Polls via GPM

Source: https://learn.getgrav.org/20/grav-premium/polls

Use the Grav Package Manager command line tool to install the plugin from the root of your Grav installation.

```bash
bin/gpm install polls
```

--------------------------------

### POST /gpm/install

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Install a plugin or theme from the GPM repository.

```APIDOC
## POST /gpm/install

### Description
Install a plugin or theme from the GPM repository.

### Method
POST

### Endpoint
/gpm/install

### Parameters
#### Request Body
- **package** (string) - Required - Package slug to install
- **type** (string) - Required - Package type: plugin or theme
- **license** (string) - Optional - License key for premium packages

### Request Example
{
  "package": "sitemap",
  "type": "plugin"
}

### Response
#### Success Response (201)
- Package installed

#### Error Responses
- 401 Unauthorized
- 422 Validation error (package not found or install failed)
```

--------------------------------

### GET /dashboard/feed

Source: https://learn.getgrav.org/20/api/endpoints/dashboard

Get the latest news feed from getgrav.org.

```APIDOC
## GET /dashboard/feed

### Description
Get the latest news feed from getgrav.org.

### Method
GET

### Endpoint
/dashboard/feed

### Response
#### Success Response (200)
- Returns the latest blog posts from the getgrav.org Atom feed, including the 10 most recent articles.
```

--------------------------------

### Install Required Web Server and PHP Packages

Source: https://learn.getgrav.org/20/webservers-hosting/vps/digitalocean

Install Nginx, PHP 8.3, and necessary extensions required for Grav functionality.

```bash
apt install -y vim zip unzip nginx git \
    php8.3-fpm php8.3-cli php8.3-gd php8.3-curl \
    php8.3-mbstring php8.3-xml php8.3-zip php8.3-intl php8.3-apcu
```

--------------------------------

### GET /dashboard/stats

Source: https://learn.getgrav.org/20/api/endpoints/dashboard

Get a summary of site statistics for the dashboard.

```APIDOC
## GET /dashboard/stats

### Description
Get a summary of site statistics for the dashboard.

### Method
GET

### Endpoint
/dashboard/stats

### Response
#### Success Response (200)
- Returns a snapshot of site statistics including page counts, user counts, plugin counts, active theme, Grav/PHP versions, and last backup date.
```

--------------------------------

### Access plugin help documentation

Source: https://learn.getgrav.org/20/cli-console/grav-cli-plugin

Provides detailed usage instructions for a specific command within a plugin.

```bash
bin/plugin login help new-user
```

--------------------------------

### Retrieve System Information

Source: https://learn.getgrav.org/20/api/endpoints/system

Returns comprehensive environment details including Grav version, PHP configuration, and installed extensions.

```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"}}}}
```

--------------------------------

### GET /blueprints/pages/{template}

Source: https://learn.getgrav.org/20/api/endpoints/system

Get the blueprint schema for a page template.

```APIDOC
## GET /blueprints/pages/{template}

### Description
Get the blueprint schema for a page template.

### Method
GET

### Endpoint
/blueprints/pages/{template}

### Parameters
#### Path Parameters
- **template** (string) - Required - The page template name (e.g. default, blog, post)

### Response
#### Success Response (200)
- Success

#### Error Response (401)
- Unauthorized

#### Error Response (404)
- Template blueprint not found
```

--------------------------------

### GET /translations/{lang}

Source: https://learn.getgrav.org/20/api/endpoints/system

Get translation strings for a specific language.

```APIDOC
## GET /translations/{lang}

### Description
Get translation strings for a language.

### Method
GET

### Endpoint
/translations/{lang}

### Parameters
#### Path Parameters
- **lang** (string) - Required - Language code (e.g. en, fr, de)

### Response
#### Success Response (200)
- Success

#### Error Response (401)
- Unauthorized
```

--------------------------------

### GET /dashboard/notifications

Source: https://learn.getgrav.org/20/api/endpoints/dashboard

Get system notifications grouped by display location.

```APIDOC
## GET /dashboard/notifications

### Description
Get system notifications grouped by display location (top, dashboard, feed), with a last_checked timestamp.

### Method
GET

### Endpoint
/dashboard/notifications

### Parameters
#### Query Parameters
- **location** (string) - Optional - Return only one group: top, dashboard, or feed.
- **force** (boolean) - Optional - Bypass the cached getgrav.org feed and refetch.

### Response
#### Success Response (200)
- Returns system notifications grouped by location, plus a last_checked timestamp.
```

--------------------------------

### Server Environment Variable Configuration

Source: https://learn.getgrav.org/20/advanced/multisite-setup

Examples of setting environment variables across different server environments to support the setup.php configuration.

```apache
 1<VirtualHost 127.0.0.1:80>
 2    ...
 3
 4    SetEnv GRAV_SETUP_PATH         user/setup.php
 5    SetEnv GRAV_ENVIRONMENT        production
 6    SetEnv DYNAMODB_SESSION_KEY    JBGARDQ06UNJV00DL0R9
 7    SetEnv DYNAMODB_SESSION_SECRET CVjwH+QkfnPhKgVvJvrG24s0ABi343cJ7WTPxvb7
 8    SetEnv DYNAMODB_SESSION_REGION us-east-1
 9    SetEnv GOOGLE_MAPS_KEY         XWIozB2R2GmYInTqZ6jnKuUrdELounUb4BIxYmp
10</VirtualHost>
```

```nginx
 1location / {
 2    ...
 3
 4    fastcgi_param GRAV_SETUP_PATH         user/setup.php;
 5    fastcgi_param GRAV_ENVIRONMENT        production;
 6    fastcgi_param DYNAMODB_SESSION_KEY    JBGARDQ06UNJV00DL0R9;
 7    fastcgi_param DYNAMODB_SESSION_SECRET CVjwH+QkfnPhKgVvJvrG24s0ABi343cJ7WTPxvb7;
 8    fastcgi_param DYNAMODB_SESSION_REGION us-east-1;
 9    fastcgi_param GOOGLE_MAPS_KEY         XWIozB2R2GmYInTqZ6jnKuUrdELounUb4BIxYmp;
10}
```

```nginx
 1location / {
 2...
 3
 4    env[GRAV_SETUP_PATH]          = user/setup.php
 5    env[GRAV_ENVIRONMENT]         = production
 6    env[DYNAMODB_SESSION_KEY]     = JBGARDQ06UNJV00DL0R9
 7    env[DYNAMODB_SESSION_SECRET]  = CVjwH+QkfnPhKgVvJvrG24s0ABi343cJ7WTPxvb7
 8    env[GDYNAMODB_SESSION_REGION] = us-east-1
 9    env[GGOOGLE_MAPS_KEY]         = XWIozB2R2GmYInTqZ6jnKuUrdELounUb4BIxYmp
10}
```

```yaml
 1web:
 2  environment:
 3    - GRAV_SETUP_PATH=user/setup.php
 4    - GRAV_ENVIRONMENT=production
 5    - DYNAMODB_SESSION_KEY=JBGARDQ06UNJV00DL0R9
 6    - DYNAMODB_SESSION_SECRET=CVjwH+QkfnPhKgVvJvrG24s0ABi343cJ7WTPxvb7
 7    - DYNAMODB_SESSION_REGION=us-east-1
 8    - GOOGLE_MAPS_KEY=XWIozB2R2GmYInTqZ6jnKuUrdELounUb4BIxYmp
```

```php
 1putenv('GRAV_SETUP_PATH', 'user/setup.php');
 2putenv('GRAV_ENVIRONMENT', 'production');
 3putenv('DYNAMODB_SESSION_KEY', 'JBGARDQ06UNJV00DL0R9');
 4putenv('DYNAMODB_SESSION_SECRET', 'CVjwH+QkfnPhKgVvJvrG24s0ABi343cJ7WTPxvb7');
 5putenv('DYNAMODB_SESSION_REGION', 'us-east-1');
 6putenv('GOOGLE_MAPS_KEY', 'XWIozB2R2GmYInTqZ6jnKuUrdELounUb4BIxYmp');
```
Tokens:
Raw