Tags API

The Tags API provides endpoints for managing tags in Joomla.

Base URL

/api/index.php/v1/tags

Endpoints Overview

Method	Endpoint	Description
GET	/tags	Retrieve all tags
GET	/tags/{id}	Retrieve specific tag
POST	/tags	Create new tag
PATCH	/tags/{id}	Update tag
DELETE	/tags/{id}	Delete tag

Retrieve all tags

GET /api/index.php/v1/tags

Response

{
    "data": [
        {
            "type": "tags",
            "id": "2",
            "attributes": {
                "title": "Joomla",
                "alias": "joomla",
                "description": "Articles about Joomla",
                "published": 1,
                "parent_id": 1,
                "level": 1,
                "path": "joomla",
                "language": "*"
            }
        }
    ]
}

Retrieve specific tag

GET /api/index.php/v1/tags/{id}

Parameters

Parameter	Type	Description
id	integer	Tag ID

Example

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

Create tag

POST /api/index.php/v1/tags

Request Body

{
    "title": "New Tag",
    "alias": "new-tag",
    "description": "Description of the tag",
    "published": 1,
    "access": 1,
    "language": "*"
}

Required fields

Field	Type	Description
title	string	Tag title

Optional fields

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

Example

curl -X POST "https://yoursite.com/api/index.php/v1/tags" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Tag",
    "description": "Description of the tag"
  }'

Update tag

PATCH /api/index.php/v1/tags/{id}

Request Body

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

Example

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

Delete tag

DELETE /api/index.php/v1/tags/{id}

Example

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

Note

Deleting a tag moves it to the trash.

Tag States

Value	Status
-2	Trash
0	Unpublished
1	Published
2	Archived

Hierarchical Tags

Tags support a hierarchical structure via parent_id.

Example: Create sub-tag

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

Filtering

By publication status

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

Search

GET /api/index.php/v1/tags?filter[search]=joomla

Linking tags to content

Tags are linked to articles via the tags field when creating or updating articles.

Example: Article with tags

curl -X POST "https://yoursite.com/api/index.php/v1/content/articles" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Article with tags",
    "catid": 2,
    "tags": [2, 3, 5]
  }'

Related Endpoints

• Articles API - Articles with tags