EpicDirectories comments (admin) API

openapi: 3.2.0
info:
  title: EpicDirectories comments (admin) API
  description: API-first directory data platform.
  version: '1.0'
  contact: {}
servers:
- url: https://api.epicdirectories.com
  description: Production
- url: http://localhost:3333
  description: Local development
tags:
- name: comments (admin)
paths:
  /v1/directories/{directoryId}/comments:
    get:
      operationId: CommentsAdminController_list
      summary: List the comment queue
      description: 'Defaults to `status=pending`. Optional `path` narrows to one page. Also returns `countsByStatus` across the whole directory.


        Each row carries `sameSourceOnPath`: how many OTHER comments on the same page arrived from the same (hashed) source address. A hint, not a verdict.'
      parameters:
      - name: directoryId
        required: true
        in: path
        schema:
          type: string
      - name: status
        required: false
        in: query
        description: Defaults to `pending`
        schema:
          enum:
          - pending
          - approved
          - rejected
          - spam
          type: string
      - name: path
        required: false
        in: query
        description: Only comments on this page. Normalised exactly as on write.
        schema:
          type: string
      - name: limit
        required: false
        in: query
        description: Default 50, max 200
        schema:
          type: string
      - name: offset
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Paginated comments + counts by status
        '404':
          description: Directory not found or not yours
      tags:
      - comments (admin)
      security:
      - bearer: []
  /v1/directories/{directoryId}/comments/{commentId}:
    get:
      operationId: CommentsAdminController_get
      summary: Get one comment, including its abuse metadata
      description: Includes the hashed source address, user agent, Turnstile verdict and the submitter email — none of which any public read returns.
      parameters:
      - name: directoryId
        required: true
        in: path
        schema:
          type: string
      - name: commentId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: The comment
        '404':
          description: Not found
      tags:
      - comments (admin)
      security:
      - bearer: []
  /v1/directories/{directoryId}/comments/{commentId}/approve:
    post:
      operationId: CommentsAdminController_approve
      summary: Approve a comment — this publishes it
      description: Makes a stranger's text publicly readable, immediately. There is no draft state to catch a mistake. Returns 409 if the comment is already approved.
      parameters:
      - name: directoryId
        required: true
        in: path
        schema:
          type: string
      - name: commentId
        required: true
        in: path
        schema:
          type: string
      responses:
        '201':
          description: Approved and published
        '404':
          description: Not found
        '409':
          description: Already approved
      tags:
      - comments (admin)
      security:
      - bearer: []
  /v1/directories/{directoryId}/comments/{commentId}/reject:
    post:
      operationId: CommentsAdminController_reject
      summary: Reject a comment, or unpublish an approved one
      description: 'Pass `{ "spam": true }` to file it as spam instead of merely rejected. Reversible — the row is retained and its status can flip back.'
      parameters:
      - name: directoryId
        required: true
        in: path
        schema:
          type: string
      - name: commentId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectCommentDto'
      responses:
        '201':
          description: Rejected
        '404':
          description: Not found
      tags:
      - comments (admin)
      security:
      - bearer: []
  /v1/directories/{directoryId}/comments/{commentId}/reply:
    put:
      operationId: CommentsAdminController_reply
      summary: Set or clear the editors' public reply
      description: '`{ "reply": "…", "replyAuthor": "The editors" }`; `reply: null` or `""` clears it. Published only once (and while) the comment is approved.'
      parameters:
      - name: directoryId
        required: true
        in: path
        schema:
          type: string
      - name: commentId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplyToCommentDto'
      responses:
        '200':
          description: The updated comment
        '404':
          description: Not found
      tags:
      - comments (admin)
      security:
      - bearer: []
components:
  schemas:
    ReplyToCommentDto:
      type: object
      properties:
        reply:
          type:
          - string
          - 'null'
          description: The editors' public reply, shown beneath the comment once it is approved. `null` or an empty string clears it.
          maxLength: 4000
        replyAuthor:
          type: string
          description: Who the reply is from, as readers should see it, e.g. "The editors".
          maxLength: 80
      required:
      - reply
    RejectCommentDto:
      type: object
      properties:
        spam:
          type: boolean
          description: Mark as spam rather than merely rejected, so abuse triage can separate the two.
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    apiKey:
      type: apiKey
      in: header
      name: x-api-key