✨ Added Admin API endpoint for browsing all comments (#25700)

ref https://linear.app/ghost/issue/FEA-485

Adds GET /api/admin/comments/ endpoint for browsing all comments across
posts, supporting filtering, pagination, and include_nested parameter.

Author: rob-ghost

ghost/core/core/server/api/endpoints/comments.js

@@ -98,6 +98,26 @@ const controller = {
             return result;
         }
     },
+    browseAll: {
+        headers: {
+            cacheInvalidate: false
+        },
+        options: [
+            'page',
+            'limit',
+            'filter',
+            'order',
+            'include_nested'
+        ],
+        validation: {},
+        permissions: {
+            method: 'browse'
+        },
+        async query(frame) {
+            const result = await commentsService.controller.adminBrowseAll(frame);
+            return result;
+        }
+    },
     add: {
         statusCode: 201,
         headers: {

ghost/core/core/server/api/endpoints/utils/serializers/output/mappers/comments.js

@@ -5,6 +5,7 @@ const htmlToPlaintext = require('@tryghost/html-to-plaintext');
 
 const commentFields = [
     'id',
+    'parent_id',
     'in_reply_to_id',
     'in_reply_to_snippet',
     'status',
@@ -47,6 +48,25 @@ const commentMapper = (model, frame) => {
 
     const isPublicRequest = utils.isMembersAPI(frame);
 
+    // Deleted comments are tombstones - just enough info to show "Reply to deleted comment"
+    if (jsonModel.status === 'deleted') {
+        const tombstone = {
+            id: jsonModel.id,
+            parent_id: jsonModel.parent_id || null,
+            status: 'deleted'
+        };
+        // Include post relation if loaded
+        if (jsonModel.post) {
+            url.forPost(jsonModel.post.id, jsonModel.post, frame);
+            tombstone.post = _.pick(jsonModel.post, postFields);
+        }
+        // Include replies if present (for tree structure), recursively mapped
+        if (jsonModel.replies) {
+            tombstone.replies = jsonModel.replies.map(reply => commentMapper(reply, frame));
+        }
+        return tombstone;
+    }
+
     if (jsonModel.inReplyTo && (jsonModel.inReplyTo.status === 'published' || (!isPublicRequest && jsonModel.inReplyTo.status === 'hidden'))) {
         jsonModel.in_reply_to_snippet = htmlToPlaintext.commentSnippet(jsonModel.inReplyTo.html);
     } else if (jsonModel.inReplyTo && jsonModel.inReplyTo.status !== 'published') {

ghost/core/core/server/services/comments/CommentsController.js

@@ -92,6 +92,29 @@ module.exports = class CommentsController {
         return await this.service.getAdminComments(frame.options);
     }
 
+    /**
+     * Browse all comments across the site (admin only, no post_id required)
+     * Used for admin moderation page showing comments from all posts
+     *
+     * Controller responsibility: Parse frame into clean domain parameters.
+     * The frame should not pass beyond this layer.
+     *
+     * @param {Frame} frame
+     */
+    async adminBrowseAll(frame) {
+        // Query params can be strings or booleans depending on how the request is made
+        const includeNestedParam = frame.options.include_nested;
+        const includeNested = includeNestedParam !== 'false' && includeNestedParam !== false;
+
+        return await this.service.getAdminAllComments({
+            includeNested,
+            filter: frame.options.filter,
+            order: frame.options.order || 'created_at desc',
+            page: frame.options.page,
+            limit: frame.options.limit
+        });
+    }
+
     /**
      * @param {Frame} frame
      */

ghost/core/core/server/services/comments/CommentsService.js

@@ -176,6 +176,39 @@ class CommentsService {
         return page;
     }
 
+    /**
+     * @typedef {Object} AdminBrowseAllOptions
+     * @property {boolean} includeNested - If true, include replies in flat list; if false, only top-level comments
+     * @property {string[]} [withRelated] - Relations to include (e.g. ['member', 'post'])
+     * @property {string} [filter] - NQL filter string
+     * @property {string} order - Order string (e.g. 'created_at desc')
+     * @property {number} [page] - Page number
+     * @property {number} [limit] - Results per page
+     */
+
+    /**
+     * Browse all comments across the site for admin moderation.
+     * Does not check if comments are enabled - admins can moderate existing comments.
+     *
+     * Service responsibility: Business logic and data access.
+     * Receives clean, typed parameters - no frame/HTTP knowledge.
+     *
+     * @param {AdminBrowseAllOptions} options
+     */
+    async getAdminAllComments({includeNested, filter, order, page, limit}) {
+        return await this.models.Comment.findPage({
+            withRelated: ['member', 'post'],
+            filter,
+            order,
+            page,
+            limit,
+            // If includeNested is false, only return top-level comments
+            parentId: includeNested ? undefined : null,
+            // Admin context: see hidden comments with full content, and all statuses including deleted
+            isAdmin: true
+        });
+    }
+
     async getAdminComments(options) {
         this.checkEnabled();
         const page = await this.models.Comment.findPage({...options, parentId: null});

ghost/core/core/server/web/api/endpoints/admin/routes.js

@@ -41,6 +41,8 @@ module.exports = function apiRoutes() {
 
     router.get('/mentions', mw.authAdminApi, http(api.mentions.browse));
 
+    // Comments - browseAll must come before :id routes
+    router.get('/comments', mw.authAdminApi, http(api.comments.browseAll));
     router.get('/comments/:id', mw.authAdminApi, http(api.commentReplies.read));
     router.get('/comments/:id/replies', mw.authAdminApi, http(api.commentReplies.browse));
     router.get('/comments/post/:post_id', mw.authAdminApi, http(api.comments.browse));

ghost/core/test/e2e-api/admin/__snapshots__/activity-feed.test.js.snap

@@ -22699,7 +22699,7 @@ exports[`Activity Feed API Can filter events by post id 2: [headers] 1`] = `
 Object {
   "access-control-allow-origin": "http://127.0.0.1:2369",
   "cache-control": "no-cache, private, no-store, must-revalidate, max-stale=0, post-check=0, pre-check=0",
-  "content-length": "18117",
+  "content-length": "18190",
   "content-type": "application/json; charset=utf-8",
   "content-version": StringMatching /v\\\\d\\+\\\\\\.\\\\d\\+/,
   "etag": StringMatching /\\(\\?:W\\\\/\\)\\?"\\(\\?:\\[ !#-\\\\x7E\\\\x80-\\\\xFF\\]\\*\\|\\\\r\\\\n\\[\\\\t \\]\\|\\\\\\\\\\.\\)\\*"/,
@@ -22871,7 +22871,7 @@ exports[`Activity Feed API Filter splitting Can use NQL OR for type only 2: [hea
 Object {
   "access-control-allow-origin": "http://127.0.0.1:2369",
   "cache-control": "no-cache, private, no-store, must-revalidate, max-stale=0, post-check=0, pre-check=0",
-  "content-length": "5279",
+  "content-length": "5352",
   "content-type": "application/json; charset=utf-8",
   "content-version": StringMatching /v\\\\d\\+\\\\\\.\\\\d\\+/,
   "etag": StringMatching /\\(\\?:W\\\\/\\)\\?"\\(\\?:\\[ !#-\\\\x7E\\\\x80-\\\\xFF\\]\\*\\|\\\\r\\\\n\\[\\\\t \\]\\|\\\\\\\\\\.\\)\\*"/,
@@ -23987,7 +23987,7 @@ exports[`Activity Feed API Returns comments in activity feed 2: [headers] 1`] =
 Object {
   "access-control-allow-origin": "http://127.0.0.1:2369",
   "cache-control": "no-cache, private, no-store, must-revalidate, max-stale=0, post-check=0, pre-check=0",
-  "content-length": "1385",
+  "content-length": "1458",
   "content-type": "application/json; charset=utf-8",
   "content-version": StringMatching /v\\\\d\\+\\\\\\.\\\\d\\+/,
   "etag": StringMatching /\\(\\?:W\\\\/\\)\\?"\\(\\?:\\[ !#-\\\\x7E\\\\x80-\\\\xFF\\]\\*\\|\\\\r\\\\n\\[\\\\t \\]\\|\\\\\\\\\\.\\)\\*"/,