### Direct Install API Response Example

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_18.direct-install/api-endpoint.md

This is an example of a successful response after a package has been installed via the direct install API.

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

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

### Direct Install API Request Example

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_18.direct-install/api-endpoint.md

Use this JSON body to install a plugin or theme from a URL. Ensure the URL points to a valid zip file.

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

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

### GET /auth/setup

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/00.authentication/_07.setup-status/api-endpoint.md

Checks whether the instance requires first-run setup based on the presence of user accounts.

```APIDOC
## GET /auth/setup

### Description
Check whether the instance requires first-run setup. Returns `setup_required: true` only when `user/accounts/` is empty. Admin2 polls this on load to decide between showing the setup wizard or the login screen. Public (no auth required).

### Method
GET

### Endpoint
/auth/setup

### Response
#### Success Response (200)
- **setup_required** (boolean) - Indicates if the setup wizard is required.

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

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

### GET /licenses/products-status

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/05.developer-guide/doc.md

Retrieves the installation status of licensed products.

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

### Description
Returns the installation status (enabled, disabled, installed, or not installed) for licensed products.

### Method
GET

### Endpoint
/licenses/products-status

### Response
#### Success Response (200)
- **status** (array) - List of products and their current installation state
```

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

### GET /system/info

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/06.system/_01.system-info/api-endpoint.md

Retrieves rich system information about the Grav installation.

```APIDOC
## GET /system/info

### Description
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.

### Method
GET

### Endpoint
/system/info

### Parameters

### Request Example

### Response
#### Success Response (200)
- **data** (object) - Contains system information.
  - **grav_version** (string) - The version of Grav.
  - **php_version** (string) - The version of PHP.
  - **php_extensions** (array) - A list of loaded PHP extensions.
  - **server_software** (string) - The web server software.
  - **environment** (string) - The current environment (e.g., localhost).
  - **plugins** (array) - A list of installed plugins.
  - **themes** (array) - A list of installed themes.
  - **php_config** (object) - A structured summary of PHP configuration settings.
    - **Upload & POST** (object) - Settings related to file uploads and POST data.
      - **file_uploads** (string) - Whether file uploads are enabled.
      - **upload_max_filesize** (string) - The maximum upload file size.

#### Response Example
```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"
      }
    }
  }
}
```

#### Error Response (401)
Unauthorized.

#### Error Response (403)
Missing `api.system.read` permission.
```

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

### System Info API Request Example

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/06.system/_01.system-info/api-endpoint.md

This is an example of a GET request to the system info endpoint.

```http
GET /system/info
```

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

### Start the Grav Development Server

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/01.basics/03.installation/doc.md

Execute this command from the root directory of your Grav installation to launch the built-in server.

```bash
bin/grav server
```

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

### Install Grav from GitHub

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/01.basics/03.installation/doc.md

Commands to clone the repository, install vendor dependencies, and set up plugins and themes.

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

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

### Install Grav from GitHub

Source: https://context7.com/getgrav/grav-learn/llms.txt

Clone the repository and install dependencies manually.

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

# Install vendor dependencies
composer install --no-dev -o

# Install plugin and theme dependencies
bin/grav install
```

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

### Grav Installer: InstallException Class

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

Provides details on the Grav Installer's InstallException class, which extends RuntimeException.

```APIDOC
## Class: \Grav\Installer\InstallException

### Description
Class InstallException

### Methods
#### public __construct(string $message, Throwable $previous)
##### Description
InstallException constructor.
##### Parameters
- **message** (string) - Required - The error message.
- **previous** (Throwable) - Required - The previous exception.
##### Return
void
```

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

### Grav Server Output Example

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/01.basics/03.installation/doc.md

Example of the terminal output generated when the Grav server is successfully initialized.

```bash
➜ 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
```

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

### Install Packages via GPM API

Source: https://context7.com/getgrav/grav-learn/llms.txt

Install plugins or themes from the GPM repository.

```bash
# Install a plugin
curl -X POST https://yoursite.com/api/v1/gpm/install \
  -H "X-API-Key: grav_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"package": "sitemap", "type": "plugin"}'

# Install a theme
curl -X POST https://yoursite.com/api/v1/gpm/install \
  -H "X-API-Key: grav_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"package": "quark", "type": "theme"}'

