feat: add mark contents as checked APIs

schema/moderation.yaml

@@ -84,3 +84,63 @@ ModerationSetting:
       type: "string"
       description: "The date/time when a rule is updated or deleted."
       format: "date-time"
+
+CheckNotes:
+  type: "array"
+  items:
+    type: "object"
+    properties:
+      noteId:
+        type: "string"
+        description: "Unique identifier for the check note"
+      userId:
+        type: "string"
+        description: "ID of the admin who created the note"
+      action:
+        type: "string"
+        enum:
+          - check
+          - need-follow-up
+          - add-note
+        description: "Action type of the check note"
+      note:
+        type: "string"
+        maxLength: 250
+        description: "Optional note text (max 250 characters)"
+      createdAt:
+        type: "string"
+        format: "date-time"
+        description: "When the check note was created"
+      updatedAt:
+        type: "string"
+        format: "date-time"
+        description: "When the check note was last updated"
+
+CheckStatus:
+  type: "string"
+  enum:
+    - to-check
+    - follow-up-needed
+    - checked
+  description: "Current check status of the content"
+
+CreateCheckNote:
+  type: "object"
+  required:
+    - action
+  properties:
+    action:
+      type: "string"
+      enum:
+        - check
+        - need-follow-up
+        - add-note
+      description: |
+        Action to take on the content:
+        - `check`: Mark content as checked
+        - `need-follow-up`: Mark content as needing follow-up
+        - `add-note`: Add a note without changing status
+    note:
+      type: "string"
+      maxLength: 250
+      description: "Optional note text (max 250 characters)"

swagger.yaml

@@ -78,6 +78,10 @@ paths:
     $ref: "./v3/comment/index.yaml#/_commentId-flags"
   /api/v4/comments/{commentId}:
     $ref: "./v4/comment/index.yaml#/_commentId"
+  /api/v4/comments/{commentId}/checks:
+    $ref: "./v4/comment/index.yaml#/commentId-checks"
+  /api/v4/comments/{commentId}/checks/{noteId}:
+    $ref: "./v4/comment/index.yaml#/commentId-checks-noteId"
   /api/v3/communities:
     $ref: "./v3/community/index.yaml#/root"
   /api/v3/communities/{communityId}:
@@ -390,6 +394,10 @@ paths:
     $ref: "./v4/post/index.yaml#/_postId"
   /api/v5/posts:
     $ref: "./v5/post/index.yaml#/root"
+  /api/v5/posts/{postId}/checks:
+    $ref: "./v5/post/index.yaml#/postId-checks"
+  /api/v5/posts/{postId}/checks/{noteId}:
+    $ref: "./v5/post/index.yaml#/postId-checks-noteId"
   /api/v1/presence/settings:
     $ref: "./v1/presence/index.yaml#/settings"
   /api/v1/presence/settings/user:
@@ -418,6 +426,8 @@ paths:
     $ref: "./v3/role/index.yaml#/_roleId"
   /api/v1/search/posts:
     $ref: "./v1/search/index.yaml#/posts"
+  /api/v1/search/comments:
+    $ref: "./v1/search/index.yaml#/comments"
   /api/v1/semantic-search/posts:
     $ref: "./v1/semantic-search/index.yaml#/posts"
   /api/v1/semantic-search/communities:

v1/search/index.yaml

@@ -17,7 +17,9 @@ posts:
       - $ref: "./parameter.yaml#/dataTypes"
       - $ref: "./parameter.yaml#/tags"
       - $ref: "./parameter.yaml#/hashtags"
+      - $ref: "./parameter.yaml#/checkStatus"
       - $ref: "./parameter.yaml#/matchingOnlyParentPost"
+      - $ref: "./parameter.yaml#/includeModerationDetails"
       - $ref: "./parameter.yaml#/options.limit"
       - $ref: "./parameter.yaml#/options.after"
       - $ref: "./parameter.yaml#/options.before"
@@ -34,3 +36,42 @@ posts:
         $ref: "../../global/error.yaml#/NotFoundError"
       500:
         $ref: "../../global/error.yaml#/UnexpectedError"
+
+comments:
+  get:
+    summary: "Search comments"
+    tags:
+      - "Comment"
+    security:
+      - BearerAuth: []
+    description: |
+      Search and filter comments with advanced criteria. Admin only.
+
+      **Access Control:**
+      - Admin only with ViewPostAndCommentManagement permission
+    parameters:
+      - $ref: "./parameter.yaml#/checkStatus"
+      - $ref: "./parameter.yaml#/targetFeedType"
+      - $ref: "./parameter.yaml#/targetCommunityIds"
+      - $ref: "./parameter.yaml#/targetContentIds"
+      - $ref: "./parameter.yaml#/targetUserIds"
+      - $ref: "./parameter.yaml#/creatorIds"
+      - $ref: "./parameter.yaml#/isDeleted"
+      - $ref: "./parameter.yaml#/referenceType"
+      - $ref: "./parameter.yaml#/sortBy"
+      - $ref: "./parameter.yaml#/includeModerationDetails"
+      - $ref: "./parameter.yaml#/options.limit"
+      - $ref: "./parameter.yaml#/options.after"
+      - $ref: "./parameter.yaml#/options.before"
+      - $ref: "./parameter.yaml#/options.token"
+    responses:
+      200:
+        $ref: "../../v4/comment/response.yaml#/SerializedCommentsWithCheckStatus"
+      400:
+        $ref: "../../global/error.yaml#/BadRequestError"
+      403:
+        $ref: "../../global/error.yaml#/ForbiddenError"
+      429:
+        $ref: "../../global/error.yaml#/RateLimitError"
+      500:
+        $ref: "../../global/error.yaml#/UnexpectedError"

