Skip to main content
The Comments API provides endpoints to list, create, and manage comments and replies on posts and pages.

​
List Comments

Retrieves a paginated list of comments for a specific subject (post, page, etc.). 
curl -X GET "http://localhost:8091/apis/api.halo.run/v1alpha1/comments?kind=Post&version=v1alpha1&name=post-name&page=0&size=10" \
  -H "Accept: application/json"

​
Query Parameters

​
kind
string
required
The comment subject kind (e.g., Post, SinglePage).
​
version
string
required
The comment subject version (e.g., v1alpha1).
​
name
string
required
The comment subject name.
​
group
string
The comment subject group.
​
page
integer
default:"0"
Page number. Default is 0.
​
size
integer
default:"0"
Size number. Default is 0.
​
sort
array
Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.
​
withReplies
boolean
default:"false"
Whether to include replies. Default is false.
​
replySize
integer
default:"10"
Reply size of the comment. Only works when withReplies is true.

​
Response

Returns a CommentWithReplyVoList object containing paginated comment results.
​
items
array
Array of comment objects with replies.
​
metadata
Metadata
required
Comment metadata including name, labels, and timestamps.
​
spec
CommentSpec
required
Comment specification.
​
raw
string
required
Raw comment content.
​
content
string
required
Rendered comment content.
​
owner
CommentOwner
required
Comment owner information.
​
approved
boolean
default:"false"
Whether the comment is approved.
​
hidden
boolean
default:"false"
Whether the comment is hidden.
​
allowNotification
boolean
default:"true"
Whether notifications are allowed.
​
owner
OwnerInfo
required
Comment owner details.
​
kind
string
Owner kind (e.g., User, Email).
​
name
string
Owner name.
​
displayName
string
Owner display name.
​
avatar
string
Owner avatar URL.
​
email
string
Owner email address.
​
stats
CommentStatsVo
required
Comment statistics.
​
upvote
integer
Number of upvotes.
​
status
CommentStatus
Comment status information.
​
replyCount
integer
Total number of replies.
​
visibleReplyCount
integer
Number of visible replies.
​
replies
ListResultReplyVo
Paginated list of replies (when withReplies is true).
​
page
integer
Current page number, starts from 1.
​
size
integer
Size of each page.
​
total
integer
Total number of comments.
​
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.

​
Create Comment

Creates a new comment on a post or page. 
curl -X POST "http://localhost:8091/apis/api.halo.run/v1alpha1/comments" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "subjectRef": {
      "group": "content.halo.run",
      "version": "v1alpha1",
      "kind": "Post",
      "name": "post-name"
    },
    "raw": "This is a comment",
    "content": "<p>This is a comment</p>",
    "allowNotification": true
  }'

​
Request Body

​
subjectRef
Ref
required
Reference to the subject (post, page, etc.) being commented on.
​
group
string
required
Extension group (e.g., content.halo.run).
​
version
string
Extension version.
​
kind
string
required
Extension kind (e.g., Post, SinglePage).
​
name
string
required
Extension name.
​
raw
string
required
Raw comment content (markdown/plain text).
​
content
string
required
Rendered comment content (HTML).
​
allowNotification
boolean
default:"false"
Whether to allow notifications for this comment.
​
hidden
boolean
default:"false"
Whether the comment should be hidden.
​
owner
CommentEmailOwner
Comment owner information (for non-logged-in users).
​
displayName
string
Display name.
​
email
string
Email address.
​
website
string
Website URL.
​
avatar
string
Avatar URL.

​
Response

Returns a Comment object representing the created comment.

​
Get Comment

Retrieves a specific comment by name. 
curl -X GET "http://localhost:8091/apis/api.halo.run/v1alpha1/comments/{name}" \
  -H "Accept: application/json"

​
Path Parameters

​
name
string
required
Comment name (unique identifier).

​
Response

Returns a CommentVoList object.

​
List Comment Replies

Retrieves all replies for a specific comment. 
curl -X GET "http://localhost:8091/apis/api.halo.run/v1alpha1/comments/{name}/reply?page=0&size=10" \
  -H "Accept: application/json"

​
Path Parameters

​
name
string
required
Comment name (unique identifier).

​
Query Parameters

​
page
integer
default:"0"
Page number. Default is 0.
​
size
integer
default:"0"
Size number. Default is 0.

​
Response

Returns a ReplyVoList object containing paginated reply results.
​
items
array
Array of reply objects.
​
metadata
Metadata
required
Reply metadata.
​
spec
ReplySpec
required
Reply specification.
​
owner
OwnerInfo
required
Reply owner information.
​
stats
CommentStatsVo
required
Reply statistics.

​
Create Reply

Creates a new reply to a comment. 
curl -X POST "http://localhost:8091/apis/api.halo.run/v1alpha1/comments/{name}/reply" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "raw": "This is a reply",
    "content": "<p>This is a reply</p>",
    "allowNotification": true
  }'

​
Path Parameters

​
name
string
required
Comment name (unique identifier) to reply to.

​
Request Body

​
raw
string
required
Raw reply content (markdown/plain text).
​
content
string
required
Rendered reply content (HTML).
​
allowNotification
boolean
default:"false"
Whether to allow notifications for this reply.
​
hidden
boolean
default:"false"
Whether the reply should be hidden.
​
quoteReply
string
Name of the reply being quoted.
​
owner
CommentEmailOwner
Reply owner information (for non-logged-in users).

​
Response

Returns a Reply object representing the created reply.

Build docs developers (and LLMs) love

Get started for freeTalk to us