# Install premium package with license
curl -X POST https://yoursite.com/api/v1/gpm/install \
  -H "X-API-Key: grav_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"package": "premium-plugin", "type": "plugin", "license": "LICENSE-KEY"}'
```

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

### Package Installation and Checking

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

Functions for checking and installing packages.

```APIDOC
## checkPackagesCanBeInstalled

### Description
Check the passed packages list can be updated.

### Method
Not specified (likely internal or part of a class method)

### Endpoint
Not applicable (function within a class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **void** - No return value.

#### Response Example
None
```

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

### Install Grav API Plugin

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/01.getting-started/doc.md

Use GPM to install the API plugin into your Grav instance.

```bash
bin/grav install api
```

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

### POST /api/v1/gpm/install

Source: https://context7.com/getgrav/grav-learn/llms.txt

Install plugins or themes from the GPM repository.

```APIDOC
## POST /api/v1/gpm/install

### Description
Install plugins or themes from the GPM repository.

### Method
POST

### Endpoint
/api/v1/gpm/install

### Request Body
- **package** (string) - Required - The name of the package.
- **type** (string) - Required - The type of package (plugin or theme).
- **license** (string) - Optional - License key for premium packages.
```

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

### Install Grav with Composer

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/01.basics/03.installation/doc.md

Use Composer to create a new Grav project or install the development version.

```bash
composer create-project getgrav/grav ~/webroot/grav
```

```bash
composer create-project getgrav/grav ~/webroot/grav 1.x-dev
```

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

### POST /gpm/install

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_03.install-package/api-endpoint.md

Installs 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
```json
{
  "package": "sitemap",
  "type": "plugin"
}
```

### Response
#### Success Response (201)
- **message** (string) - Package installed

#### Error Response (401)
- **error** (string) - Unauthorized

#### Error Response (422)
- **error** (string) - Validation error (package not found or install failed)
```

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

### Install Grav dependencies

Source: https://github.com/getgrav/grav-learn/blob/develop/README.md

Execute this command from the Grav root directory to install required plugins and vendor libraries.

```bash
bin/grav install
```

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

### Grav GPM Installer Methods

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

A collection of static methods for managing Grav package installations and file operations.

```APIDOC
## copyInstall

### Description
Copies an installation from a source path to a destination path.

### Parameters
- **$source_path** (string) - Required - The source directory path.
- **$install_path** (string) - Required - The destination directory path.

### Response
- **bool** - Returns true on success, false otherwise.

## install

### Description
Installs a given package to a given destination.

### Parameters
- **$zip** (string) - Required - Path to the zip file.
- **$destination** (string) - Required - Destination path.
- **$options** (array) - Optional - Installation options.
- **$extracted** (string/null) - Optional - Path to extracted files.
- **$keepExtracted** (bool) - Optional - Whether to keep extracted files.

### Response
- **bool** - True if everything went fine, False otherwise.

## uninstall

### Description
Uninstalls one or more given packages.

### Parameters
- **$path** (string) - Required - Path to the package.
- **$options** (array) - Optional - Uninstallation options.

### Response
- **bool** - True if everything went fine, False otherwise.

## unZip

### Description
Unzip a file to a specified destination.

### Parameters
- **$zip_file** (string) - Required - Path to the zip file.
- **$destination** (string) - Required - Destination path.

### Response
- **string/false** - Returns the path or false on failure.
```

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

### System Info API Response Example

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/06.system/_01.system-info/api-endpoint.md

This is an example of a successful JSON response from the system info endpoint, including Grav and PHP versions, extensions, server software, environment details, and PHP configuration summaries.

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

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

### Grav Installer: VersionUpdate Class

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

Details the methods and constructor for the Grav Installer's VersionUpdate class.

```APIDOC
## Class: \Grav\Installer\VersionUpdate

### Description
Class VersionUpdate

### Methods
#### public __construct(string $file, \Grav\Installer\VersionUpdater $updater)
##### Parameters
- **file** (string) - Required - The file path.
- **updater** (\Grav\Installer\VersionUpdater) - Required - The updater instance.
##### Return
void

#### public getDate()
##### Return
mixed

#### public getPatch()
##### Return
mixed

#### public getRevision()
##### Return
mixed

#### public getUpdater()
##### Return
mixed

#### public getVersion()
##### Return
mixed

#### public postflight(\Grav\Installer\VersionUpdater $updater)
##### Description
Runs right after installation.
##### Parameters
- **updater** (\Grav\Installer\VersionUpdater) - Required - The updater instance.
##### Return
void

#### public preflight(\Grav\Installer\VersionUpdater $updater)
##### Description
Run right before installation.
##### Parameters
- **updater** (\Grav\Installer\VersionUpdater) - Required - The updater instance.
##### Return
void
```

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

### Install Package Request

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_03.install-package/api-endpoint.md

JSON payload required to install a specific plugin or theme package.

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

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

### Create API Key Response Example

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/04.users/_10.create-api-key/api-endpoint.md

This is an example of a successful response when creating an API key. The raw key is only returned once.

```json
{"data": {"id": "abc123", "name": "CI Deploy Key", "api_key": "grav_...", "scopes": [], "created": 1710000000}}
```

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

### List Installed Themes

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_07.list-themes/api-endpoint.md

Use this endpoint to retrieve a list of all themes installed in your Grav instance. It returns details such as version, update availability, and thumbnail links.

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

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

### Class: \Grav\Common\GPM\Local\Plugins

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

Handles the collection of locally installed plugins.

```APIDOC
## Class: \Grav\Common\GPM\Local\Plugins

### Description
Manages the collection of plugins installed locally in the Grav instance.

### Methods
- **__construct()**: Initializes the local plugins collection.
```

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

### Class: \Grav\Common\Config\Setup

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

Methods for system setup, including stream management and resource locator initialization.

```APIDOC
## \Grav\Common\Config\Setup

### Methods
- **__construct($container)**: (void) Initialize the Setup class with a container or array.
- **getStreams()**: (array) Get available streams and their types from the configuration.
- **init()**: (\Grav\Common\Config\$this) Initialize the setup process.
- **initializeLocator($locator)**: (void) Initialize resource locator by using the configuration.
```

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

### GET /gpm/themes

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_07.list-themes/api-endpoint.md

Retrieves a list of all installed themes with their respective details.

```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 themes.

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

### Error Handling
- 401: Unauthorized.
- 403: Missing `api.gpm.read` permission.
```

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

### POST /auth/setup

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/00.authentication/_08.setup-create/api-endpoint.md

Creates the initial super-admin account on a fresh Grav 2.0 install. This endpoint is only active while the user accounts directory is empty.

```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; 409 thereafter. Grants `api.super` by default. Fires `onApiUserCreated` and `onApiSetupComplete`, then issues a login token pair.

### 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) - Account created; token pair issued.

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

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

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

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_08.get-theme/api-endpoint.md

Retrieves details for a specific installed theme.

```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.

### Request Example

### Response
#### Success Response (200)
- **data** (object) - Contains theme details.
  - **slug** (string) - The theme slug.
  - **name** (string) - The theme name.
  - **version** (string) - The theme version.
  - **updatable** (boolean) - Indicates if the theme is updatable.
  - **is_symlink** (boolean) - Indicates if the theme is a symlink.
  - **screenshot** (string) - URL to the theme's screenshot.

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

#### Error Responses
- **401**: Unauthorized.
- **403**: Missing `api.gpm.read` permission.
- **404**: Theme not installed.
```

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

### System Configuration YAML

Source: https://context7.com/getgrav/grav-learn/llms.txt

Example of the system.yaml configuration file for Grav.

```yaml
# user/config/system.yaml
absolute_urls: false
timezone: 'America/New_York'
default_locale: en
force_ssl: true
force_lowercase_urls: true

languages:
  supported: [en, fr, de]
  default_lang: en
  include_default_lang: true
  translations: true
  translations_fallback: true

home:
  alias: '/home'
  hide_in_urls: true

pages:
  theme: quark
  order:
    by: date
    dir: desc
  list:
    count: 20
  process:
    markdown: true
    twig: false
  markdown:
    extra: true
    auto_line_breaks: false
  types: [html, htm, xml, txt, json, rss, atom]

cache:
  enabled: true
  check:
    method: file
  driver: auto
  lifetime: 604800      # 7 days
  gzip: false

twig:
  cache: true
  debug: false
  auto_reload: true
  autoescape: false

debugger:
  enabled: false
  provider: clockwork

session:
  enabled: true
  timeout: 1800
  name: grav-site
  secure: true
  httponly: true
  samesite: Lax
```

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

### GET /gpm/plugins

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_01.list-plugins/api-endpoint.md

Retrieves a list of all installed plugins with their current status and metadata.

```APIDOC
## GET /gpm/plugins

### Description
List all installed plugins with enablement flags, update status, and whether each plugin is installed via a symlink (important for upgrade gating — symlinked packages should not be overwritten).

### Method
GET

### Endpoint
/gpm/plugins

### Response
#### Success Response (200)
- **data** (array) - Plugins returned.

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

#### Error Response (403)
- Missing `api.gpm.read` permission.

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

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

### Run Grav Development Server

Source: https://context7.com/getgrav/grav-learn/llms.txt

Start the built-in PHP server for local development.

```bash
# Start built-in PHP server with Symfony CLI (recommended)
bin/grav server

# Output:
# Grav Web Server
# ===============
# [OK] Web server listening
# The Web server is using PHP FPM 8.0.8
# https://127.0.0.1:8000
```

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

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

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_12.get-readme/api-endpoint.md

Retrieves the README.md content for a specified installed plugin.

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

### Description
Get the README.md content for an installed plugin. This endpoint is also available for themes at `/gpm/themes/{slug}/readme`.

### Method
GET

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

### Parameters
#### Path Parameters
- **slug** (string) - Required - The package slug

### Response
#### Success Response (200)
- **data.content** (string) - The content of the README.md file.

#### Response Example
```json
{
  "data": {
    "content": "# My Plugin\n\nThis plugin does..."
  }
}
```

#### Error Responses
- **401** - Unauthorized
- **404** - Package or README not found
```

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

### POST /gpm/direct-install

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_18.direct-install/api-endpoint.md

Install a plugin or theme from a URL or uploaded zip file. This endpoint is useful for private packages, pre-release builds, or local development.

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

### Description
Install a plugin or theme from a URL or uploaded zip — bypasses the GPM repository lookup. Accepts either a JSON body with `url`, or a multipart upload with a `file` field.

### 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`).

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

