openapi: 3.0.3
info:
  version: v1.0.0
  title: LE-KO Moderation
  license:
    name: private
    url: https://le-ko.deggex.com
  contact:
    email: denis@deggex.awsapps.com
  description: LE-KO Moderation API for content moderation, user reporting, and admin actions.
servers:
  - url: https://moderation-{env}.le-ko.deggex.com/{basePath}
    description: Moderation endpoint
    variables:
      basePath:
        default: v1
      env:
        default: dev
security:
  - bearerHttpAuthentication: []
tags:
  - name: admin
    description: Admin moderation panel
paths:
  /admin/queue:
    get:
      tags:
        - admin
      summary: Get moderation queue
      description: ✨ List content items awaiting moderation, with optional filters.
      operationId: getAdminQueue
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/TraceparentHeader'
        - name: entity
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Entity'
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/ModerationStatus'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Moderation queue items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModerationItemsPage'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /admin/recent:
    get:
      tags:
        - admin
      summary: Get recent platform content
      description: ✨ List all content posted on the platform within the last N minutes.
      operationId: getRecentContent
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/TraceparentHeader'
        - name: entity
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Entity'
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/ModerationStatus'
        - name: minutes
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1440
            default: 60
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Recent content items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModerationItemsPage'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /admin/content/{entity}/{entityId}/status:
    post:
      tags:
        - admin
      summary: Update moderation status
      description: ✨ Apply manual moderation decision for a content item.
      operationId: moderateContent
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/TraceparentHeader'
        - $ref: '#/components/parameters/EntityPath'
        - $ref: '#/components/parameters/EntityIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModerateRequest'
      responses:
        '204':
          description: Content moderation status updated
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Content not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /admin/audit:
    get:
      tags:
        - admin
      summary: Get audit log
      description: ✨ List moderation actions, including manual moderator actions and AI/system flags.
      operationId: getAuditLog
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/TraceparentHeader'
        - name: actorId
          in: query
          required: false
          schema:
            type: string
            format: uuid
        - name: entity
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Entity'
        - name: action
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AuditAction'
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Audit log entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditPage'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
components:
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer token using a JWT
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    CurrentUserId:
      name: x-current-user-id
      in: header
      required: true
      schema:
        type: string
        format: uuid
    TraceparentHeader:
      name: traceparent
      in: header
      required: false
      description: W3C Trace Context traceparent header for request tracing
      schema:
        type: string
        pattern: ^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$
        example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
    EntityPath:
      name: entity
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Entity'
    EntityIdPath:
      name: entityId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    Offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
  schemas:
    Entity:
      type: string
      description: Type of moderated entity
      enum:
        - user
        - service
        - group
        - post
        - comment
        - message
        - userAward
        - userAchievement
        - userCertificate
        - userWorkCompany
        - userWorkPosition
        - userCover
        - userAvatar
        - postImage
        - groupCover
        - serviceImage
        - userPhoto
        - groupAvatar
    ModerationStatus:
      type: string
      description: Moderation lifecycle status. Updated content that was rejected is moved back to review for re-check.
      enum:
        - posted
        - review
        - flagged
        - approved
        - rejected
    ViolationType:
      type: string
      description: Type of policy violation
      enum:
        - toxicBehavior
        - spam
        - commercialActivity
        - adultContent
        - violence
        - illegalActivity
        - other
    AuditAction:
      type: string
      description: Moderation action type
      enum:
        - approve
        - reject
        - flag
    ModerationDecisionStatus:
      type: string
      description: Moderator decision status
      enum:
        - approved
        - rejected
    ModerationItem:
      type: object
      required:
        - id
        - entity
        - entityId
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        entity:
          $ref: '#/components/schemas/Entity'
        entityId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/ModerationStatus'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ModerationItemsPage:
      type: object
      required:
        - items
        - total
        - limit
        - offset
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ModerationItem'
        total:
          type: integer
          minimum: 0
        limit:
          type: integer
        offset:
          type: integer
    ModerateRequest:
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/ModerationDecisionStatus'
        violation:
          $ref: '#/components/schemas/ViolationType'
          nullable: true
        moderatorId:
          type: string
          format: uuid
          nullable: true
        reason:
          type: string
          nullable: true
          maxLength: 1000
    AuditEntry:
      type: object
      required:
        - id
        - actorId
        - entity
        - entityId
        - action
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        actorId:
          type: string
          format: uuid
          description: Moderator who performed the action
        entity:
          $ref: '#/components/schemas/Entity'
        entityId:
          type: string
          format: uuid
        action:
          $ref: '#/components/schemas/AuditAction'
        previousStatus:
          $ref: '#/components/schemas/ModerationStatus'
          nullable: true
        newStatus:
          $ref: '#/components/schemas/ModerationStatus'
          nullable: true
        violation:
          $ref: '#/components/schemas/ViolationType'
          nullable: true
        createdAt:
          type: string
          format: date-time
    AuditPage:
      type: object
      required:
        - items
        - total
        - limit
        - offset
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AuditEntry'
        total:
          type: integer
          minimum: 0
        limit:
          type: integer
        offset:
          type: integer
    Error:
      type: object
      required:
        - code
        - message
        - endpoint
        - requestId
      properties:
        code:
          type: string
          enum:
            - validation
            - internal
            - not_found
            - unauthorized
            - forbidden
        message:
          type: string
        endpoint:
          type: string
        requestId:
          type: string
    Errors:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'