Templates API

The Templates API provides endpoints for managing template styles in Joomla.

Base URL

/api/index.php/v1/templates

Endpoints Overview

Site Templates

Method	Endpoint	Description
GET	/templates/styles/site	All site template styles
GET	/templates/styles/site/{id}	Retrieve specific style
POST	/templates/styles/site	Create new style
PATCH	/templates/styles/site/{id}	Update style
DELETE	/templates/styles/site/{id}	Delete style

Administrator Templates

Method	Endpoint	Description
GET	/templates/styles/administrator	All admin template styles
GET	/templates/styles/administrator/{id}	Retrieve specific admin style
PATCH	/templates/styles/administrator/{id}	Update admin style

Site Template Styles

Retrieve all site styles

GET /api/index.php/v1/templates/styles/site

Response

{
    "data": [
        {
            "type": "template-styles",
            "id": "10",
            "attributes": {
                "template": "cassiopeia",
                "title": "Cassiopeia - Default",
                "home": "1",
                "params": {
                    "logoFile": "",
                    "fluidContainer": "0",
                    "siteTitle": "",
                    "siteDescription": "",
                    "colorName": "colors_standard",
                    "useFontScheme": "0"
                }
            }
        }
    ]
}

Retrieve specific style

GET /api/index.php/v1/templates/styles/site/{id}

Example

curl -X GET "https://yoursite.com/api/index.php/v1/templates/styles/site/10" \
  -H "X-Joomla-Token: YOUR_API_TOKEN"

Create template style

POST /api/index.php/v1/templates/styles/site

Request Body

{
    "template": "cassiopeia",
    "title": "Cassiopeia - Custom",
    "home": "0",
    "params": {
        "logoFile": "images/logo.png",
        "fluidContainer": "1",
        "colorName": "colors_alternative"
    }
}

Required fields

Field	Type	Description
template	string	Template name (folder name)
title	string	Style title

Optional fields

Field	Type	Default	Description
home	string	"0"	Default template ("1" = yes)
params	object		Template specific parameters

Example

curl -X POST "https://yoursite.com/api/index.php/v1/templates/styles/site" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "cassiopeia",
    "title": "My Custom Style",
    "params": {
      "logoFile": "images/custom-logo.png",
      "fluidContainer": "1"
    }
  }'

Update template style

PATCH /api/index.php/v1/templates/styles/site/{id}

Request Body

{
    "title": "New Title",
    "params": {
        "colorName": "colors_standard"
    }
}

Example

curl -X PATCH "https://yoursite.com/api/index.php/v1/templates/styles/site/10" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cassiopeia - Updated"
  }'

Delete template style

DELETE /api/index.php/v1/templates/styles/site/{id}

Note

You cannot delete the default template style. First set another style as default.

Administrator Template Styles

Retrieve all admin styles

GET /api/index.php/v1/templates/styles/administrator

Update admin style

PATCH /api/index.php/v1/templates/styles/administrator/{id}

Set Default Template

To set a template style as default:

curl -X PATCH "https://yoursite.com/api/index.php/v1/templates/styles/site/10" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "home": "1"
  }'

info

There can only be one default template style. Setting a new default automatically sets the previous one to "0".

Cassiopeia Parameters

The Cassiopeia template (Joomla 4/5 default) has these parameters:

Parameter	Type	Description
logoFile	string	Path to logo image
siteTitle	string	Site title (overrides config)
siteDescription	string	Site description
fluidContainer	string	"0" = fixed, "1" = fluid container
colorName	string	Color scheme name
useFontScheme	string	"0" = default, "1" = custom

Available color schemes

Value	Description
colors_standard	Standard colors
colors_alternative	Alternative set

Template Style per Menu Item

Template styles can be linked to specific menu items. This is done at the menu item, not at the template style.

Example: Menu item with template style

curl -X PATCH "https://yoursite.com/api/index.php/v1/menus/site/items/101" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_style_id": 11
  }'

Filtering

By template

GET /api/index.php/v1/templates/styles/site?filter[template]=cassiopeia

Default styles

GET /api/index.php/v1/templates/styles/site?filter[home]=1

Retrieve Template Positions

To see available template positions, check the template's templateDetails.xml file or use:

# Activate the template preview module position
# Preview URL: yoursite.com/?tp=1

Example: Manage Multiple Styles

<?php
/**
 * Manage template styles via API
 */
class TemplateManager {
    private $baseUrl;
    private $token;

    public function __construct($baseUrl, $token) {
        $this->baseUrl = $baseUrl;
        $this->token = $token;
    }

    public function createStyle($template, $title, $params = []) {
        $url = $this->baseUrl . '/api/index.php/v1/templates/styles/site';

        $data = [
            'template' => $template,
            'title' => $title,
            'params' => $params
        ];

        return $this->request('POST', $url, $data);
    }

    public function setDefault($styleId) {
        $url = $this->baseUrl . "/api/index.php/v1/templates/styles/site/{$styleId}";
        return $this->request('PATCH', $url, ['home' => '1']);
    }

    private function request($method, $url, $data = null) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'X-Joomla-Token: ' . $this->token,
            'Content-Type: application/json'
        ]);
        if ($data) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true);
    }
}
?>