### Response
#### Success Response (201)
- **data** (object) - Contains the installation status message.

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

### Error Handling
- **400**: Neither `url` nor a valid `file` was provided.
- **401**: Unauthorized.
- **403**: Missing `api.gpm.write` permission.
- **500**: Installation failed.
```

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

### Configuration and Initialization

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

Methods for initializing and configuring system options.

```APIDOC
## POST /api/initOptions

### Description
Initializes or updates system options with the provided array.

### Method
POST

### Endpoint
/api/initOptions

### Parameters
#### Request Body
- **options** (array) - Required - An array of options to initialize or update.

### Response
#### Success Response (200)
- **void** - This method does not return a value.

## GET /api/isIndexed

### Description
Checks if the system's index is currently active or initialized.

### Method
GET

### Endpoint
/api/isIndexed

### Response
#### Success Response (200)
- **bool** - True if the index is active, false otherwise.

```

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

### Sidebar Items API Response

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/08.sidebar/_01.sidebar-items/api-endpoint.md

Example JSON response structure for the GET /sidebar/items endpoint.

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

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

### Install Grav via ZIP

Source: https://context7.com/getgrav/grav-learn/llms.txt

Download and extract the Grav ZIP archive to your webroot.

```bash
# Download and extract Grav with Admin plugin
wget https://getgrav.org/download/core/grav-admin/latest -O grav-admin.zip
unzip grav-admin.zip -d ~/webroot/
cd ~/webroot/grav-admin