v1/search/parameter.yaml

@@ -161,3 +161,93 @@ hashtags:
       example: "search_query"
     example: ["technology", "AI_trends", "programming", "web_development"]
   description: Filter posts by hashtags. Only letter characters, numbers and underscores are allowed. Case-insensitive matching. Also, tags and hashtags is a different thing. Tags are used to categorize posts, while hashtags are used to tag content with relevant keywords or phrases.
+
+checkStatus: 
+  name: checkStatus
+  in: query
+  schema: 
+    $ref: '../../schema/moderation.yaml#/CheckStatus'
+
+targetFeedType:
+  name: targetFeedType
+  in: query
+  schema:
+    type: string
+    enum:
+      - user
+      - community
+      - content
+  description: Filter by target feed type
+
+targetCommunityIds:
+  name: targetCommunityIds
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+      pattern: '^[0-9a-fA-F]{24}$'
+    maxItems: 10
+  description: Filter by target community IDs (max 10)
+  style: form
+  explode: true
+
+targetContentIds:
+  name: targetContentIds
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+      maxLength: 900
+    maxItems: 10
+  description: Filter by target content IDs (max 10)
+  style: form
+  explode: true
+
+targetUserIds:
+  name: targetUserIds
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+      pattern: '^[0-9a-fA-F]{24}$'
+    maxItems: 10
+  description: Filter by target user IDs (max 10)
+  style: form
+  explode: true
+
+creatorIds:
+  name: creatorIds
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+      pattern: '^[0-9a-fA-F]{24}$'
+    maxItems: 10
+  description: Filter by comment creator IDs (max 10)
+  style: form
+  explode: true
+
+referenceType:
+  name: referenceType
+  in: query
+  schema:
+    type: string
+    enum:
+      - post
+      - content
+      - story
+  description: Filter by reference type
+
+includeModerationDetails:
+  name: includeModerationDetails
+  in: query
+  schema:
+    type: boolean
+    default: false
+  description: Include moderation details (flags, AI moderation, check notes) in response
+
+

v1/search/response.yaml

@@ -8,7 +8,14 @@ post-pagination-response-200:
           posts:
             type: array
             items:
-              $ref: "../../schema/post.yaml#/PostV5"
+              allOf: 
+                - $ref: "../../schema/post.yaml#/PostV5"
+                - type: object
+                  properties:
+                    checkNote:
+                      $ref: "../../schema/moderation.yaml#/CheckNotes"
+                    checkStatus:
+                      $ref: "../../schema/moderation.yaml#/CheckStatus"
           postChildren:
             type: array
             items:

v4/comment/index.yaml

@@ -17,3 +17,98 @@ _commentId:
         $ref: "../../global/error.yaml#/NotFoundError"
       500:
         $ref: "../../global/error.yaml#/UnexpectedError"
+
+commentId-checks:
+  post:
+    summary: "Add check note to comment"
+    tags:
+      - "Comment"
+    security:
+      - BearerAuth: []
+    description: |
+      Add a check note to a comment for content review purposes. Admin only.
+
+      **Check Actions:**
+      - `check`: Mark the comment as checked/reviewed
+      - `need-follow-up`: Mark the comment as needing follow-up review
+      - `add-note`: Add a note without changing the check status (maximum 5 notes, not included note on check or need-follow-up)
+
+      **Check Status Updates:**
+      - When action is `check`, checkStatus becomes `checked`
+      - When action is `need-follow-up`, checkStatus becomes `follow-up-needed`
+      - When action is `add-note`, checkStatus remains unchanged
+
+      **Access Control:**
+      - Admin only with ManagePostAndComment permission
+    parameters:
+      - name: commentId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: '^[0-9a-fA-F]{24}$'
+        description: "MongoDB ObjectId of the comment"
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: "../../schema/moderation.yaml#/CreateCheckNote"
+    responses:
+      200:
+        $ref: "./response.yaml#/SerializedCommentsWithCheckStatus"
+      400:
+        $ref: "../../global/error.yaml#/BadRequestError"
+      403:
+        $ref: "../../global/error.yaml#/ForbiddenError"
+      404:
+        $ref: "../../global/error.yaml#/NotFoundError"
+      500:
+        $ref: "../../global/error.yaml#/UnexpectedError"
+
+commentId-checks-noteId:
+  delete:
+    summary: "Delete check note from comment"
+    tags:
+      - "Comment"
+    security:
+      - BearerAuth: []
+    description: |
+      Delete a specific check note from a comment. Admin only.
+
+      **Important Notes:**
+      - Soft deletes the check note (marks as deleted)
+      - Does not affect the comment's check status
+      - Admin only with ManagePostAndComment permission
+    parameters:
+      - name: commentId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: '^[0-9a-fA-F]{24}$'
+        description: "MongoDB ObjectId of the comment"
+      - name: noteId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: '^[0-9a-fA-F]{24}$'
+        description: "MongoDB ObjectId of the check note"
+    responses:
+      200:
+        description: "Check note deleted successfully"
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                success:
+                  type: boolean
+                  example: true
+      403:
+        $ref: "../../global/error.yaml#/ForbiddenError"
+      404:
+        $ref: "../../global/error.yaml#/NotFoundError"
+      500:
+        $ref: "../../global/error.yaml#/UnexpectedError"