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

​
List Categories

Retrieves a paginated list of categories. 
curl -X GET "http://localhost:8091/apis/api.content.halo.run/v1alpha1/categories?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 CategoryVoList object containing paginated category results.
​
items
array
Array of category objects.
​
metadata
Metadata
required
Category metadata including name, labels, and timestamps.
​
spec
CategorySpec
Category specification.
​
displayName
string
required
Display name of the category.
​
slug
string
required
Category slug for URL.
​
description
string
Category description.
​
cover
string
Cover image URL.
​
priority
integer
default:"0"
Category priority for ordering.
​
children
array
Array of child category names.
​
hideFromList
boolean
Whether to hide the category from the category list. When set to true, the category including its subcategories and related posts will not be displayed in the category list, but can still be accessed by permalink.
​
status
CategoryStatus
Category status information.
​
permalink
string
Permanent link to the category.
​
postCount
integer
Total number of posts including all nested levels.
​
visiblePostCount
integer
Number of published and public posts including all nested levels.
​
postCount
integer
Number of posts in this category.
​
page
integer
Current page number, starts from 1.
​
size
integer
Size of each page.
​
total
integer
Total number of categories.
​
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 Category by Name

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

​
Path Parameters

​
name
string
required
Category name (unique identifier).

​
Response

Returns a CategoryVo object.
​
metadata
Metadata
required
Category metadata.
​
spec
CategorySpec
Category specification.
​
status
CategoryStatus
Category status.
​
postCount
integer
Number of posts in this category.

​
List Posts by Category

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

​
Path Parameters

​
name
string
required
Category 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 ListedPostVoList object containing posts in the specified category.

Build docs developers (and LLMs) love

Get started for freeTalk to us