From 41374c33e2e087e1b8369a3eff592c9179503f00 Mon Sep 17 00:00:00 2001
From: "promptless[bot]" <promptless[bot]@users.noreply.github.com>
Date: Sun, 3 May 2026 23:14:06 +0000
Subject: [PATCH 1/5] Add Themes API endpoint documentation (#471)

Migrate Themes REST API documentation from legacy markdown to RST format.
Content verified against Mautic 7.0 source code (ThemeApiController.php
and ThemeHelper.php). Documents all endpoints: get, list, create, delete.
Adds detailed response properties including theme config fields.
---
 docs/rest_api/themes.rst | 280 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 275 insertions(+), 5 deletions(-)

diff --git a/docs/rest_api/themes.rst b/docs/rest_api/themes.rst
index 707ed6da..578966fa 100644
--- a/docs/rest_api/themes.rst
+++ b/docs/rest_api/themes.rst
@@ -1,14 +1,284 @@
 Themes
 ######
 
+Use this endpoint to work with Mautic Themes.
+
+**Using Mautic's API Library**
+
+You can interact with this API through the :xref:`Mautic API Library` as follows, or use the various http endpoints as described in this document.
+
+.. code-block:: php
+
+   <?php
+   use Mautic\MauticApi;
+   use Mautic\Auth\ApiAuth;
+
+   // ...
+   $initAuth  = new ApiAuth();
+   $auth      = $initAuth->newAuth($settings);
+   $apiUrl    = "https://example.com";
+   $api       = new MauticApi();
+   $themesApi = $api->newApi("themes", $auth, $apiUrl);
+
 .. vale off
 
-.. note::
+Get Theme
+*********
+
+.. vale on
+
+Returns the Theme as a zip file with the ``application/zip`` header on success, or a JSON response with error messages on failure. The PHP API library saves the zip file to the system's temporary directory and returns the path.
+
+.. code-block:: php
+
+   <?php
+
+   //...
+   $response = $themesApi->get($themeName);
+
+.. code-block:: json
+
+   {
+       "file": "/absolute/path/to/the/system/temp/dir/with/the/theme/zip/file"
+   }
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /themes/THEME_NAME``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. vale off
+
+Set Temporary File Path
+***********************
+
+.. vale on
+
+Changes the default temporary directory where the PHP API library creates the zip file. Creates the directory if it doesn't exist.
+
+.. code-block:: php
+
+   <?php
+
+   //...
+   $themesApi->setTemporaryFilePath("/absolute/path/to/a/different/temp/dir");
+   $response = $themesApi->get($themeName);
+
+.. code-block:: json
+
+   {
+       "file": "/absolute/path/to/a/different/temp/dir/zipfile"
+   }
+
+.. vale off
+
+List Themes
+***********
+
+.. vale on
+
+Lists all installed Themes with details from their ``config.json`` files.
+
+.. code-block:: php
+
+   <?php
+
+   //...
+   $response = $themesApi->getList();
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /themes``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+   {
+       "themes": {
+           "blank": {
+               "name": "Blank",
+               "key": "blank",
+               "config": {
+                   "name": "Blank",
+                   "author": "Mautic team",
+                   "authorUrl": "https://mautic.org",
+                   "features": [
+                       "page",
+                       "email",
+                       "form"
+                   ]
+               }
+           }
+       }
+   }
+
+**Response Properties**
 
-  The content for this page requires a major update. The legacy page contains outdated and potentially inaccurate information. You can still access it in the :xref:`legacy repository`.
+.. list-table::
+   :header-rows: 1
+   :widths: 20 15 65
 
-  If you're interested in helping develop the new content for this page and others, consider joining the documentation efforts.
+   * - Name
+     - Type
+     - Description
+   * - ``themes``
+     - array
+     - List of installed Themes and their configurations
 
-  Please read the :xref:`dev docs contributing guidelines` and :xref:`Contributing to Mautic’s documentation` to get started.
+**Theme Object Properties**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 15 65
+
+   * - Name
+     - Type
+     - Description
+   * - ``name``
+     - string
+     - Display name of the Theme
+   * - ``key``
+     - string
+     - Directory name and unique identifier of the Theme
+   * - ``config``
+     - object
+     - Theme configuration from ``config.json``
+
+**Config Object Properties**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 15 65
+
+   * - Name
+     - Type
+     - Description
+   * - ``name``
+     - string
+     - Theme name
+   * - ``author``
+     - string
+     - Theme author
+   * - ``authorUrl``
+     - string
+     - Author's website URL
+   * - ``features``
+     - array
+     - List of supported features such as ``page``, ``email``, or ``form``
+   * - ``builder``
+     - array
+     - Optional list of compatible builders such as ``legacy`` or ``grapeJs``
+
+.. vale off
+
+Create Theme
+************
+
+.. vale on
+
+Creates a new Theme or updates an existing one from the provided zip file. The Theme name comes from the zip file name.
+
+.. code-block:: php
+
+   <?php
+
+   //...
+   $data = array(
+       'file' => dirname(__DIR__) . '/' . 'mytheme.zip'
+   );
+
+   $response = $themesApi->create($data);
+
+The file is sent through a standard POST files array, the same way a browser sends files during upload.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /themes/new``
+
+**POST Parameters**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 15 65
+
+   * - Name
+     - Type
+     - Description
+   * - ``file``
+     - file
+     - The zip file containing the Theme (required)
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+   {
+       "success": true
+   }
+
+**Error Responses**
+
+The API returns error messages if:
+
+- No file is uploaded
+- The uploaded file doesn't have a ``.zip`` extension
+- The zip file is missing required files (``config.json``, ``html/message.html.twig``)
+- The zip file contains disallowed file extensions
+
+.. vale off
+
+Delete Theme
+************
+
+.. vale on
+
+Deletes a Theme. You can't delete stock Themes; they become hidden instead.
+
+.. code-block:: php
+
+   <?php
+
+   //...
+   $response = $themesApi->delete($themeName);
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``DELETE /themes/THEME_NAME/delete``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+   {
+       "success": true
+   }
+
+.. note::
 
-.. vale on
\ No newline at end of file
+   Default Themes bundled with Mautic can't be permanently deleted. Attempting to delete a default Theme hides it instead. Use the Theme visibility toggle in the Mautic UI to restore hidden default Themes.

From 749cc085e5a749c16f544f5bfe2c603525cda9f6 Mon Sep 17 00:00:00 2001
From: klkhan <khawarlatifkhan@hotmail.com>
Date: Sun, 3 May 2026 16:30:57 -0700
Subject: [PATCH 2/5] docs: Add Themes API endpoint documentation (#471)

Co-authored-by: promptless[bot] <promptless[bot]@users.noreply.github.com>
---
 docs/rest_api/themes.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/rest_api/themes.rst b/docs/rest_api/themes.rst
index 578966fa..dd7d74a7 100644
--- a/docs/rest_api/themes.rst
+++ b/docs/rest_api/themes.rst
@@ -252,7 +252,7 @@ Delete Theme
 
 .. vale on
 
-Deletes a Theme. You can't delete stock Themes; they become hidden instead.
+Deletes a Theme. You cannot delete stock Themes.
 
 .. code-block:: php
 
@@ -281,4 +281,4 @@ Deletes a Theme. You can't delete stock Themes; they become hidden instead.
 
 .. note::
 
-   Default Themes bundled with Mautic can't be permanently deleted. Attempting to delete a default Theme hides it instead. Use the Theme visibility toggle in the Mautic UI to restore hidden default Themes.
+   Default Themes bundled with Mautic cannot be permanently deleted. Attempting to delete a default Theme hides it instead. Use the Theme visibility toggle in the Mautic UI to restore hidden default Themes.

From 7d2bcc496116927bb74027a34817b18c8d40669e Mon Sep 17 00:00:00 2001
From: "promptless[bot]" <promptless[bot]@users.noreply.github.com>
Date: Wed, 20 May 2026 11:34:03 +0000
Subject: [PATCH 3/5] Apply reviewer feedback on Themes API documentation

Address PR review suggestions from @adiati98:
- Improve intro paragraph and section headers for consistency
- Use "HTTP request" and "Response" as proper RST section headers
- Add "Returns 200 OK" pattern to all Response sections
- Change property headers to proper RST formatting
- Improve wording for theme descriptions and error responses
- Add vale off/on around "Config object properties" header
- Use bullet list format for error conditions
- Update note about default Theme deletion prevention
---
 docs/rest_api/themes.rst | 115 +++++++++++++++++++++------------------
 1 file changed, 63 insertions(+), 52 deletions(-)

diff --git a/docs/rest_api/themes.rst b/docs/rest_api/themes.rst
index dd7d74a7..9dcdc6cc 100644
--- a/docs/rest_api/themes.rst
+++ b/docs/rest_api/themes.rst
@@ -1,11 +1,16 @@
 Themes
 ######
 
-Use this endpoint to work with Mautic Themes.
+Use this endpoint to manipulate and obtain details on Mautic's Themes.
 
-**Using Mautic's API Library**
+Using the Mautic API library
+****************************
 
-You can interact with this API through the :xref:`Mautic API Library` as follows, or use the various http endpoints as described in this document.
+.. vale off
+
+You can interact with this API using the :xref:`Mautic API Library` as below, or the various HTTP endpoints described in this document.
+
+.. vale on
 
 .. code-block:: php
 
@@ -27,7 +32,7 @@ Get Theme
 
 .. vale on
 
-Returns the Theme as a zip file with the ``application/zip`` header on success, or a JSON response with error messages on failure. The PHP API library saves the zip file to the system's temporary directory and returns the path.
+Retrieves the Theme as a zip file with the ``application/zip`` header on success, or a JSON response with error messages on failure. The PHP API library saves the zip file to the system's temporary directory and retrieves the path.
 
 .. code-block:: php
 
@@ -36,27 +41,25 @@ Returns the Theme as a zip file with the ``application/zip`` header on success,
    //...
    $response = $themesApi->get($themeName);
 
-.. code-block:: json
-
-   {
-       "file": "/absolute/path/to/the/system/temp/dir/with/the/theme/zip/file"
-   }
-
-.. vale off
+HTTP request
+============
 
-**HTTP Request**
+``GET /themes/THEME_NAME``
 
-.. vale on
+Response
+========
 
-``GET /themes/THEME_NAME``
+* Returns ``200 OK`` when the request successfully retrieves the Theme zip file.
 
-**Response**
+.. code-block:: json
 
-``Expected Response Code: 200``
+   {
+       "file": "/absolute/path/to/the/system/temp/dir/with/the/theme/zip/file"
+   }
 
 .. vale off
 
-Set Temporary File Path
+Set temporary file path
 ***********************
 
 .. vale on
@@ -71,6 +74,11 @@ Changes the default temporary directory where the PHP API library creates the zi
    $themesApi->setTemporaryFilePath("/absolute/path/to/a/different/temp/dir");
    $response = $themesApi->get($themeName);
 
+Response
+========
+
+* Returns ``200 OK`` when the request successfully changes or creates the default temporary directory.
+
 .. code-block:: json
 
    {
@@ -93,17 +101,15 @@ Lists all installed Themes with details from their ``config.json`` files.
    //...
    $response = $themesApi->getList();
 
-.. vale off
-
-**HTTP Request**
-
-.. vale on
+HTTP request
+============
 
 ``GET /themes``
 
-**Response**
+Response
+========
 
-``Expected Response Code: 200``
+* Returns ``200 OK`` when the request successfully retrieves the Themes list.
 
 .. code-block:: json
 
@@ -126,7 +132,8 @@ Lists all installed Themes with details from their ``config.json`` files.
        }
    }
 
-**Response Properties**
+Properties
+----------
 
 .. list-table::
    :header-rows: 1
@@ -139,7 +146,8 @@ Lists all installed Themes with details from their ``config.json`` files.
      - array
      - List of installed Themes and their configurations
 
-**Theme Object Properties**
+Theme object properties
+-----------------------
 
 .. list-table::
    :header-rows: 1
@@ -158,7 +166,12 @@ Lists all installed Themes with details from their ``config.json`` files.
      - object
      - Theme configuration from ``config.json``
 
-**Config Object Properties**
+.. vale off
+
+Config object properties
+------------------------
+
+.. vale on
 
 .. list-table::
    :header-rows: 1
@@ -190,7 +203,7 @@ Create Theme
 
 .. vale on
 
-Creates a new Theme or updates an existing one from the provided zip file. The Theme name comes from the zip file name.
+Creates a new Theme or updates an existing one from the provided zip file. The Theme name comes from the zip filename.
 
 .. code-block:: php
 
@@ -203,17 +216,15 @@ Creates a new Theme or updates an existing one from the provided zip file. The T
 
    $response = $themesApi->create($data);
 
-The file is sent through a standard POST files array, the same way a browser sends files during upload.
-
-.. vale off
+Mautic sends the file through a standard POST files array, the same way a browser sends files during upload.
 
-**HTTP Request**
-
-.. vale on
+HTTP request
+============
 
 ``POST /themes/new``
 
-**POST Parameters**
+POST parameters
+---------------
 
 .. list-table::
    :header-rows: 1
@@ -224,11 +235,12 @@ The file is sent through a standard POST files array, the same way a browser sen
      - Description
    * - ``file``
      - file
-     - The zip file containing the Theme (required)
+     - The zip file containing the Theme - **required**
 
-**Response**
+Response
+========
 
-``Expected Response Code: 200``
+* Returns ``200 OK`` when the request successfully creates a Theme.
 
 .. code-block:: json
 
@@ -236,14 +248,15 @@ The file is sent through a standard POST files array, the same way a browser sen
        "success": true
    }
 
