Comments API Overview - Blog Marketing Platform

Introduction

The Comments API allows you to manage user comments on blog posts, including creating comments, retrieving comments with nested replies, handling likes, and generating statistics about comment activity.

All comment endpoints support both approved and pending statuses. Comments start in pending status by default and require moderation before becoming visible.

Get All Comments

Retrieve all comments across the platform with optional filters.

Endpoint

GET /api/comments

Query Parameters

withUser

boolean

default:"false"

Include full user information in the response

withReplies

boolean

default:"false"

Include nested replies in the response

page

number

default:"1"

Page number for pagination

limit

number

default:"10"

Number of comments per page

Response

items

array

Array of comment objects

number

Unique comment identifier

contenido

string

Comment content text

post_id

number

ID of the post this comment belongs to

usuario_id

number

ID of the user who created the comment

usuario

object

User information (when withUser=true)

number

User ID

username

string

Username

first_name

string

User’s first name

last_name

string

User’s last name

string

User’s email address

avatar

string

URL to user’s avatar image

status

string

Comment status: pending, approved, spam, or rejected

parent_id

number | null

ID of parent comment (for nested replies)

likes

number

Number of likes the comment has received

is_edited

boolean

Whether the comment has been edited

edited_at

string | null

ISO 8601 timestamp of last edit

depth

number

Nesting depth level (0 for top-level comments)

path

string

Hierarchical path for nested comment tracking

replies

array

Nested array of reply comments (when withReplies=true)

created_at

string

ISO 8601 timestamp of creation

updated_at

string

ISO 8601 timestamp of last update

total

number

Total number of comments

page

number

Current page number

pages

number

Total number of pages

Example Request

const response = await getAllComments();
console.log(`Found ${response.length} comments`);

Get Comments by Post

Retrieve all comments for a specific blog post with pagination and filtering options.

Endpoint

GET /api/comments?post_id={postId}

Function Signature

getCommentsByPostId(
  postId: number,
  options?: {
    withUser?: boolean;
    withReplies?: boolean;
    page?: number;
    limit?: number;
  }
): Promise<{
  comments: Comment[];
  total: number;
  page: number;
  pages: number;
}>

Parameters

postId

number

required

ID of the post to retrieve comments for

withUser

boolean

default:"true"

Include full user information

withReplies

boolean

default:"true"

Include nested replies

page

number

default:"1"

Page number

limit

number

default:"10"

Comments per page

Example Request

const result = await getCommentsByPostId(42, {
  withUser: true,
  withReplies: true,
  page: 1,
  limit: 20
});

console.log(`${result.total} comments on post 42`);
console.log(`Page ${result.page} of ${result.pages}`);

Create Comment

Create a new comment or reply on a blog post.

Endpoint

POST /api/comments

Function Signature

createComment(
  commentData: Partial<Comment>
): Promise<Comment>

Request Body

contenido

string

required

The comment content text

post_id

number

required

ID of the post to comment on

usuario_id

number

required

ID of the user creating the comment

parent_id

number

ID of parent comment (for nested replies). Omit for top-level comments.

New comments are created with pending status by default and require moderation before being visible to users.

Response

Returns the created comment object with all fields populated, including:

Auto-generated id
status set to pending
likes initialized to 0
created_at and updated_at timestamps

Example Request

const newComment = await createComment({
  content: "Great article! Thanks for sharing.",
  postId: 42,
  authorId: 123,
  parentId: null // Top-level comment
});

console.log(`Created comment ${newComment.id}`);

Get Comment Replies

Retrieve all replies to a specific comment.

Endpoint

GET /api/comments/{commentId}/replies

Function Signature

getCommentReplies(
  commentId: number
): Promise<Comment[]>

Parameters

commentId

number

required

ID of the parent comment

Response

Returns an array of comment objects that are direct replies to the specified comment.

The response includes only direct replies (depth + 1). To get the full nested thread, use the withReplies=true parameter on the main comments endpoint.

Example Request

const replies = await getCommentReplies(789);
console.log(`Comment 789 has ${replies.length} replies`);

Like Comment

Add a like to a comment.

Endpoint

POST /api/comments/{commentId}/like

Function Signature

likeComment(
  commentId: number
): Promise<boolean>

Parameters

commentId

number

required

ID of the comment to like

Response

Returns true if the like was successfully added, false otherwise.

Example Request

const success = await likeComment(789);
if (success) {
  console.log('Comment liked successfully');
}

Delete Comment

Permanently delete a comment.

Endpoint

DELETE /api/comments/{commentId}

Function Signature

deleteComment(
  commentId: number
): Promise<boolean>

Parameters

commentId

number

required

ID of the comment to delete

This action is permanent and cannot be undone. Consider updating the status to rejected instead if you want to preserve the comment for moderation records.

Response

Returns true if deletion was successful, false otherwise.

