Modules API

The Modules API provides endpoints for managing site modules in Joomla.

Base URL

/api/index.php/v1/modules

Endpoints Overview

Method	Endpoint	Description
GET	/modules/site	Retrieve all modules
GET	/modules/site/{id}	Retrieve specific module
POST	/modules/site	Create new module
PATCH	/modules/site/{id}	Update module
DELETE	/modules/site/{id}	Delete module

Retrieve all modules

GET /api/index.php/v1/modules/site

Response

{
    "data": [
        {
            "type": "modules",
            "id": "1",
            "attributes": {
                "title": "Main Menu",
                "module": "mod_menu",
                "position": "sidebar-left",
                "published": 1,
                "access": 1,
                "showtitle": 1,
                "language": "*",
                "note": ""
            }
        }
    ]
}

Retrieve specific module

GET /api/index.php/v1/modules/site/{id}

Parameters

Parameter	Type	Description
id	integer	Module ID

Example

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

Create module

POST /api/index.php/v1/modules/site

Request Body

{
    "title": "My Custom Module",
    "module": "mod_custom",
    "position": "sidebar-right",
    "published": 1,
    "access": 1,
    "showtitle": 1,
    "language": "*",
    "note": "Custom HTML module",
    "params": {
        "content": "<p>This is custom HTML content</p>"
    }
}

Required fields

Field	Type	Description
title	string	Module title
module	string	Module type
position	string	Template position

Optional fields

Field	Type	Default	Description
published	int	1	Publication status
access	int	1	Access level
showtitle	int	1	Show title (0=no, 1=yes)
language	string	"*"	Language code
note	string	""	Note
ordering	int	0	Order
params	object		Module specific parameters

Example

curl -X POST "https://yoursite.com/api/index.php/v1/modules/site" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Welcome Message",
    "module": "mod_custom",
    "position": "banner",
    "published": 1,
    "showtitle": 0,
    "params": {
      "content": "<h2>Welcome to our site!</h2>"
    }
  }'

Update module

PATCH /api/index.php/v1/modules/site/{id}

Request Body

{
    "title": "Updated Module",
    "position": "footer",
    "published": 0
}

Example

curl -X PATCH "https://yoursite.com/api/index.php/v1/modules/site/1" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Module Title"
  }'

Delete module

DELETE /api/index.php/v1/modules/site/{id}

Example

curl -X DELETE "https://yoursite.com/api/index.php/v1/modules/site/5" \
  -H "X-Joomla-Token: YOUR_API_TOKEN"

Module States

Value	Status
-2	Trash
0	Unpublished
1	Published

Common Module Types

Module	Description
mod_menu	Menu module
mod_custom	Custom HTML
mod_articles_latest	Latest articles
mod_articles_popular	Popular articles
mod_articles_category	Articles from category
mod_breadcrumbs	Breadcrumb trail
mod_login	Login form
mod_search	Search form
mod_tags_popular	Popular tags
mod_footer	Footer information

Template Positions

Template positions vary per template. Common positions:

Position	Description
banner	Banner area
sidebar-left	Left sidebar
sidebar-right	Right sidebar
top-a	Above content
bottom-a	Below content
footer	Footer
debug	Debug position

Filtering

By position

GET /api/index.php/v1/modules/site?filter[position]=sidebar-left

By module type

GET /api/index.php/v1/modules/site?filter[module]=mod_menu

By publication status

GET /api/index.php/v1/modules/site?filter[published]=1

Module Parameters

Each module type has its own parameters. Here is an example for mod_articles_latest:

{
    "title": "Latest News",
    "module": "mod_articles_latest",
    "position": "sidebar-right",
    "params": {
        "catid": ["2"],
        "count": 5,
        "show_author": 0,
        "show_date": 1,
        "show_category": 1
    }
}

Menu Assignment

Modules can be assigned to specific menu items. This is done via the assignment field:

Value	Meaning
0	On all pages
-1	On no pages
1	Only on selected pages

info

Menu assignment via the API is complex. For advanced assignments, prefer using the Joomla administrator interface.