-**Error Responses**
+Error responses
+---------------
 
 The API returns error messages if:
 
-- No file is uploaded
-- The uploaded file doesn't have a ``.zip`` extension
-- The zip file is missing required files (``config.json``, ``html/message.html.twig``)
-- The zip file contains disallowed file extensions
+* The request includes no uploaded file
+* The uploaded file doesn't have a ``.zip`` extension
+* The zip file is missing required files - ``config.json`` and ``html/message.html.twig``
+* The zip file contains disallowed file extensions
 
 .. vale off
 
@@ -252,7 +265,7 @@ Delete Theme
 
 .. vale on
 
-Deletes a Theme. You cannot delete stock Themes.
+Deletes a Theme. The system prevents deletion of stock Themes.
 
 .. code-block:: php
 
@@ -261,17 +274,15 @@ Deletes a Theme. You cannot delete stock Themes.
    //...
    $response = $themesApi->delete($themeName);
 
-.. vale off
-
-**HTTP Request**
-
-.. vale on
+HTTP request
+============
 
 ``DELETE /themes/THEME_NAME/delete``
 
-**Response**
+Response
+========
 
-``Expected Response Code: 200``
+* Returns ``200 OK`` when the request successfully deletes the Theme.
 
 .. code-block:: json
 
@@ -281,4 +292,4 @@ Deletes a Theme. You cannot delete stock Themes.
 
 .. note::
 
