Skip to main content
The Tags API provides endpoints to list, retrieve, and query posts by tag in your Halo CMS.

​
List Tags

Retrieves a paginated list of tags. 
curl -X GET "http://localhost:8091/apis/api.content.halo.run/v1alpha1/tags?page=0&size=10" \
  -H "Accept: application/json"

​
Query Parameters

​
page
integer
default:"0"
Page number. Default is 0.
​
size
integer
default:"0"
Size number. Default is 0.
​
labelSelector
array
Label selector. e.g.: hidden!=true
​
fieldSelector
array
Field selector. e.g.: metadata.name==halo
​
sort
array
Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

​
Response

Returns a TagVoList object containing paginated tag results.
​
items
array
Array of tag objects.
​
metadata
Metadata
required
Tag metadata including name, labels, and timestamps.
​
spec
TagSpec
Tag specification.
​
displayName
string
required
Display name of the tag.
​
slug
string
required
Tag slug for URL.
​
color
string
Tag color in hex format (e.g., #FF5733 or #F57).
​
cover
string
Cover image URL.
​
status
TagStatus
Tag status information.
​
permalink
string
Permanent link to the tag.
​
postCount
integer
Total number of posts with this tag.
​
visiblePostCount
integer
Number of published and public posts with this tag.
​
postCount
integer
Number of posts with this tag.
​
page
integer
Current page number, starts from 1.
​
size
integer
Size of each page.
​
total
integer
Total number of tags.
​
totalPages
integer
Total number of pages.
​
first
boolean
Whether this is the first page.
​
last
boolean
Whether this is the last page.
​
hasNext
boolean
Whether there is a next page.
​
hasPrevious
boolean
Whether there is a previous page.

​
Get Tag by Name

Retrieves a single tag by its name. 
curl -X GET "http://localhost:8091/apis/api.content.halo.run/v1alpha1/tags/{name}" \
  -H "Accept: application/json"

​
Path Parameters

​
name
string
required
Tag name (unique identifier).

​
Response

Returns a TagVo object.
​
metadata
Metadata
required
Tag metadata.
​
spec
TagSpec
Tag specification.
​
status
TagStatus
Tag status.
​
postCount
integer
Number of posts with this tag.

​
List Posts by Tag

Retrieves all posts with a specific tag. 
curl -X GET "http://localhost:8091/apis/api.content.halo.run/v1alpha1/tags/{name}/posts?page=0&size=10" \
  -H "Accept: application/json"

​
Path Parameters

​
name
string
required
Tag name (unique identifier).

​
Query Parameters

​
page
integer
default:"0"
Page number. Default is 0.
​
size
integer
default:"0"
Size number. Default is 0.
​
labelSelector
array
Label selector. e.g.: hidden!=true
​
fieldSelector
array
Field selector. e.g.: metadata.name==halo
​
sort
array
Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

​
Response

Returns a ListedPostVo object containing posts with the specified tag.

Build docs developers (and LLMs) love

Get started for freeTalk to us