Example Request

const deleted = await deleteComment(789);
if (deleted) {
  console.log('Comment deleted successfully');
}

Comments Statistics

Get comprehensive statistics about comments across the platform.

Endpoint

GET /api/comments/stats/general

Function Signature

getCommentsStats(): Promise<{
  total: number;
  approved: number;
  pending: number;
  spam: number;
}>

Response

total

number

Total number of comments

approved

number

Number of approved comments

pending

number

Number of comments awaiting moderation

spam

number

Number of comments marked as spam

Example Request

const stats = await getCommentsStats();
console.log(`Total: ${stats.total}`);
console.log(`Pending moderation: ${stats.pending}`);

Most Active Commenters

Get a list of users who have posted the most comments.

Endpoint

GET /api/comments/stats/most-active

Function Signature

getMostActiveCommenters(
  limit?: number
): Promise<any[]>

Query Parameters

limit

number

default:"10"

Maximum number of users to return

Response

Returns an array of users ordered by comment count (descending).

Example Request

const activeUsers = await getMostActiveCommenters(10);
activeUsers.forEach(user => {
  console.log(`${user.username}: ${user.comment_count} comments`);
});

Helper Functions

Get Pending Comments

Filter comments by pending status (local/client-side operation).

getPendingComments(): Comment[]

Returns all comments with status === 'pending'.

Get Comments by Post (Local)

Filter comments by post ID (local/client-side operation).

getCommentsByPost(
  postId: string | number
): Comment[]

Returns all comments for the specified post from local store.

Nested Replies Structure

Comments support unlimited nesting depth with the following structure:

The API uses parent_id, depth, and path fields to maintain the comment hierarchy:

parent_id: References the immediate parent comment (null for top-level)
depth: Integer representing nesting level (0 = top-level)
path: Hierarchical string path for efficient tree queries
replies: Array of nested comment objects (when withReplies=true)

Example Nested Structure

{
  "id": 1,
  "contenido": "Top-level comment",
  "parent_id": null,
  "depth": 0,
  "path": "1",
  "replies": [
    {
      "id": 2,
      "contenido": "First reply",
      "parent_id": 1,
      "depth": 1,
      "path": "1.2",
      "replies": [
        {
          "id": 3,
          "contenido": "Nested reply",
          "parent_id": 2,
          "depth": 2,
          "path": "1.2.3",
          "replies": []
        }
      ]
    }
  ]
}

Data Transformation

The API automatically transforms between backend (snake_case) and frontend (camelCase) formats: Backend Format → Frontend Format

contenido → content
post_id → postId
usuario_id → authorId
parent_id → parentId
is_edited → isEdited
edited_at → editedAt
created_at → createdAt
updated_at → updatedAt

All transformations are handled automatically by transformCommentFromBackend() and transformCommentToBackend() functions in commentsService.ts:16-69.

Authentication

Posts

Users

Comments

Categories

RBAC

​Introduction

​Get All Comments

​Endpoint

​Query Parameters

​Response

​Example Request

​Get Comments by Post

​Endpoint

​Function Signature

​Parameters

​Example Request

​Create Comment

​Endpoint

​Function Signature

​Request Body

​Response

​Example Request

​Get Comment Replies

​Endpoint

​Function Signature

​Parameters

​Response

​Example Request

​Like Comment

​Endpoint

​Function Signature

​Parameters

​Response

​Example Request

​Delete Comment

​Endpoint

​Function Signature

​Parameters

​Response

​Example Request

​Comments Statistics

​Endpoint

​Function Signature

​Response

​Example Request

​Top Commented Posts

​Endpoint

​Function Signature

​Query Parameters

​Response

​Example Request

​Most Active Commenters

​Endpoint

​Function Signature

​Query Parameters

​Response

​Example Request

​Helper Functions

​Get Pending Comments

​Get Comments by Post (Local)

​Nested Replies Structure

​Example Nested Structure

​Data Transformation

Build docs developers (and LLMs) love

Introduction

Get All Comments

Endpoint

Query Parameters

Response

Example Request

Get Comments by Post

Endpoint

Function Signature

Parameters

Example Request

Create Comment

Endpoint

Function Signature

Request Body

Response

Example Request

Get Comment Replies

Endpoint

Function Signature

Parameters

Response

Example Request

Like Comment

Endpoint

Function Signature

Parameters

Response

Example Request

Delete Comment

Endpoint

Function Signature

Parameters

Response

Example Request

Comments Statistics

Endpoint

Function Signature

Response

Example Request

Top Commented Posts

Endpoint

Function Signature

Query Parameters

Response

Example Request

Most Active Commenters

Endpoint

Function Signature

Query Parameters

Response

Example Request

Helper Functions

Get Pending Comments

Get Comments by Post (Local)

Nested Replies Structure

Example Nested Structure

Data Transformation