-   Default Themes bundled with Mautic cannot be permanently deleted. Attempting to delete a default Theme hides it instead. Use the Theme visibility toggle in the Mautic UI to restore hidden default Themes.
+   Mautic prevents permanent deletion of default Themes bundled with the application. Attempting to delete a default Theme hides it instead. Use the Theme visibility toggle in the Mautic UI to restore hidden default Themes.

From 0e55d51a38f5cbf0d9ecdfe0185b37a296b9e7a9 Mon Sep 17 00:00:00 2001
From: "promptless[bot]" <promptless[bot]@users.noreply.github.com>
Date: Fri, 22 May 2026 06:30:15 +0000
Subject: [PATCH 4/5] Address PR review feedback for Vale warnings

- Add vale off/on directives around all 4 HTTP request section headers
- Shorten 'application' to 'app' in delete default Themes note
---
 docs/rest_api/themes.rst | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/docs/rest_api/themes.rst b/docs/rest_api/themes.rst
index 9dcdc6cc..9715b75a 100644
--- a/docs/rest_api/themes.rst
+++ b/docs/rest_api/themes.rst
@@ -41,9 +41,13 @@ Retrieves the Theme as a zip file with the ``application/zip`` header on success
    //...
    $response = $themesApi->get($themeName);
 
+.. vale off
+
 HTTP request
 ============
 