# Verify PHP version (requires 7.3.6+)
php -v
```

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

### GET /gpm/repository/{slug}

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_21.repository-package/api-endpoint.md

Retrieves full repository details for a plugin or theme based on the provided slug, including an installed flag.

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

### Description
Get full repository details for a plugin or theme (whichever matches the slug), plus an `installed` flag.

### Method
GET

### Endpoint
/gpm/repository/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - Package slug.

### Response
#### Success Response (200)
- **data** (object) - Package details including slug, name, version, description, author, and installed status.

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

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

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

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_02.get-plugin/api-endpoint.md

Retrieves detailed information about a specific installed plugin, including versioning, update status, and configuration flags.

```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 returned.

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

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

### Get Specific Theme Details

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_08.get-theme/api-endpoint.md

Retrieve details for a specific installed theme using its slug. Ensure you have the necessary permissions to access the GPM API.

```json
{"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}/changelog

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/05.gpm/_13.get-changelog/api-endpoint.md

Retrieves the CHANGELOG.md content for a specific installed plugin or theme using its slug. This endpoint is also accessible via /gpm/themes/{slug}/changelog.

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

### Description
Get the CHANGELOG.md content for an installed plugin or theme. Also available at /gpm/themes/{slug}/changelog.

### Method
GET

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

### Parameters
#### Path Parameters
- **slug** (string) - Required - The package slug

### Request Example

### Response
#### Success Response (200)
- **data** (object) - Contains the changelog content
  - **content** (string) - The content of the CHANGELOG.md file

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

#### Error Responses
- **401** - Unauthorized
- **404** - Package or changelog not found
```

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

