Categories API

The Categories API provides endpoints for managing categories in Joomla.

Base URL

/api/index.php/v1/content/categories

Endpoints Overview

Method	Endpoint	Description
GET	/content/categories	Retrieve all categories
GET	/content/categories/{id}	Retrieve specific category
POST	/content/categories	Create new category
PATCH	/content/categories/{id}	Update category
DELETE	/content/categories/{id}	Delete category

Retrieve all categories

GET /api/index.php/v1/content/categories

Response

{
    "data": [
        {
            "type": "categories",
            "id": "2",
            "attributes": {
                "title": "News",
                "alias": "news",
                "description": "News articles",
                "published": 1,
                "parent_id": 1,
                "level": 1,
                "path": "news",
                "language": "*"
            }
        }
    ]
}

Retrieve specific category

GET /api/index.php/v1/content/categories/{id}

Parameters

Parameter	Type	Description
id	integer	Category ID

Example

curl -X GET "https://yoursite.com/api/index.php/v1/content/categories/2" \
  -H "X-Joomla-Token: YOUR_API_TOKEN"

Create category

POST /api/index.php/v1/content/categories

Request Body

{
    "title": "New Category",
    "alias": "new-category",
    "description": "Description of the category",
    "parent_id": 1,
    "published": 1,
    "access": 1,
    "language": "*"
}

Required fields

Field	Type	Description
title	string	Category title

Optional fields

Field	Type	Default	Description
alias	string	auto	URL-friendly name
description	string	""	Description
parent_id	int	1	Parent category ID
published	int	1	Publication status
access	int	1	Access level
language	string	"*"	Language code or *
extension	string	"com_content"	Component extension

Example

curl -X POST "https://yoursite.com/api/index.php/v1/content/categories" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Category",
    "alias": "new-category",
    "parent_id": 1,
    "published": 1
  }'

Update category

PATCH /api/index.php/v1/content/categories/{id}

Request Body

{
    "title": "Updated Category",
    "description": "New description"
}

Example

curl -X PATCH "https://yoursite.com/api/index.php/v1/content/categories/2" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Category"
  }'

Delete category

DELETE /api/index.php/v1/content/categories/{id}

Example

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

Note

A category can only be deleted if no articles are linked to it.

Category States

Value	Status
-2	Trash
0	Unpublished
1	Published
2	Archived

Hierarchy

Categories support a hierarchical structure. Use parent_id to create subcategories.

Example: Create subcategory

curl -X POST "https://yoursite.com/api/index.php/v1/content/categories" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Subcategory",
    "parent_id": 2
  }'

Filtering

By parent category

GET /api/index.php/v1/content/categories?filter[parent_id]=2

By publication status

GET /api/index.php/v1/content/categories?filter[published]=1

Search

GET /api/index.php/v1/content/categories?filter[search]=news

Related Endpoints

• Articles API - Articles within categories