+.. vale on
+
 ``GET /themes/THEME_NAME``
 
 Response
@@ -101,9 +105,13 @@ Lists all installed Themes with details from their ``config.json`` files.
    //...
    $response = $themesApi->getList();
 
+.. vale off
+
 HTTP request
 ============
 
+.. vale on
+
 ``GET /themes``
 
 Response
@@ -218,9 +226,13 @@ Creates a new Theme or updates an existing one from the provided zip file. The T
 
 Mautic sends the file through a standard POST files array, the same way a browser sends files during upload.
 
+.. vale off
+
 HTTP request
 ============
 
+.. vale on
+
 ``POST /themes/new``
 
 POST parameters
@@ -274,9 +286,13 @@ Deletes a Theme. The system prevents deletion of stock Themes.
    //...
    $response = $themesApi->delete($themeName);
 
+.. vale off
+
 HTTP request
 ============
 
+.. vale on
+
 ``DELETE /themes/THEME_NAME/delete``
 
 Response
@@ -292,4 +308,4 @@ Response
 
 .. note::
 
-   Mautic prevents permanent deletion of default Themes bundled with the application. Attempting to delete a default Theme hides it instead. Use the Theme visibility toggle in the Mautic UI to restore hidden default Themes.
+   Mautic prevents permanent deletion of default Themes bundled with the app. Attempting to delete a default Theme hides it instead. Use the Theme visibility toggle in the Mautic UI to restore hidden default Themes.