### Get Sidebar Items API

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/08.sidebar/_01.sidebar-items/api-endpoint.md

This endpoint collects sidebar navigation items registered by plugins. It fires the onApiSidebarItems event and returns all items contributed by installed plugins. Each item defines an id, label, icon, route, and optional badge.

```APIDOC
## GET /sidebar/items

### Description
Collect sidebar navigation items registered by plugins. Fires the onApiSidebarItems event and returns all items contributed by installed plugins. Each item defines an id, label, icon, route, and optional badge.

### Method
GET

### Endpoint
/sidebar/items

### Parameters

### Request Example

### Response
#### Success Response (200)
- **data** (array) - An array of sidebar item objects.
  - **id** (string) - The unique identifier for the sidebar item.
  - **plugin** (string) - The name of the plugin contributing the item.
  - **label** (string) - The display label for the item.
  - **icon** (string) - The CSS class for the item's icon.
  - **route** (string) - The route associated with the item.
  - **priority** (integer) - The display priority of the item.
#### Response Example
{
  "data": [
    {
      "id": "license-manager",
      "plugin": "license-manager",
      "label": "Licenses",
      "icon": "fa-key",
      "route": "/plugin/license-manager",
      "priority": 10
    }
  ]
}

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

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

### GET /scheduler/status

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/10.scheduler/_02.scheduler-status/api-endpoint.md

Report the scheduler's crontab installation state, the cron + scheduler commands Grav would expect, the effective user (`whoami`), health diagnostics, and whether the optional scheduler-webhook plugin is installed/enabled. Drives the "is cron set up?" panel on the Admin2 dashboard.

```APIDOC
## GET /scheduler/status

### Description
Report the scheduler's crontab installation state, the cron + scheduler commands Grav would expect, the effective user (`whoami`), health diagnostics, and whether the optional scheduler-webhook plugin is installed/enabled. Drives the "is cron set up?" panel on the Admin2 dashboard.

### Method
GET

### Endpoint
/scheduler/status

### Parameters

### Request Example

### Response
#### Success Response (200)
- **crontab_status** (string) - One of: `not_installed`, `installed`, `error`, `unknown`.
- **cron_command** (string) - The cron command Grav expects.
- **scheduler_command** (string) - The scheduler command Grav expects.
- **whoami** (string) - The effective user running the command.
- **health** (object) - Health diagnostics.
- **triggers** (array) - List of triggers.
- **webhook_installed** (boolean) - Whether the webhook plugin is installed.
- **webhook_enabled** (boolean) - Whether the webhook plugin is enabled.

#### Response Example
```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
  }
}
```

#### Error Responses
- **401**: Unauthorized.
- **403**: Missing `api.scheduler.read` permission.
```

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

### Define Basic System Configuration Options

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/01.basics/05.grav-configuration/doc.md

General settings for site operation, timezone, and URL handling defined in system.yaml.

```yaml
absolute_urls: false
timezone: ''
default_locale:
param_sep: ':'
wrapped_site: false
reverse_proxy_setup: false
force_ssl: false
force_lowercase_urls: true
custom_base_url: ''
username_regex: '^[a-z0-9_-]{3,16}$'
pwd_regex: '(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{8,}'
intl_enabled: true
http_x_forwarded:
  protocol: true
  host: false
  port: true
  ip: true
