openapi: 3.1.0
info:
  title: CLAN Visibility Guard API
  version: 1.0.0
  description: Visibility policy checks and sensitivity classification for CLAN/ZHOS.
servers:
  - url: http://clan-visibility-guard:8112
tags:
  - name: health
  - name: visibility
paths:
  /health:
    get:
      tags: [health]
      summary: Service health check
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /visibility/check_downgrade:
    post:
      tags: [visibility]
      summary: Check if requested visibility downgrade is allowed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VisibilityCheckRequest"
      responses:
        "200":
          description: Downgrade check result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VisibilityCheckResponse"
        "400":
          description: Invalid visibility level
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /visibility/classify:
    post:
      tags: [visibility]
      summary: Classify text sensitivity and recommend level
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClassifyRequest"
      responses:
        "200":
          description: Classification result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClassifyResponse"
  /visibility/redact_for_level:
    post:
      tags: [visibility]
      summary: Redact text for target visibility level
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RedactRequest"
      responses:
        "200":
          description: Redaction result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RedactResponse"
        "400":
          description: Invalid visibility level
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  schemas:
    VisibilityLevel:
      type: string
      enum: [public, interclan, incircle, soulsafe, sacred]
    HealthResponse:
      type: object
      required: [status, service]
      properties:
        status:
          type: string
          example: ok
        service:
          type: string
          example: clan-visibility-guard
    ErrorResponse:
      type: object
      required: [detail]
      properties:
        detail:
          oneOf:
            - type: string
            - type: object
    VisibilityCheckRequest:
      type: object
      required: [current_level, requested_level]
      properties:
        current_level:
          $ref: "#/components/schemas/VisibilityLevel"
        requested_level:
          $ref: "#/components/schemas/VisibilityLevel"
    VisibilityCheckResponse:
      type: object
      required: [allowed, reason, current_level, requested_level]
      properties:
        allowed:
          type: boolean
        reason:
          type: string
          enum: [ok, downgrade_requires_consent]
        current_level:
          $ref: "#/components/schemas/VisibilityLevel"
        requested_level:
          $ref: "#/components/schemas/VisibilityLevel"
    ClassifyRequest:
      type: object
      required: [text]
      properties:
        text:
          type: string
    ClassifyResponse:
      type: object
      required: [recommended_level, sensitivity_flags]
      properties:
        recommended_level:
          $ref: "#/components/schemas/VisibilityLevel"
        sensitivity_flags:
          type: array
          items:
            type: string
    RedactRequest:
      type: object
      required: [text, target_level]
      properties:
        text:
          type: string
        target_level:
          $ref: "#/components/schemas/VisibilityLevel"
    RedactResponse:
      type: object
      required: [target_level, redacted_text, changed]
      properties:
        target_level:
          $ref: "#/components/schemas/VisibilityLevel"
        redacted_text:
          type: string
        changed:
          type: boolean