From 35a45d43ea8f784a535aefebcb1d03c705fa7cad Mon Sep 17 00:00:00 2001
From: "promptless[bot]" <promptless[bot]@users.noreply.github.com>
Date: Mon, 1 Jun 2026 08:34:18 +0000
Subject: [PATCH 5/5] Apply reviewer feedback: capitalize ZIP consistently

Address PR review feedback from @adiati98 to use "ZIP file"
consistently throughout the Themes API documentation.
---
 docs/rest_api/themes.rst | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/rest_api/themes.rst b/docs/rest_api/themes.rst
index 9715b75a..af8c41fc 100644
--- a/docs/rest_api/themes.rst
+++ b/docs/rest_api/themes.rst
@@ -32,7 +32,7 @@ Get Theme
 
 .. vale on
 
-Retrieves the Theme as a zip file with the ``application/zip`` header on success, or a JSON response with error messages on failure. The PHP API library saves the zip file to the system's temporary directory and retrieves the path.
+Retrieves the Theme as a ZIP file with the ``application/zip`` header on success, or a JSON response with error messages on failure. The PHP API library saves the ZIP file to the system's temporary directory and retrieves the path.
 
 .. code-block:: php
 
@@ -53,7 +53,7 @@ HTTP request
 Response
 ========
 
-* Returns ``200 OK`` when the request successfully retrieves the Theme zip file.
+* Returns ``200 OK`` when the request successfully retrieves the Theme ZIP file.
 
 .. code-block:: json
 
@@ -68,7 +68,7 @@ Set temporary file path
 
 .. vale on
 
-Changes the default temporary directory where the PHP API library creates the zip file. Creates the directory if it doesn't exist.
+Changes the default temporary directory where the PHP API library creates the ZIP file. Creates the directory if it doesn't exist.
 
 .. code-block:: php
 
@@ -211,7 +211,7 @@ Create Theme
 
 .. vale on
 
-Creates a new Theme or updates an existing one from the provided zip file. The Theme name comes from the zip filename.
+Creates a new Theme or updates an existing one from the provided ZIP file. The Theme name comes from the ZIP filename.
 
 .. code-block:: php
 
@@ -247,7 +247,7 @@ POST parameters
      - Description
    * - ``file``
      - file
-     - The zip file containing the Theme - **required**
+     - The ZIP file containing the Theme - **required**
 
 Response
 ========
@@ -267,8 +267,8 @@ The API returns error messages if:
 
 * The request includes no uploaded file
 * The uploaded file doesn't have a ``.zip`` extension
-* The zip file is missing required files - ``config.json`` and ``html/message.html.twig``
-* The zip file contains disallowed file extensions
+* The ZIP file is missing required files - ``config.json`` and ``html/message.html.twig``
+* The ZIP file contains disallowed file extensions
 
 .. vale off