```

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

### GET /dashboard/stats

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/14.api/03.endpoints/09.dashboard/_01.dashboard-stats/api-endpoint.md

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

### Parameters

### Request Body

### Request Example

### Response
#### Success Response (200)
- **page_counts** (integer) - The total number of pages on the site.
- **user_counts** (integer) - The total number of users.
- **plugin_counts** (integer) - The total number of installed plugins.
- **active_theme** (string) - The name of the currently active theme.
- **grav_version** (string) - The version of Grav installed.
- **php_version** (string) - The version of PHP being used.
- **last_backup_date** (string) - The date and time of the last backup.

#### Response Example
{
  "page_counts": 150,
  "user_counts": 10,
  "plugin_counts": 25,
  "active_theme": "Quark",
  "grav_version": "1.7.40",
  "php_version": "7.4.33",
  "last_backup_date": "2023-10-27T10:00:00Z"
}

#### Error Response (401)
- **error** (string) - Indicates that the request is unauthorized.
```

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

### Get System Information via API

Source: https://context7.com/getgrav/grav-learn/llms.txt

Retrieve detailed server and environment information.

```bash
# Get system info
curl -H "X-API-Key: grav_abc123..." \
  "https://yoursite.com/api/v1/system/info"

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

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

### Pages::referrerRoute() Example

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

Examples demonstrating the usage of the referrerRoute method.

```APIDOC
## Examples of Pages::referrerRoute()

### Example 1
```php
$langCode = null;
$referrer = $pages->referrerRoute($langCode, '/admin');
// returns relative referrer url within /admin and updates $langCode
```

### Example 2
```php
$langCode = 'en';
$referrer = $pages->referrerRoute($langCode, '/admin');
// returns relative referrer url within the /en/admin
```
```

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

### Grav\Installer\Versions Methods

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

Methods for interacting with the Grav versioning system.

```APIDOC
## GET /versions/all

### Description
Retrieves all version information.

### Method
GET

### Response
- **return** (array) - All version data.

## GET /versions/extension/{extension}

### Description
Retrieves information for a specific extension.

### Method
GET

### Parameters
#### Path Parameters
- **extension** (string) - Required - The name of the extension.

### Response
- **return** (array/null) - Extension data or null if not found.

## GET /versions/plugins

### Description
Retrieves a list of all plugins.

### Method
GET

### Response
- **return** (array) - List of plugins.

## GET /versions/themes

### Description
Retrieves a list of all themes.

### Method
GET

### Response
- **return** (array) - List of themes.

## POST /versions/save

### Description
Saves the current version state to the file.

### Method
POST

### Response
- **return** (bool) - True if the file was updated.
```

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

### GPM InstallCommand

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

Documentation for the GPM InstallCommand class used for package installation.

```APIDOC
## \Grav\Console\Gpm\InstallCommand

### Description
Class responsible for installing packages via the Grav Package Manager.

### Methods
- **askConfirmationIfMajorVersionUpdated(\Grav\Common\GPM\Remote\Package $package)**: void - If the package is updated from an older major release, show warning and ask confirmation.
- **installDependencies(array $dependencies, string $type, string $message, bool $required=true)**: void - Given a $dependencies list, filters their type according to $type and shows $message prior to listing them to the user. Then asks the user a confirmation prior to installing them.
```

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

### TwigTokenParserTryCatch Get Tag Method

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

Gets the tag name associated with this token parser, which is 'trycatch'.

```php
getTag()

```

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

### Markdown Basic Content Example

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/20/01.basics/04.basic-tutorial/doc.md

Example of standard Markdown text including bold formatting.

```markdown
Congratulations! You have installed the **Base Grav Package** that provides a **simple page** and the default **Quark** theme to get you started.
```

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

### Configure Grav REST API

Source: https://context7.com/getgrav/grav-learn/llms.txt

Install the API plugin and configure its settings via YAML.

```bash
# Install API plugin via GPM
bin/grav install api
```

```yaml
# user/config/plugins/api.yaml
enabled: true
route: /api                    # Base route for all API endpoints
version_prefix: v1             # Version prefix

auth:
  api_keys_enabled: true       # Enable API key authentication
  jwt_enabled: true            # Enable JWT token authentication
  session_enabled: true        # Enable session passthrough

cors:
  enabled: true                # Enable CORS headers
  origin: '*'                  # Allowed origins
  credentials: false           # Allow credentials

rate_limit:
  enabled: true                # Enable rate limiting
  requests_per_minute: 120     # Requests per minute per user/IP

pagination:
  default_per_page: 20         # Default items per page
  max_per_page: 100            # Maximum items per page
```

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

### Grav Installer YamlUpdater API

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

API endpoints for managing YAML configurations within the Grav Installer.

```APIDOC
## POST /api/yamlupdater/define

### Description
Defines a variable within the YAML configuration.

### Method
POST

### Endpoint
/api/yamlupdater/define

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **variable** (string) - Required - The name of the variable to define.
- **value** (mixed) - Required - The value to assign to the variable.

### Request Example
```json
{
  "variable": "site.title",
  "value": "My Grav Site"
}
```

### Response
#### Success Response (200)
- **void** - No content returned on success.

#### Response Example
None
```

```APIDOC
## GET /api/yamlupdater/exists

### Description
Checks if a variable exists in the YAML configuration using dot notation for nested arrays/objects.

### Method
GET

### Endpoint
/api/yamlupdater/exists

### Parameters
#### Path Parameters
None

#### Query Parameters
- **variable** (string) - Required - The dot-notation path to the variable.

### Response
#### Success Response (200)
- **void** - No content returned on success, but the existence is implied by the lack of an error.

#### Response Example
None
```

```APIDOC
## GET /api/yamlupdater/get

### Description
Retrieves a value from the YAML configuration using dot notation for nested arrays/objects.

### Method
GET

### Endpoint
/api/yamlupdater/get

### Parameters
#### Path Parameters
None

#### Query Parameters
- **name** (string) - Required - The dot-notation path to the variable.
- **default** (mixed) - Optional - The default value to return if the variable is not found.

### Response
#### Success Response (200)
- **mixed** - The value of the variable or the default value.

#### Response Example
```json
"My Grav Site"
```
```

```APIDOC
## GET /api/yamlupdater/getComments

### Description
Retrieves comments from the YAML configuration.

### Method
GET

### Endpoint
/api/yamlupdater/getComments

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Response
#### Success Response (200)
- **array** - An array of comments.

#### Response Example
```json
[
  "# This is a comment.",
  "# Another comment."
]
```
```

```APIDOC
## POST /api/yamlupdater/instance

### Description
Creates or retrieves an instance of the YamlUpdater for a specific file.

### Method
POST

### Endpoint
/api/yamlupdater/instance

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **filename** (string) - Required - The path to the YAML file.

### Request Example
```json
{
  "filename": "user/config/site.yaml"
}
```

### Response
#### Success Response (200)
- **void** - No content returned on success.

#### Response Example
None
```

```APIDOC
## GET /api/yamlupdater/isHandWritten

### Description
Checks if the YAML file was manually written or generated.

### Method
GET

### Endpoint
/api/yamlupdater/isHandWritten

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Response
#### Success Response (200)
- **bool** - True if the file is handwritten, false otherwise.

#### Response Example
```json
true
```
```

```APIDOC
## POST /api/yamlupdater/save

### Description
Saves the current YAML configuration.

### Method
POST

### Endpoint
/api/yamlupdater/save

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **bool** - True if the save was successful, false otherwise.

#### Response Example
```json
true
```
```

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

### Media Class Constructor

Source: https://github.com/getgrav/grav-learn/blob/develop/pages/api/default.md

Initialization of the Grav Media class.

```APIDOC
## __construct($path, $media_order, $load)

### Description
Initializes a new Media instance.

### Parameters
- **$path** (string) - Required - The file system path.
- **$media_order** (array/null) - Optional - The order of media items.
- **$load** (bool) - Optional - Whether to load media immediately.
```