openapi: 3.0.0
info:
  title: VerifyWise API
  description: AI Governance Platform API
  version: 2.0.0
servers:
  - url: /api
    description: Main API server

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    ProjectId:
      name: id
      in: path
      required: true
      description: The numeric project ID
      schema:
        type: integer
        example: 1
    PolicyId:
      name: id
      in: path
      required: true
      description: Numeric ID of the policy
      schema:
        type: integer
        example: 42
  schemas:
    Error:
      type: object
      properties:
        data:
          type: string
    AiRiskClassification:
      type: string
      enum: [Prohibited, High risk, Limited risk, Minimal risk]
      description: EU AI Act risk classification level
    HighRiskRole:
      type: string
      enum: [Deployer, Provider, Distributor, Importer, Product manufacturer, Authorized representative]
      description: Role of the organization under the EU AI Act for high-risk systems
    ProjectStatus:
      type: string
      enum: [Not started, In progress, Under review, Completed, Closed, On hold, Rejected]
      description: Current lifecycle status of the project
    CreateProjectRequest:
      type: object
      required: [project_title, owner, start_date, framework]
      properties:
        project_title:
          type: string
          example: Customer Support Chatbot
        owner:
          type: integer
          example: 1
        start_date:
          type: string
          format: date-time
          example: "2026-01-15T00:00:00.000Z"
        geography:
          type: integer
          default: 1
          example: 1
        ai_risk_classification:
          $ref: "#/components/schemas/AiRiskClassification"
        type_of_high_risk_role:
          $ref: "#/components/schemas/HighRiskRole"
        goal:
          type: string
          nullable: true
          example: Automate tier-1 support queries
        target_industry:
          type: string
          nullable: true
          example: Financial Services
        description:
          type: string
          nullable: true
          example: An LLM-powered chatbot for handling customer inquiries
        status:
          $ref: "#/components/schemas/ProjectStatus"
        is_organizational:
          type: boolean
          default: false
        members:
          type: array
          items:
            type: integer
          example: [2, 3, 5]
        framework:
          type: array
          items:
            type: integer
          example: [1, 2]
        approval_workflow_id:
          type: integer
          nullable: true
          example: null
        enable_ai_data_insertion:
          type: boolean
          default: false
    UpdateProjectRequest:
      type: object
      properties:
        project_title:
          type: string
        owner:
          type: integer
        start_date:
          type: string
          format: date-time
        geography:
          type: integer
        ai_risk_classification:
          $ref: "#/components/schemas/AiRiskClassification"
        type_of_high_risk_role:
          $ref: "#/components/schemas/HighRiskRole"
        goal:
          type: string
          nullable: true
        target_industry:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        status:
          $ref: "#/components/schemas/ProjectStatus"
        last_updated:
          type: string
          format: date-time
        last_updated_by:
          type: integer
        members:
          type: array
          items:
            type: integer
          example: [2, 3, 5]
    ProjectFramework:
      type: object
      properties:
        project_framework_id:
          type: integer
        framework_id:
          type: integer
        name:
          type: string
          example: EU AI Act
    Project:
      type: object
      properties:
        id:
          type: integer
          example: 42
        uc_id:
          type: string
          example: UC-7
        project_title:
          type: string
          example: Customer Support Chatbot
        owner:
          type: integer
          example: 1
        start_date:
          type: string
          format: date-time
        geography:
          type: integer
          example: 1
        ai_risk_classification:
          $ref: "#/components/schemas/AiRiskClassification"
        type_of_high_risk_role:
          $ref: "#/components/schemas/HighRiskRole"
        goal:
          type: string
          nullable: true
        target_industry:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        status:
          $ref: "#/components/schemas/ProjectStatus"
        last_updated:
          type: string
          format: date-time
        last_updated_by:
          type: integer
        created_at:
          type: string
          format: date-time
        is_organizational:
          type: boolean
        is_demo:
          type: boolean
        approval_workflow_id:
          type: integer
          nullable: true
        pending_frameworks:
          type: string
          nullable: true
        enable_ai_data_insertion:
          type: boolean
        organization_id:
          type: integer
        framework:
          type: array
          items:
            $ref: "#/components/schemas/ProjectFramework"
        members:
          type: array
          items:
            type: integer
    ProjectListItem:
      allOf:
        - $ref: "#/components/schemas/Project"
        - type: object
          properties:
            has_pending_approval:
              type: boolean
            approval_status:
              type: string
              nullable: true
              enum: [pending, rejected, null]
            _source:
              type: string
              nullable: true
              example: jira-assets
    ProjectDetail:
      allOf:
        - $ref: "#/components/schemas/Project"
        - type: object
          properties:
            owner_name:
              type: string
              example: John Doe
            has_pending_approval:
              type: boolean
            approval_status:
              type: string
              nullable: true
              enum: [pending, rejected, null]
    ProjectWithMembers:
      allOf:
        - $ref: "#/components/schemas/Project"
        - type: object
          properties:
            members:
              type: array
              items:
                type: integer
    ProjectStats:
      type: object
      properties:
        user:
          type: object
          properties:
            name:
              type: string
            surname:
              type: string
            email:
              type: string
              format: email
            project_last_updated:
              type: string
              format: date-time
            userWhoUpdated:
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string
                surname:
                  type: string
                email:
                  type: string
                  format: email
    ProjectRiskCount:
      type: object
      properties:
        risk_level_autocalculated:
          type: string
          example: High
        count:
          type: string
          example: "3"
    VendorRiskCount:
      type: object
      properties:
        risk_level:
          type: string
          example: Critical
        count:
          type: string
          example: "2"
    ComplianceProgress:
      type: object
      properties:
        allsubControls:
          oneOf:
            - type: string
            - type: integer
          example: "45"
        allDonesubControls:
          oneOf:
            - type: string
            - type: integer
          example: "12"
    AssessmentProgress:
      type: object
      properties:
        totalQuestions:
          oneOf:
            - type: string
            - type: integer
          example: "80"
        answeredQuestions:
          oneOf:
            - type: string
            - type: integer
          example: "35"
    ControlCategory:
      type: object
      properties:
        id:
          type: integer
        project_id:
          type: integer
        name:
          type: string
        organization_id:
          type: integer
        controls:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              control_category_id:
                type: integer
              title:
                type: string
              description:
                type: string
              status:
                type: string
              numberOfSubcontrols:
                type: integer
              numberOfDoneSubcontrols:
                type: integer
              subControls:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    control_id:
                      type: integer
                    title:
                      type: string
                    description:
                      type: string
                    status:
                      type: string
                      enum: [Draft, In progress, Done]
                    organization_id:
                      type: integer
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          example: Not Found
        data:
          example: {}
    ServerError:
      type: object
      properties:
        message:
          type: string
          example: Internal Server Error
        error:
          type: string
          example: "Unexpected error occurred"
    UserSafe:
      type: object
      description: User object with password_hash excluded
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "John"
        surname:
          type: string
          example: "Doe"
        email:
          type: string
          format: email
          example: "john@example.com"
        role_id:
          type: integer
          description: "1=Admin, 2=Reviewer, 3=Editor, 4=Auditor, 5=SuperAdmin"
          example: 1
        created_at:
          type: string
          format: date-time
        last_login:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        is_demo:
          type: boolean
          default: false
        organization_id:
          type: integer
          nullable: true
          example: 1
        profile_photo_id:
          type: integer
          nullable: true
      required:
        - id
        - name
        - surname
        - email
        - role_id
        - created_at
    StatusEnvelope:
      type: object
      properties:
        message:
          type: string
          description: HTTP status text (e.g. "OK", "Created", "Accepted")
        data:
          description: Response payload (varies by endpoint)
    ErrorEnvelope:
      type: object
      properties:
        message:
          type: string
          description: HTTP status text or error category
        data:
          type: string
          description: Error detail message
    ProgressResponse:
      type: object
      properties:
        assessmentsMetadata:
          type: array
          items:
            type: object
            properties:
              projectId:
                type: integer
              totalAssessments:
                type: integer
              doneAssessments:
                type: integer
        controlsMetadata:
          type: array
          items:
            type: object
            properties:
              projectId:
                type: integer
              totalSubControls:
                type: integer
              doneSubControls:
                type: integer
        allTotalAssessments:
          type: integer
        allDoneAssessments:
          type: integer
        allTotalSubControls:
          type: integer
        allDoneSubControls:
          type: integer

    Vendor:
      type: object
      properties:
        id:
          type: integer
          description: Auto-generated primary key
          example: 42
        order_no:
          type: integer
          nullable: true
          description: Display order number
        vendor_name:
          type: string
          description: Name of the vendor
          example: "Acme Corp"
        vendor_provides:
          type: string
          description: What the vendor provides
          example: "Cloud hosting services"
        assignee:
          type: integer
          description: User ID of the assigned owner
          example: 5
        website:
          type: string
          description: Vendor website URL
          example: "https://acme.example.com"
        vendor_contact_person:
          type: string
          description: Name of the vendor contact
          example: "Jane Doe"
        review_result:
          type: string
          nullable: true
          description: Free-text review result summary
        review_status:
          type: string
          nullable: true
          enum:
            - Not started
            - In review
            - Reviewed
            - Requires follow-up
          default: Not started
          description: Current review lifecycle status
        reviewer:
          type: integer
          nullable: true
          description: User ID of the reviewer
        review_date:
          type: string
          format: date-time
          nullable: true
          description: Date the review was performed (ISO 8601)
        is_demo:
          type: boolean
          default: false
          description: Whether this is a demo vendor (read-only after creation)
        projects:
          type: array
          items:
            type: integer
          description: Array of associated project IDs
        data_sensitivity:
          type: string
          nullable: true
          enum:
            - None
            - Internal only
            - "Personally identifiable information (PII)"
            - Financial data
            - "Health data (e.g. HIPAA)"
            - Model weights or AI assets
            - Other sensitive data
          description: Scorecard - type of data the vendor accesses
        business_criticality:
          type: string
          nullable: true
          enum:
            - "Low (vendor supports non-core functions)"
            - "Medium (affects operations but is replaceable)"
            - "High (critical to core services or products)"
          description: Scorecard - how critical the vendor is to operations
        past_issues:
          type: string
          nullable: true
          enum:
            - None
            - "Minor incident (e.g. small delay, minor bug)"
            - "Major incident (e.g. data breach, legal issue)"
          description: Scorecard - history of past incidents
        regulatory_exposure:
          type: string
          nullable: true
          enum:
            - None
            - "GDPR (EU)"
            - "HIPAA (US)"
            - SOC 2
            - ISO 27001
            - EU AI act
            - "CCPA (california)"
            - Other
          description: Scorecard - applicable regulatory framework
        risk_score:
          type: integer
          nullable: true
          description: Computed risk score for the vendor
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp (ISO 8601)
      required:
        - vendor_name
        - vendor_provides
        - assignee
        - website
        - vendor_contact_person
    VendorWithReviewerName:
      allOf:
        - $ref: "#/components/schemas/Vendor"
        - type: object
          properties:
            reviewer_name:
              type: string
              description: Full name of the reviewer (joined from users table)
              example: "John Smith"
    VendorInput:
      type: object
      required:
        - vendor_name
        - vendor_provides
        - assignee
        - website
        - vendor_contact_person
      properties:
        vendor_name:
          type: string
          description: Name of the vendor (required, non-empty)
        vendor_provides:
          type: string
          description: What the vendor provides (required, non-empty)
        assignee:
          type: integer
          minimum: 1
          description: User ID of the assigned owner (required, >= 1)
        website:
          type: string
          description: Vendor website URL (required, non-empty)
        vendor_contact_person:
          type: string
          description: Name of the vendor contact (required, non-empty)
        review_result:
          type: string
          description: Free-text review result summary
        review_status:
          type: string
          enum:
            - Not started
            - In review
            - Reviewed
            - Requires follow-up
          description: Current review lifecycle status
        reviewer:
          type: integer
          minimum: 1
          description: User ID of the reviewer
        review_date:
          type: string
          format: date-time
          description: Date of the review (ISO 8601)
        order_no:
          type: integer
          description: Display order number
        is_demo:
          type: boolean
          default: false
          description: Mark as demo vendor
        projects:
          type: array
          items:
            type: integer
          description: Array of project IDs to associate
        data_sensitivity:
          type: string
          enum:
            - None
            - Internal only
            - "Personally identifiable information (PII)"
            - Financial data
            - "Health data (e.g. HIPAA)"
            - Model weights or AI assets
            - Other sensitive data
        business_criticality:
          type: string
          enum:
            - "Low (vendor supports non-core functions)"
            - "Medium (affects operations but is replaceable)"
            - "High (critical to core services or products)"
        past_issues:
          type: string
          enum:
            - None
            - "Minor incident (e.g. small delay, minor bug)"
            - "Major incident (e.g. data breach, legal issue)"
        regulatory_exposure:
          type: string
          enum:
            - None
            - "GDPR (EU)"
            - "HIPAA (US)"
            - SOC 2
            - ISO 27001
            - EU AI act
            - "CCPA (california)"
            - Other
        risk_score:
          type: integer
          description: Computed risk score
    VendorUpdate:
      type: object
      description: All fields are optional. Only provided fields are updated. Review and scorecard fields can be set to null to clear them.
      properties:
        vendor_name:
          type: string
        vendor_provides:
          type: string
        assignee:
          type: integer
          minimum: 1
        website:
          type: string
        vendor_contact_person:
          type: string
        review_result:
          type: string
          nullable: true
        review_status:
          type: string
          nullable: true
          enum:
            - Not started
            - In review
            - Reviewed
            - Requires follow-up
        reviewer:
          type: integer
          nullable: true
        review_date:
          type: string
          format: date-time
          nullable: true
        order_no:
          type: integer
        projects:
          type: array
          items:
            type: integer
        data_sensitivity:
          type: string
          nullable: true
          enum:
            - None
            - Internal only
            - "Personally identifiable information (PII)"
            - Financial data
            - "Health data (e.g. HIPAA)"
            - Model weights or AI assets
            - Other sensitive data
        business_criticality:
          type: string
          nullable: true
          enum:
            - "Low (vendor supports non-core functions)"
            - "Medium (affects operations but is replaceable)"
            - "High (critical to core services or products)"
        past_issues:
          type: string
          nullable: true
          enum:
            - None
            - "Minor incident (e.g. small delay, minor bug)"
            - "Major incident (e.g. data breach, legal issue)"
        regulatory_exposure:
          type: string
          nullable: true
          enum:
            - None
            - "GDPR (EU)"
            - "HIPAA (US)"
            - SOC 2
            - ISO 27001
            - EU AI act
            - "CCPA (california)"
            - Other
        risk_score:
          type: integer
          nullable: true
    ModelInventoryStatus:
      type: string
      enum:
        - Approved
        - Restricted
        - Pending
        - Blocked
        - Rejected
      description: Current approval/review status of the model
    Filedata:
      type: object
      description: Metadata for an uploaded security-assessment file
      properties:
        id:
          type: integer
          description: File record ID
        filename:
          type: string
          description: Original file name
        size:
          type: integer
          description: File size in bytes
        mimetype:
          type: string
          description: MIME type (e.g. application/pdf)
        upload_date:
          type: string
          format: date-time
          description: ISO 8601 upload timestamp
        uploaded_by:
          type: integer
          description: User ID who uploaded the file
      required:
        - id
        - filename
        - size
        - mimetype
        - upload_date
        - uploaded_by
    ModelInventoryResponse:
      type: object
      description: Model inventory record as returned by the API
      properties:
        id:
          type: integer
          description: Auto-generated primary key
          example: 42
        provider_model:
          type: string
          nullable: true
          description: Legacy combined provider+model field (backward compatibility)
          example: "OpenAI / GPT-4"
        provider:
          type: string
          description: Model provider name
          example: OpenAI
        model:
          type: string
          description: Model name
          example: GPT-4
        version:
          type: string
          description: Model version identifier
          example: "turbo-2024-04-09"
        approver:
          type: integer
          nullable: true
          description: User ID of the assigned approver
          example: 7
        capabilities:
          type: array
          items:
            type: string
          description: >
            List of capability strings. Stored as comma-separated text in the DB,
            returned as an array.
          example: ["Text Generation", "Code Generation", "Reasoning"]
        security_assessment:
          type: boolean
          description: Whether a security assessment has been completed
          example: false
        status:
          $ref: "#/components/schemas/ModelInventoryStatus"
        status_date:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last status change
          example: "2026-04-15T10:30:00.000Z"
        reference_link:
          type: string
          nullable: true
          description: URL to external model documentation or model card
          example: "https://platform.openai.com/docs/models/gpt-4"
        biases:
          type: string
          description: Known biases of the model
          example: "May reflect biases present in training data"
        limitations:
          type: string
          description: Known limitations of the model
          example: "Knowledge cutoff, potential hallucinations"
        hosting_provider:
          type: string
          description: Where the model is hosted
          example: "Azure OpenAI"
        security_assessment_data:
          type: array
          items:
            $ref: "#/components/schemas/Filedata"
          description: Uploaded security assessment file metadata
        is_demo:
          type: boolean
          description: Whether this is a demo/sample record
          example: false
        created_at:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp
          example: "2026-04-10T08:00:00.000Z"
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 last-updated timestamp
          example: "2026-04-15T10:30:00.000Z"
        projects:
          type: array
          items:
            type: integer
          description: IDs of projects this model is associated with
          example: [1, 3]
        frameworks:
          type: array
          items:
            type: integer
          description: IDs of frameworks this model is associated with
          example: [5]
    ModelInventoryCreateRequest:
      type: object
      description: Request body for creating a new model inventory record
      required:
        - provider
        - model
        - version
        - capabilities
        - status
        - status_date
        - reference_link
        - biases
        - limitations
        - hosting_provider
      properties:
        provider_model:
          type: string
          description: Legacy combined provider+model field (optional, backward compatibility)
          example: "OpenAI / GPT-4"
        provider:
          type: string
          description: Model provider name
          example: OpenAI
        model:
          type: string
          description: Model name
          example: GPT-4
        version:
          type: string
          description: Model version identifier
          example: "turbo-2024-04-09"
        approver:
          type: integer
          nullable: true
          description: User ID of the assigned approver
          example: 7
        capabilities:
          oneOf:
            - type: string
              description: Comma-separated capabilities
            - type: array
              items:
                type: string
              description: Array of capability strings
          description: >
            Accepted as either a comma-separated string or an array of strings.
            Arrays are joined with ", " before storage.
          example: ["Text Generation", "Code Generation"]
        security_assessment:
          type: boolean
          description: Whether a security assessment has been completed
          default: false
        status:
          $ref: "#/components/schemas/ModelInventoryStatus"
        status_date:
          type: string
          format: date-time
          description: ISO 8601 timestamp for the status
          example: "2026-04-15T10:30:00.000Z"
        reference_link:
          type: string
          description: URL to external model documentation or model card
          example: "https://platform.openai.com/docs/models/gpt-4"
        biases:
          type: string
          description: Known biases of the model
          example: "May reflect biases present in training data"
        limitations:
          type: string
          description: Known limitations of the model
          example: "Knowledge cutoff, potential hallucinations"
        hosting_provider:
          type: string
          description: Where the model is hosted
          example: "Azure OpenAI"
        security_assessment_data:
          type: array
          items:
            $ref: "#/components/schemas/Filedata"
          description: Uploaded security assessment file metadata
          default: []
        is_demo:
          type: boolean
          description: Whether this is a demo/sample record
          default: false
        projects:
          type: array
          items:
            type: integer
          description: Project IDs to associate with this model
          default: []
          example: [1, 3]
        frameworks:
          type: array
          items:
            type: integer
          description: Framework IDs to associate with this model
          default: []
          example: [5]
    ModelInventoryUpdateRequest:
      type: object
      description: >
        Request body for updating a model inventory record. All fields are
        optional; only provided fields are modified.
      properties:
        provider_model:
          type: string
          description: Legacy combined provider+model field
        provider:
          type: string
          description: Model provider name
        model:
          type: string
          description: Model name
        version:
          type: string
          description: Model version identifier
        approver:
          type: integer
          nullable: true
          description: User ID of the assigned approver
        capabilities:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: Capabilities (string or array)
        security_assessment:
          type: boolean
          description: Whether a security assessment has been completed
        status:
          $ref: "#/components/schemas/ModelInventoryStatus"
        status_date:
          type: string
          format: date-time
          description: ISO 8601 timestamp for the status
        reference_link:
          type: string
          description: URL to external model documentation
        biases:
          type: string
          description: Known biases of the model
        limitations:
          type: string
          description: Known limitations of the model
        hosting_provider:
          type: string
          description: Where the model is hosted
        security_assessment_data:
          type: array
          items:
            $ref: "#/components/schemas/Filedata"
          description: Uploaded security assessment file metadata
        is_demo:
          type: boolean
          description: Whether this is a demo/sample record
        projects:
          type: array
          items:
            type: integer
          description: >
            Project IDs to associate. When provided (even empty), replaces all
            existing project associations.
        frameworks:
          type: array
          items:
            type: integer
          description: >
            Framework IDs to associate. When provided (even empty), replaces all
            existing framework associations.
        deleteProjects:
          type: boolean
          description: >
            When true, clears all project associations even if projects array is
            empty. Used to force-delete associations without providing replacements.
          default: false
        deleteFrameworks:
          type: boolean
          description: >
            When true, clears all framework associations even if frameworks array
            is empty. Used to force-delete associations without providing replacements.
          default: false

    PolicyWithReviewers:
      type: object
      description: A policy record with computed assigned reviewer IDs
      properties:
        id:
          type: integer
          description: Auto-generated primary key
          example: 42
        organization_id:
          type: integer
          description: Tenant organization ID
          example: 1
        title:
          type: string
          description: Policy title
          example: "AI Ethics Policy"
        content_html:
          type: string
          description: Full policy content as HTML
          example: "<h1>AI Ethics Policy</h1><p>...</p>"
        status:
          type: string
          description: Policy lifecycle status
          example: "draft"
        tags:
          type: array
          items:
            type: string
            enum:
              - AI ethics
              - Fairness
              - Transparency
              - Explainability
              - Bias mitigation
              - Privacy
              - Data governance
              - Model risk
              - Accountability
              - Security
              - LLM
              - Human oversight
              - EU AI Act
              - ISO 42001
              - NIST RMF
              - Red teaming
              - Audit
              - Monitoring
              - Vendor management
          description: Categorization tags
        next_review_date:
          type: string
          format: date-time
          nullable: true
          description: Scheduled next review date
        author_id:
          type: integer
          description: User ID of the policy creator
          example: 1
        last_updated_by:
          type: integer
          description: User ID of the last editor
          example: 1
        last_updated_at:
          type: string
          format: date-time
          description: Timestamp of last update
        review_status:
          type: string
          nullable: true
          enum:
            - pending_review
            - approved
            - changes_requested
            - null
          description: Current review workflow status
        review_comment:
          type: string
          nullable: true
          description: Most recent review comment
        reviewed_by:
          type: integer
          nullable: true
          description: User ID of the last reviewer
        reviewed_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of last review action
        is_demo:
          type: boolean
          description: Whether this is a demo/seed policy
          default: false
        created_at:
          type: string
          format: date-time
          description: Row creation timestamp (set by database)
        assigned_reviewer_ids:
          type: array
          items:
            type: integer
          description: User IDs of assigned reviewers (aggregated from mapping table)
          example: [2, 5]
    PolicyCreateRequest:
      type: object
      required:
        - title
        - content_html
        - status
      properties:
        title:
          type: string
          description: Policy title
          example: "Data Governance Policy"
        content_html:
          type: string
          description: Full policy content as HTML
          example: "<h1>Data Governance</h1><p>This policy outlines...</p>"
        status:
          type: string
          description: Initial policy status
          example: "draft"
        tags:
          type: array
          items:
            type: string
          description: Categorization tags (must be from the allowed tag list)
          example: ["Data governance", "Privacy"]
        next_review_date:
          type: string
          format: date-time
          nullable: true
          description: Scheduled next review date
          example: "2026-07-01T00:00:00.000Z"
        assigned_reviewer_ids:
          type: array
          items:
            type: integer
          description: User IDs to assign as reviewers
          example: [2, 5]
        is_demo:
          type: boolean
          description: Mark as a demo policy
          default: false
    PolicyUpdateRequest:
      type: object
      description: All fields are optional. Only provided fields are updated.
      properties:
        title:
          type: string
          description: Updated policy title
        content_html:
          type: string
          description: Updated policy content as HTML
        status:
          type: string
          description: Updated policy status
        tags:
          type: array
          items:
            type: string
          description: Replacement tag list (must be from the allowed tag list)
        next_review_date:
          type: string
          format: date-time
          nullable: true
          description: Updated next review date
        assigned_reviewer_ids:
          type: array
          items:
            type: integer
          description: Replacement reviewer list (fully replaces existing reviewers)
    # ── Project Risk ──
    ProjectRiskInput:
      type: object
      required:
        - risk_name
        - risk_owner
        - risk_description
      properties:
        risk_name:
          type: string
          description: Name/title of the risk.
        risk_owner:
          type: integer
          description: User ID of the risk owner (must be >= 1).
        ai_lifecycle_phase:
          type: string
          enum:
            - Problem definition & planning
            - Data collection & processing
            - Model development & training
            - Model validation & testing
            - Deployment & integration
            - Monitoring & maintenance
            - Decommissioning & retirement
        risk_description:
          type: string
          description: Detailed description of the risk.
        risk_category:
          type: array
          items:
            type: string
          description: Array of category labels.
        impact:
          type: string
        assessment_mapping:
          type: string
        controls_mapping:
          type: string
        likelihood:
          type: string
          enum: [Rare, Unlikely, Possible, Likely, Almost Certain]
        severity:
          type: string
          enum: [Negligible, Minor, Moderate, Major, Catastrophic]
        risk_level_autocalculated:
          type: string
          enum: [No risk, Very low risk, Low risk, Medium risk, High risk, Very high risk]
        review_notes:
          type: string
        mitigation_status:
          type: string
          enum: [Not Started, In Progress, Completed, On Hold, Deferred, Canceled, Requires review]
        current_risk_level:
          type: string
          enum: [Very Low risk, Low risk, Medium risk, High risk, Very high risk]
        deadline:
          type: string
          format: date-time
        mitigation_plan:
          type: string
        implementation_strategy:
          type: string
        mitigation_evidence_document:
          type: string
        likelihood_mitigation:
          type: string
          enum: [Rare, Unlikely, Possible, Likely, Almost Certain]
        risk_severity:
          type: string
          enum: [Negligible, Minor, Moderate, Major, Critical]
        final_risk_level:
          type: string
        risk_approval:
          type: integer
          description: User ID of the approver.
        approval_status:
          type: string
        date_of_assessment:
          type: string
          format: date-time
        is_demo:
          type: boolean
          default: false
        projects:
          type: array
          items:
            type: integer
          description: Array of project IDs to link this risk to.
        frameworks:
          type: array
          items:
            type: integer
          description: Array of framework IDs to link this risk to.
        event_frequency_min:
          type: number
          nullable: true
        event_frequency_likely:
          type: number
          nullable: true
        event_frequency_max:
          type: number
          nullable: true
        loss_regulatory_min:
          type: number
          nullable: true
        loss_regulatory_likely:
          type: number
          nullable: true
        loss_regulatory_max:
          type: number
          nullable: true
        loss_operational_min:
          type: number
          nullable: true
        loss_operational_likely:
          type: number
          nullable: true
        loss_operational_max:
          type: number
          nullable: true
        loss_litigation_min:
          type: number
          nullable: true
        loss_litigation_likely:
          type: number
          nullable: true
        loss_litigation_max:
          type: number
          nullable: true
        loss_reputational_min:
          type: number
          nullable: true
        loss_reputational_likely:
          type: number
          nullable: true
        loss_reputational_max:
          type: number
          nullable: true
        control_effectiveness:
          type: number
          nullable: true
          description: Percentage 0-100.
        mitigation_cost_annual:
          type: number
          nullable: true
        benchmark_id:
          type: integer
          nullable: true
        currency:
          type: string
          nullable: true
          default: USD
          maxLength: 3
    ProjectRiskResponse:
      allOf:
        - $ref: "#/components/schemas/ProjectRiskInput"
        - type: object
          properties:
            id:
              type: integer
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            total_loss_likely:
              type: number
              nullable: true
            ale_estimate:
              type: number
              nullable: true
            residual_ale:
              type: number
              nullable: true
            roi_percentage:
              type: number
              nullable: true
            projects:
              type: array
              items:
                type: integer
            frameworks:
              type: array
              items:
                type: integer
            subClauses:
              type: array
              items:
                type: object
            annexCategories:
              type: array
              items:
                type: object
            controls:
              type: array
              items:
                type: object
            assessments:
              type: array
              items:
                type: object
            annexControls_27001:
              type: array
              items:
                type: object
            subClauses_27001:
              type: array
              items:
                type: object
    # ── Vendor Risk ──
    VendorRiskInput:
      type: object
      required:
        - vendor_id
        - risk_description
        - impact_description
        - likelihood
        - risk_severity
        - action_plan
        - action_owner
        - risk_level
      properties:
        vendor_id:
          type: integer
          description: ID of the vendor this risk belongs to.
        order_no:
          type: integer
          nullable: true
          description: Optional ordering number.
        risk_description:
          type: string
        impact_description:
          type: string
        likelihood:
          type: string
          enum: [Rare, Unlikely, Possible, Likely, Almost certain]
        risk_severity:
          type: string
          enum: [Negligible, Minor, Moderate, Major, Catastrophic]
        action_plan:
          type: string
        action_owner:
          type: integer
          description: User ID of the action owner.
        risk_level:
          type: string
          description: Free-text risk level.
        is_demo:
          type: boolean
          default: false
    VendorRiskResponse:
      type: object
      properties:
        id:
          type: integer
        vendor_id:
          type: integer
        order_no:
          type: integer
          nullable: true
        risk_description:
          type: string
        impact_description:
          type: string
        impact:
          type: string
          nullable: true
        likelihood:
          type: string
          enum: [Rare, Unlikely, Possible, Likely, Almost certain]
        risk_severity:
          type: string
          enum: [Negligible, Minor, Moderate, Major, Catastrophic]
        action_plan:
          type: string
        action_owner:
          type: integer
        risk_level:
          type: string
        is_demo:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    VendorRiskAllProjectsResponse:
      description: Extended vendor risk with joined vendor/project info.
      type: object
      properties:
        risk_id:
          type: integer
        vendor_id:
          type: integer
        order_no:
          type: integer
          nullable: true
        risk_description:
          type: string
        impact_description:
          type: string
        likelihood:
          type: string
        risk_severity:
          type: string
        action_plan:
          type: string
        action_owner:
          type: integer
        risk_level:
          type: string
        is_demo:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        is_deleted:
          type: boolean
        deleted_at:
          type: string
          format: date-time
          nullable: true
        vendor_name:
          type: string
        project_id:
          type: integer
          nullable: true
        project_title:
          type: string
          nullable: true
    # ── Model Risk ──
    ModelRiskInput:
      type: object
      required:
        - risk_name
        - risk_category
        - risk_level
        - owner
        - target_date
      properties:
        risk_name:
          type: string
        risk_category:
          type: string
          enum: [Performance, Bias & Fairness, Security, Data Quality, Compliance]
        risk_level:
          type: string
          enum: [Low, Medium, High, Critical]
        status:
          type: string
          enum: [Open, In Progress, Resolved, Accepted]
          default: Open
        owner:
          type: string
          description: Name or identifier of the risk owner.
        target_date:
          type: string
          format: date
          description: Next review / target date.
        description:
          type: string
        mitigation_plan:
          type: string
        impact:
          type: string
        likelihood:
          type: string
        key_metrics:
          type: string
        current_values:
          type: string
        threshold:
          type: string
        model_id:
          type: integer
          nullable: true
          description: ID of the model inventory entry this risk is linked to.
        is_demo:
          type: boolean
          default: false
    ModelRiskResponse:
      type: object
      properties:
        id:
          type: integer
        risk_name:
          type: string
        risk_category:
          type: string
          enum: [Performance, Bias & Fairness, Security, Data Quality, Compliance]
        risk_level:
          type: string
          enum: [Low, Medium, High, Critical]
        status:
          type: string
          enum: [Open, In Progress, Resolved, Accepted]
        owner:
          type: string
        target_date:
          type: string
          format: date
        description:
          type: string
        mitigation_plan:
          type: string
        impact:
          type: string
        likelihood:
          type: string
        key_metrics:
          type: string
        current_values:
          type: string
        threshold:
          type: string
        model_id:
          type: integer
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    SuccessResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          description: Response payload (type varies per endpoint)

    ValidationErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          example: Dataset creation validation failed
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
              code:
                type: string

    # ─── Evidence Hub ──────────────────────────────────────────────────────────

    Evidence:
      type: object
      properties:
        id:
          type: integer
        evidence_name:
          type: string
        evidence_type:
          type: string
        description:
          type: string
          nullable: true
        evidence_files:
          type: array
          items:
            $ref: "#/components/schemas/FileResponse"
        expiry_date:
          type: string
          format: date-time
          nullable: true
        mapped_model_ids:
          type: array
          items:
            type: integer
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    FileResponse:
      type: object
      properties:
        id:
          oneOf:
            - type: string
            - type: integer
        filename:
          type: string
        size:
          oneOf:
            - type: number
            - type: string
        mimetype:
          type: string
        uploaded_by:
          type: integer
        upload_date:
          type: string

    EvidenceCreateRequest:
      type: object
      required:
        - evidence_name
        - evidence_type
      properties:
        evidence_name:
          type: string
          maxLength: 255
        evidence_type:
          type: string
          maxLength: 100
        description:
          type: string
          nullable: true
        evidence_files:
          type: array
          items:
            type: object
            properties:
              id:
                oneOf:
                  - type: string
                  - type: integer
          description: Array of file references (by ID) to link
        expiry_date:
          type: string
          format: date-time
          nullable: true
        mapped_model_ids:
          type: array
          items:
            type: integer
          description: Model inventory IDs to map this evidence to

    EvidenceUpdateRequest:
      type: object
      properties:
        evidence_name:
          type: string
          maxLength: 255
        evidence_type:
          type: string
          maxLength: 100
        description:
          type: string
          nullable: true
        evidence_files:
          type: array
          items:
            type: object
            properties:
              id:
                oneOf:
                  - type: string
                  - type: integer
          description: New files to link
        deleteFiles:
          type: array
          items:
            oneOf:
              - type: string
              - type: integer
          description: File IDs to unlink
        expiry_date:
          type: string
          format: date-time
          nullable: true
        mapped_model_ids:
          type: array
          items:
            type: integer

    # ─── Datasets ──────────────────────────────────────────────────────────────

    Dataset:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        version:
          type: string
        owner:
          type: string
        type:
          type: string
          enum: [training, validation, testing, production, reference, synthetic]
        function:
          type: string
        source:
          type: string
        license:
          type: string
          nullable: true
        format:
          type: string
          nullable: true
        classification:
          type: string
          enum: [public, internal, confidential, restricted]
        contains_pii:
          type: boolean
        pii_types:
          type: string
          nullable: true
        status:
          type: string
          enum: [draft, active, deprecated, archived]
        status_date:
          type: string
          format: date-time
        known_biases:
          type: string
          nullable: true
        bias_mitigation:
          type: string
          nullable: true
        collection_method:
          type: string
          nullable: true
        preprocessing_steps:
          type: string
          nullable: true
        documentation_data:
          type: array
          items:
            $ref: "#/components/schemas/DocumentationFile"
        is_demo:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        models:
          type: array
          items:
            type: integer
          description: Related model inventory IDs
        projects:
          type: array
          items:
            type: integer
          description: Related project IDs

    DocumentationFile:
      type: object
      description: File metadata stored in JSONB documentation_data column
      properties:
        id:
          type: string
        filename:
          type: string
        size:
          type: number
        mimetype:
          type: string

    DatasetCreateRequest:
      type: object
      required:
        - name
        - description
        - version
        - owner
        - type
        - function
        - source
        - classification
        - contains_pii
        - status
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type: string
        version:
          type: string
          maxLength: 50
        owner:
          type: string
          maxLength: 255
        type:
          type: string
          enum: [training, validation, testing, production, reference, synthetic]
        function:
          type: string
        source:
          type: string
          maxLength: 255
        license:
          type: string
          maxLength: 255
        format:
          type: string
          maxLength: 100
        classification:
          type: string
          enum: [public, internal, confidential, restricted]
        contains_pii:
          type: boolean
        pii_types:
          type: string
        status:
          type: string
          enum: [draft, active, deprecated, archived]
        status_date:
          type: string
          format: date-time
          description: Defaults to current time if omitted
        known_biases:
          type: string
        bias_mitigation:
          type: string
        collection_method:
          type: string
        preprocessing_steps:
          type: string
        documentation_data:
          type: array
          items:
            $ref: "#/components/schemas/DocumentationFile"
        is_demo:
          type: boolean
          default: false
        models:
          type: array
          items:
            type: integer
          description: Model inventory IDs to associate
        projects:
          type: array
          items:
            type: integer
          description: Project IDs to associate

    DatasetUpdateRequest:
      type: object
      description: All fields optional. Only provided fields are updated.
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type: string
        version:
          type: string
          maxLength: 50
        owner:
          type: string
          maxLength: 255
        type:
          type: string
          enum: [training, validation, testing, production, reference, synthetic]
        function:
          type: string
        source:
          type: string
          maxLength: 255
        license:
          type: string
          maxLength: 255
        format:
          type: string
          maxLength: 100
        classification:
          type: string
          enum: [public, internal, confidential, restricted]
        contains_pii:
          type: boolean
        pii_types:
          type: string
        status:
          type: string
          enum: [draft, active, deprecated, archived]
        status_date:
          type: string
          format: date-time
        known_biases:
          type: string
        bias_mitigation:
          type: string
        collection_method:
          type: string
        preprocessing_steps:
          type: string
        documentation_data:
          type: array
          items:
            $ref: "#/components/schemas/DocumentationFile"
        is_demo:
          type: boolean
        models:
          type: array
          items:
            type: integer
          description: Replace model associations (provide full list)
        projects:
          type: array
          items:
            type: integer
          description: Replace project associations (provide full list)
        deleteModels:
          type: boolean
          description: If true, remove all model associations (even if models array is empty)
        deleteProjects:
          type: boolean
          description: If true, remove all project associations (even if projects array is empty)

    DatasetChangeHistoryEntry:
      type: object
      properties:
        id:
          type: integer
        dataset_id:
          type: integer
        change_type:
          type: string
          description: "e.g. created, deleted, field_change"
        field_name:
          type: string
          nullable: true
        old_value:
          type: string
          nullable: true
        new_value:
          type: string
          nullable: true
        changed_by:
          type: integer
          nullable: true
        created_at:
          type: string
          format: date-time

    # ─── Automations ───────────────────────────────────────────────────────────

    AutomationTrigger:
      type: object
      properties:
        id:
          type: integer
        key:
          type: string
          description: Machine-readable trigger identifier
        label:
          type: string
          description: Human-readable name
        event_name:
          type: string
        description:
          type: string
          nullable: true

    AutomationAction:
      type: object
      properties:
        id:
          type: integer
        key:
          type: string
          description: Machine-readable action identifier
        label:
          type: string
          description: Human-readable name
        description:
          type: string
          nullable: true
        default_params:
          type: object
          nullable: true
          description: Default parameters for this action type

    Automation:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        trigger_id:
          type: integer
        params:
          type: object
          description: Trigger-specific parameters (JSON)
        is_active:
          type: boolean
        created_by:
          type: integer
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    AutomationWithActions:
      allOf:
        - $ref: "#/components/schemas/Automation"
        - type: object
          properties:
            actions:
              type: array
              items:
                $ref: "#/components/schemas/TenantAutomationAction"

    TenantAutomationAction:
      type: object
      properties:
        id:
          type: integer
        automation_id:
          type: integer
        action_type_id:
          type: integer
        params:
          type: object
          nullable: true
          description: Action-specific parameters (JSON)
        order:
          type: integer
          description: Execution order (1-based)

    AutomationCreateRequest:
      type: object
      required:
        - triggerId
        - name
        - actions
      properties:
        triggerId:
          type: integer
          description: ID of the automation trigger
        name:
          type: string
          description: Automation name
        params:
          type: string
          description: JSON-encoded trigger parameters (parsed server-side)
          default: "{}"
        actions:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - action_type_id
            properties:
              action_type_id:
                type: integer
                description: ID of the action type
              params:
                type: object
                nullable: true
                description: Action-specific parameters

    AutomationUpdateRequest:
      type: object
      properties:
        name:
          type: string
        triggerId:
          type: integer
        params:
          type: string
          description: JSON-encoded trigger parameters
          default: "{}"
        is_active:
          type: boolean
        actions:
          type: array
          items:
            type: object
            required:
              - action_type_id
            properties:
              action_type_id:
                type: integer
              params:
                type: object
                nullable: true
          description: If provided, replaces all existing actions

    AutomationHistoryResponse:
      type: object
      properties:
        logs:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              automation_id:
                type: integer
              status:
                type: string
              triggered_at:
                type: string
                format: date-time
              completed_at:
                type: string
                format: date-time
                nullable: true
              actions:
                type: array
                items:
                  type: object
                description: Per-action execution results
        total:
          type: integer
          description: Total number of log entries
        limit:
          type: integer
        offset:
          type: integer

    AutomationStats:
      type: object
      description: Aggregated execution statistics for an automation
      properties:
        total_executions:
          type: integer
        successful:
          type: integer
        failed:
          type: integer
        last_executed_at:
          type: string
          format: date-time
    # =========================================================================
    # Common
    # =========================================================================

    ApiResponse:
      type: object
      properties:
        statusCode:
          type: integer
        data:
          description: Response payload (varies by endpoint)

    Pagination:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
        total_pages:
          type: integer

    # =========================================================================
    # AI Detection - Enums
    # =========================================================================

    ScanStatus:
      type: string
      enum: [pending, cloning, scanning, completed, failed, cancelled]

    ScanMode:
      type: string
      enum: [full, incremental]

    FindingStatus:
      type: string
      enum: [active, fixed, carried_forward]

    FindingType:
      type: string
      enum:
        - library
        - dependency
        - api_call
        - secret
        - model_ref
        - rag_component
        - agent
        - prompt_injection
        - pii_exposure
        - excessive_agency
        - jailbreak_risk
        - training_data_poisoning
        - model_dos
        - supply_chain
        - insecure_plugin
        - overreliance
        - model_theft

    ConfidenceLevel:
      type: string
      enum: [high, medium, low]

    RiskLevel:
      type: string
      enum: [high, medium, low]

    GovernanceStatus:
      type: string
      enum: [reviewed, approved, flagged]
      nullable: true

    LicenseRiskLevel:
      type: string
      enum: [high, medium, low, unknown]

    # =========================================================================
    # AI Detection - Scan Schemas
    # =========================================================================

    StartScanRequest:
      type: object
      required: [repository_url]
      properties:
        repository_url:
          type: string
          description: GitHub repository URL
          example: https://github.com/owner/repo
        scan_mode:
          $ref: '#/components/schemas/ScanMode'
        base_commit_sha:
          type: string
          pattern: '^[0-9a-fA-F]{7,40}$'
          description: Required for incremental scans
        head_commit_sha:
          type: string
          pattern: '^[0-9a-fA-F]{7,40}$'
          description: Required for incremental scans

    ScanStatusResponse:
      type: object
      properties:
        id:
          type: integer
        status:
          $ref: '#/components/schemas/ScanStatus'
        progress:
          type: number
          format: float
        current_file:
          type: string
        files_scanned:
          type: integer
        total_files:
          type: integer
          nullable: true
        findings_count:
          type: integer
        error_message:
          type: string
          nullable: true

    TriggeredByUser:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        surname:
          type: string

    ScanResponse:
      type: object
      properties:
        scan:
          type: object
          properties:
            id:
              type: integer
            repository_url:
              type: string
            repository_owner:
              type: string
            repository_name:
              type: string
            status:
              $ref: '#/components/schemas/ScanStatus'
            findings_count:
              type: integer
            files_scanned:
              type: integer
            started_at:
              type: string
              format: date-time
              nullable: true
            completed_at:
              type: string
              format: date-time
              nullable: true
            duration_ms:
              type: integer
              nullable: true
            error_message:
              type: string
              nullable: true
            triggered_by:
              $ref: '#/components/schemas/TriggeredByUser'
            risk_score:
              type: number
              nullable: true
            risk_score_grade:
              type: string
              nullable: true
            risk_score_details:
              type: object
              nullable: true
            risk_score_calculated_at:
              type: string
              format: date-time
              nullable: true
            scan_mode:
              $ref: '#/components/schemas/ScanMode'
            base_commit_sha:
              type: string
              nullable: true
            head_commit_sha:
              type: string
              nullable: true
            baseline_scan_id:
              type: integer
              nullable: true
            changed_files_count:
              type: integer
              nullable: true
            created_at:
              type: string
              format: date-time
        summary:
          $ref: '#/components/schemas/ScanSummary'

    ScanSummary:
      type: object
      properties:
        total:
          type: integer
        by_confidence:
          type: object
          properties:
            high:
              type: integer
            medium:
              type: integer
            low:
              type: integer
        by_provider:
          type: object
          additionalProperties:
            type: integer

    ScanListItem:
      type: object
      properties:
        id:
          type: integer
        repository_url:
          type: string
        repository_owner:
          type: string
        repository_name:
          type: string
        status:
          $ref: '#/components/schemas/ScanStatus'
        findings_count:
          type: integer
        files_scanned:
          type: integer
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        duration_ms:
          type: integer
          nullable: true
        triggered_by:
          $ref: '#/components/schemas/TriggeredByUser'
        risk_score:
          type: number
          nullable: true
        risk_score_grade:
          type: string
          nullable: true
        scan_mode:
          $ref: '#/components/schemas/ScanMode'
        baseline_scan_id:
          type: integer
          nullable: true
        changed_files_count:
          type: integer
          nullable: true
        created_at:
          type: string
          format: date-time

    ScansResponse:
      type: object
      properties:
        scans:
          type: array
          items:
            $ref: '#/components/schemas/ScanListItem'
        pagination:
          $ref: '#/components/schemas/Pagination'

    CancelScanResponse:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string
          enum: [cancelled]
        message:
          type: string

    DeleteScanResponse:
      type: object
      properties:
        message:
          type: string

    # =========================================================================
    # AI Detection - Finding Schemas
    # =========================================================================

    FilePath:
      type: object
      properties:
        path:
          type: string
        line_number:
          type: integer
          nullable: true
        matched_text:
          type: string

    Finding:
      type: object
      properties:
        id:
          type: integer
        finding_type:
          $ref: '#/components/schemas/FindingType'
        category:
          type: string
        name:
          type: string
        provider:
          type: string
        confidence:
          $ref: '#/components/schemas/ConfidenceLevel'
        risk_level:
          $ref: '#/components/schemas/RiskLevel'
        description:
          type: string
          nullable: true
        documentation_url:
          type: string
          nullable: true
        file_count:
          type: integer
        file_paths:
          type: array
          items:
            $ref: '#/components/schemas/FilePath'
        governance_status:
          $ref: '#/components/schemas/GovernanceStatus'
        governance_updated_at:
          type: string
          format: date-time
          nullable: true
        governance_updated_by:
          type: integer
          nullable: true
        license_id:
          type: string
          nullable: true
        license_name:
          type: string
          nullable: true
        license_risk:
          $ref: '#/components/schemas/LicenseRiskLevel'
        license_source:
          type: string
          enum: [package, huggingface, pypi, npm, manual]
          nullable: true
        mitigation:
          type: string
          nullable: true
        data_flow_summary:
          type: string
          nullable: true
        vulnerability_details:
          type: object
          nullable: true
        finding_status:
          $ref: '#/components/schemas/FindingStatus'

    FindingsResponse:
      type: object
      properties:
        findings:
          type: array
          items:
            $ref: '#/components/schemas/Finding'
        pagination:
          $ref: '#/components/schemas/Pagination'

    UpdateGovernanceStatusRequest:
      type: object
      properties:
        governance_status:
          type: string
          enum: [reviewed, approved, flagged]
          nullable: true
          description: Set to null to clear governance status

    UpdateGovernanceStatusResponse:
      type: object
      properties:
        id:
          type: integer
        governance_status:
          type: string
          nullable: true
        governance_updated_at:
          type: string
          format: date-time
        governance_updated_by:
          type: integer

    # =========================================================================
    # AI Detection - Risk Scoring
    # =========================================================================

    RiskScoreResponse:
      type: object
      properties:
        score:
          type: number
          nullable: true
        grade:
          type: string
          nullable: true
        details:
          type: object
          nullable: true
        calculated_at:
          type: string
          format: date-time
          nullable: true

    DimensionWeights:
      type: object
      properties:
        data_sovereignty:
          type: number
          minimum: 0
          maximum: 1
        transparency:
          type: number
          minimum: 0
          maximum: 1
        security:
          type: number
          minimum: 0
          maximum: 1
        autonomy:
          type: number
          minimum: 0
          maximum: 1
        supply_chain:
          type: number
          minimum: 0
          maximum: 1
      description: All values must sum to 1.0

    VulnerabilityTypesEnabled:
      type: object
      properties:
        prompt_injection:
          type: boolean
        pii_exposure:
          type: boolean
        excessive_agency:
          type: boolean
        jailbreak_risk:
          type: boolean
        training_data_poisoning:
          type: boolean
        model_dos:
          type: boolean
        supply_chain:
          type: boolean
        insecure_plugin:
          type: boolean
        overreliance:
          type: boolean
        model_theft:
          type: boolean

    RiskScoringConfig:
      type: object
      properties:
        id:
          type: integer
          nullable: true
        llm_enabled:
          type: boolean
        llm_key_id:
          type: integer
          nullable: true
        dimension_weights:
          $ref: '#/components/schemas/DimensionWeights'
        vulnerability_scan_enabled:
          type: boolean
        vulnerability_types_enabled:
          $ref: '#/components/schemas/VulnerabilityTypesEnabled'
        updated_by:
          type: integer
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true

    UpdateRiskScoringConfigRequest:
      type: object
      properties:
        llm_enabled:
          type: boolean
        llm_key_id:
          type: integer
          nullable: true
        dimension_weights:
          $ref: '#/components/schemas/DimensionWeights'
        vulnerability_scan_enabled:
          type: boolean
        vulnerability_types_enabled:
          $ref: '#/components/schemas/VulnerabilityTypesEnabled'

    # =========================================================================
    # AI Detection - Dependency Graph & Compliance
    # =========================================================================

    DependencyGraphResponse:
      type: object
      properties:
        nodes:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              label:
                type: string
              type:
                type: string
              metadata:
                type: object
        edges:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              target:
                type: string
              relationship:
                type: string
        metadata:
          type: object

    ComplianceMappingResponse:
      type: object
      properties:
        mappings:
          type: array
          items:
            type: object
        checklist:
          type: array
          items:
            type: object
        summary:
          type: object

    # =========================================================================
    # AI Detection - Repository Schemas
    # =========================================================================

    Repository:
      type: object
      properties:
        id:
          type: integer
        repository_url:
          type: string
        repository_owner:
          type: string
        repository_name:
          type: string
        display_name:
          type: string
          nullable: true
        default_branch:
          type: string
        github_token_id:
          type: integer
          nullable: true
        schedule_enabled:
          type: boolean
        schedule_frequency:
          type: string
          enum: [daily, weekly, monthly]
          nullable: true
        schedule_day_of_week:
          type: integer
          minimum: 0
          maximum: 6
          nullable: true
        schedule_day_of_month:
          type: integer
          minimum: 1
          maximum: 31
          nullable: true
        schedule_hour:
          type: integer
          minimum: 0
          maximum: 23
        schedule_minute:
          type: integer
          minimum: 0
          maximum: 59
        webhook_secret:
          type: string
          nullable: true
        ci_enabled:
          type: boolean
        ci_min_score:
          type: number
        ci_max_critical:
          type: integer
        ci_post_comments:
          type: boolean
        ci_status_checks:
          type: boolean
        last_scan_id:
          type: integer
          nullable: true
        last_scan_status:
          type: string
          nullable: true
        last_scan_at:
          type: string
          format: date-time
          nullable: true
        next_scan_at:
          type: string
          format: date-time
          nullable: true
        is_enabled:
          type: boolean
        created_by:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateRepositoryRequest:
      type: object
      required: [repository_url]
      properties:
        repository_url:
          type: string
          description: GitHub repository URL
          example: https://github.com/owner/repo
        display_name:
          type: string
          nullable: true
        default_branch:
          type: string
          default: main
        github_token_id:
          type: integer
          nullable: true
        schedule_enabled:
          type: boolean
          default: false
        schedule_frequency:
          type: string
          enum: [daily, weekly, monthly]
          description: Required when schedule_enabled is true
        schedule_day_of_week:
          type: integer
          minimum: 0
          maximum: 6
          description: Required for weekly schedule (0=Sunday)
        schedule_day_of_month:
          type: integer
          minimum: 1
          maximum: 31
          description: Required for monthly schedule
        schedule_hour:
          type: integer
          minimum: 0
          maximum: 23
          default: 2
        schedule_minute:
          type: integer
          minimum: 0
          maximum: 59
          default: 0

    UpdateRepositoryRequest:
      type: object
      properties:
        display_name:
          type: string
          nullable: true
        default_branch:
          type: string
        github_token_id:
          type: integer
          nullable: true
        schedule_enabled:
          type: boolean
        schedule_frequency:
          type: string
          enum: [daily, weekly, monthly]
        schedule_day_of_week:
          type: integer
          minimum: 0
          maximum: 6
        schedule_day_of_month:
          type: integer
          minimum: 1
          maximum: 31
        schedule_hour:
          type: integer
          minimum: 0
          maximum: 23
        schedule_minute:
          type: integer
          minimum: 0
          maximum: 59
        is_enabled:
          type: boolean
        ci_enabled:
          type: boolean
        ci_min_score:
          type: number
        ci_max_critical:
          type: integer
        ci_post_comments:
          type: boolean
        ci_status_checks:
          type: boolean

    RepositoryListResponse:
      type: object
      properties:
        repositories:
          type: array
          items:
            $ref: '#/components/schemas/Repository'
        pagination:
          $ref: '#/components/schemas/Pagination'

    # =========================================================================
    # AI Trust Centre Schemas
    # =========================================================================

    AITrustCentreOverview:
      type: object
      description: Full overview with all sections
      properties:
        intro:
          type: object
          properties:
            id:
              type: integer
            purpose_visible:
              type: boolean
            purpose_text:
              type: string
            our_statement_visible:
              type: boolean
            our_statement_text:
              type: string
            our_mission_visible:
              type: boolean
            our_mission_text:
              type: string
        compliance_badges:
          type: object
          properties:
            id:
              type: integer
            soc2_type_i:
              type: boolean
            soc2_type_ii:
              type: boolean
            iso_27001:
              type: boolean
            iso_42001:
              type: boolean
            ccpa:
              type: boolean
            gdpr:
              type: boolean
            hipaa:
              type: boolean
            eu_ai_act:
              type: boolean
        company_description:
          type: object
          properties:
            id:
              type: integer
            background_visible:
              type: boolean
            background_text:
              type: string
            core_benefits_visible:
              type: boolean
            core_benefits_text:
              type: string
            compliance_doc_visible:
              type: boolean
            compliance_doc_text:
              type: string
        terms_and_contact:
          type: object
          properties:
            id:
              type: integer
            terms_visible:
              type: boolean
            terms_text:
              type: string
            privacy_visible:
              type: boolean
            privacy_text:
              type: string
            email_visible:
              type: boolean
            email_text:
              type: string
        info:
          type: object
          properties:
            id:
              type: integer
            title:
              type: string
            header_color:
              type: string
            visible:
              type: boolean
            intro_visible:
              type: boolean
            compliance_badges_visible:
              type: boolean
            company_description_visible:
              type: boolean
            terms_and_contact_visible:
              type: boolean
            resources_visible:
              type: boolean
            subprocessor_visible:
              type: boolean
            updated_at:
              type: string
              format: date-time

    AITrustCentreResource:
      type: object
      properties:
        id:
          type: integer
        organization_id:
          type: integer
        name:
          type: string
        description:
          type: string
        file_id:
          type: integer
        visible:
          type: boolean
        filename:
          type: string

    AITrustCentreSubprocessor:
      type: object
      properties:
        id:
          type: integer
        organization_id:
          type: integer
        name:
          type: string
        purpose:
          type: string
        location:
          type: string
        url:
          type: string

    CreateSubprocessorRequest:
      type: object
      required: [name, purpose, location]
      properties:
        name:
          type: string
        purpose:
          type: string
        location:
          type: string
        url:
          type: string

    UpdateSubprocessorRequest:
      type: object
      properties:
        name:
          type: string
        purpose:
          type: string
        location:
          type: string
        url:
          type: string

    AITrustCentrePublicPage:
      type: object
      description: Conditionally includes sections based on visibility settings
      properties:
        info:
          type: object
          properties:
            title:
              type: string
            header_color:
              type: string
            logo:
              type: integer
              nullable: true
        intro:
          type: object
          nullable: true
          properties:
            purpose:
              type: string
              nullable: true
            statement:
              type: string
              nullable: true
            mission:
              type: string
              nullable: true
        compliance_badges:
          type: object
          nullable: true
          properties:
            soc2_type_i:
              type: boolean
            soc2_type_ii:
              type: boolean
            iso_27001:
              type: boolean
            iso_42001:
              type: boolean
            ccpa:
              type: boolean
            gdpr:
              type: boolean
            hipaa:
              type: boolean
            eu_ai_act:
              type: boolean
        company_description:
          type: object
          nullable: true
          properties:
            background:
              type: string
              nullable: true
            core_benefits:
              type: string
              nullable: true
            compliance_doc:
              type: string
              nullable: true
        terms_and_contact:
          type: object
          nullable: true
          properties:
            terms:
              type: string
              nullable: true
            privacy:
              type: string
              nullable: true
            email:
              type: string
              nullable: true
        resources:
          type: array
          nullable: true
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              description:
                type: string
              file_id:
                type: integer
              visible:
                type: boolean
        subprocessors:
          type: array
          nullable: true
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              purpose:
                type: string
              location:
                type: string
              url:
                type: string

    # =========================================================================
    # AI Incident Management Schemas
    # =========================================================================

    IncidentType:
      type: string
      enum:
        - Malfunction
        - Unexpected behavior
        - Model drift
        - Misuse
        - Data corruption
        - Security breach
        - Performance degradation

    IncidentSeverity:
      type: string
      enum:
        - Minor
        - Serious
        - Very serious

    IncidentStatus:
      type: string
      enum:
        - Open
        - Investigating
        - Mitigated
        - Closed

    IncidentApprovalStatus:
      type: string
      enum:
        - Approved
        - Rejected
        - Pending
        - Not required

    Incident:
      type: object
      properties:
        id:
          type: integer
        incident_id:
          type: string
          nullable: true
        ai_project:
          type: string
        type:
          $ref: '#/components/schemas/IncidentType'
        severity:
          $ref: '#/components/schemas/IncidentSeverity'
        status:
          $ref: '#/components/schemas/IncidentStatus'
        occurred_date:
          type: string
          format: date-time
        date_detected:
          type: string
          format: date-time
        reporter:
          type: string
        categories_of_harm:
          type: array
          items:
            type: string
        affected_persons_groups:
          type: string
          nullable: true
        description:
          type: string
        relationship_causality:
          type: string
          nullable: true
        immediate_mitigations:
          type: string
          nullable: true
        planned_corrective_actions:
          type: string
          nullable: true
        model_system_version:
          type: string
          nullable: true
        interim_report:
          type: boolean
        archived:
          type: boolean
        approval_status:
          $ref: '#/components/schemas/IncidentApprovalStatus'
        approved_by:
          type: string
          nullable: true
        approval_date:
          type: string
          format: date-time
          nullable: true
        approval_notes:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateIncidentRequest:
      type: object
      required:
        - ai_project
        - type
        - severity
        - status
        - occurred_date
        - date_detected
        - reporter
        - approval_status
        - categories_of_harm
        - description
        - relationship_causality
      properties:
        ai_project:
          type: string
        type:
          $ref: '#/components/schemas/IncidentType'
        severity:
          $ref: '#/components/schemas/IncidentSeverity'
        status:
          $ref: '#/components/schemas/IncidentStatus'
        occurred_date:
          type: string
          format: date-time
        date_detected:
          type: string
          format: date-time
        reporter:
          type: string
        approval_status:
          $ref: '#/components/schemas/IncidentApprovalStatus'
        approved_by:
          type: string
        categories_of_harm:
          oneOf:
            - type: array
              items:
                type: string
            - type: string
              description: Comma-separated string (will be split)
        affected_persons_groups:
          type: string
        description:
          type: string
        relationship_causality:
          type: string
        immediate_mitigations:
          type: string
        planned_corrective_actions:
          type: string
        model_system_version:
          type: string
        interim_report:
          type: boolean
          default: false
        archived:
          type: boolean
          default: false
        approval_date:
          type: string
          format: date-time
        approval_notes:
          type: string

    UpdateIncidentRequest:
      type: object
      description: All fields are optional; only provided fields are updated.
      properties:
        ai_project:
          type: string
        type:
          $ref: '#/components/schemas/IncidentType'
        severity:
          $ref: '#/components/schemas/IncidentSeverity'
        status:
          $ref: '#/components/schemas/IncidentStatus'
        occurred_date:
          type: string
          format: date-time
        date_detected:
          type: string
          format: date-time
        reporter:
          type: string
        approval_status:
          $ref: '#/components/schemas/IncidentApprovalStatus'
        approved_by:
          type: string
        categories_of_harm:
          oneOf:
            - type: array
              items:
                type: string
            - type: string
        affected_persons_groups:
          type: string
        description:
          type: string
        relationship_causality:
          type: string
        immediate_mitigations:
          type: string
        planned_corrective_actions:
          type: string
        model_system_version:
          type: string
        interim_report:
          type: boolean
        archived:
          type: boolean
        approval_date:
          type: string
          format: date-time
        approval_notes:
          type: string
    # ---- Generic response wrappers ----

    Framework:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        organization_id:
          type: integer

    # ---- ISO 27001 ----

    ISO27001Clause:
      type: object
      properties:
        id:
          type: integer
        arrangement:
          type: integer
        title:
          type: string

    ISO27001ClauseWithSubClauses:
      type: object
      properties:
        id:
          type: integer
        arrangement:
          type: integer
        title:
          type: string
        subClauses:
          type: array
          items:
            $ref: "#/components/schemas/ISO27001SubClause"

    ISO27001SubClause:
      type: object
      properties:
        id:
          type: integer
        subclause_meta_id:
          type: integer
        projects_frameworks_id:
          type: integer
        organization_id:
          type: integer
        status:
          type: string
          enum: [Not started, Draft, In review, Done]
        owner:
          type: integer
          nullable: true
        reviewer:
          type: integer
          nullable: true
        approver:
          type: integer
          nullable: true
        implementation_details:
          type: string
          nullable: true
        evidence_links:
          type: array
          items:
            type: object
        risks_mitigated:
          type: array
          items:
            type: integer
        tags:
          type: array
          items:
            type: string

    ISO27001Annex:
      type: object
      properties:
        id:
          type: integer
        arrangement:
          type: string
        order_no:
          type: integer
        title:
          type: string

    ISO27001AnnexWithControls:
      type: object
      properties:
        id:
          type: integer
        arrangement:
          type: string
        order_no:
          type: integer
        title:
          type: string
        controls:
          type: array
          items:
            $ref: "#/components/schemas/ISO27001AnnexControl"

    ISO27001AnnexControl:
      type: object
      properties:
        id:
          type: integer
        annexcontrol_meta_id:
          type: integer
        projects_frameworks_id:
          type: integer
        organization_id:
          type: integer
        status:
          type: string
          enum: [Not started, Draft, In review, Done]
        owner:
          type: integer
          nullable: true
        reviewer:
          type: integer
          nullable: true
        approver:
          type: integer
          nullable: true
        implementation_details:
          type: string
          nullable: true
        evidence_links:
          type: array
          items:
            type: object
        risks_mitigated:
          type: array
          items:
            type: integer
        tags:
          type: array
          items:
            type: string

    ISO27001SaveClauseRequest:
      type: object
      properties:
        user_id:
          type: string
          description: User ID for file upload attribution
        project_id:
          type: string
          description: Project ID for file upload association
        status:
          type: string
          enum: [Not started, Draft, In review, Done]
        owner:
          type: integer
          nullable: true
        reviewer:
          type: integer
          nullable: true
        approver:
          type: integer
          nullable: true
        implementation_details:
          type: string
        tags:
          type: string
          description: JSON-encoded array of tag strings
        delete:
          type: string
          description: JSON-encoded array of file IDs to unlink
        risksDelete:
          type: string
          description: JSON-encoded array of risk IDs to remove
        risksMitigated:
          type: string
          description: JSON-encoded array of risk IDs to add
        files:
          type: array
          items:
            type: string
            format: binary
          description: Evidence files to upload

    ISO27001SaveAnnexRequest:
      type: object
      properties:
        user_id:
          type: string
          description: User ID for file upload attribution
        project_id:
          type: string
          description: Project ID for file upload association
        status:
          type: string
          enum: [Not started, Draft, In review, Done]
        owner:
          type: integer
          nullable: true
        reviewer:
          type: integer
          nullable: true
        approver:
          type: integer
          nullable: true
        implementation_details:
          type: string
        tags:
          type: string
          description: JSON-encoded array of tag strings
        delete:
          type: string
          description: JSON-encoded array of file IDs to unlink
        risksDelete:
          type: string
          description: JSON-encoded array of risk IDs to remove
        risksMitigated:
          type: string
          description: JSON-encoded array of risk IDs to add
        files:
          type: array
          items:
            type: string
            format: binary
          description: Evidence files to upload

    # ---- ISO 42001 ----

    ISO42001Clause:
      type: object
      properties:
        id:
          type: integer
        clause_no:
          type: integer
        title:
          type: string

    ISO42001ClauseWithSubClauses:
      type: object
      properties:
        id:
          type: integer
        clause_no:
          type: integer
        title:
          type: string
        subClauses:
          type: array
          items:
            $ref: "#/components/schemas/ISO42001SubClause"

    ISO42001SubClause:
      type: object
      properties:
        id:
          type: integer
        subclause_meta_id:
          type: integer
        projects_frameworks_id:
          type: integer
        organization_id:
          type: integer
        status:
          type: string
          enum: [Not started, Draft, In review, Done]
        owner:
          type: integer
          nullable: true
        reviewer:
          type: integer
          nullable: true
        approver:
          type: integer
          nullable: true
        implementation_details:
          type: string
          nullable: true
        evidence_links:
          type: array
          items:
            type: object
        risks_mitigated:
          type: array
          items:
            type: integer
        tags:
          type: array
          items:
            type: string

    ISO42001Annex:
      type: object
      properties:
        id:
          type: integer
        annex_no:
          type: integer
        title:
          type: string

    ISO42001AnnexWithCategories:
      type: object
      properties:
        id:
          type: integer
        annex_no:
          type: integer
        title:
          type: string
        categories:
          type: array
          items:
            $ref: "#/components/schemas/ISO42001AnnexCategory"

    ISO42001AnnexCategory:
      type: object
      properties:
        id:
          type: integer
        annexcategory_meta_id:
          type: integer
        projects_frameworks_id:
          type: integer
        organization_id:
          type: integer
        status:
          type: string
          enum: [Not started, Draft, In review, Done]
        owner:
          type: integer
          nullable: true
        reviewer:
          type: integer
          nullable: true
        approver:
          type: integer
          nullable: true
        implementation_details:
          type: string
          nullable: true
        evidence_links:
          type: array
          items:
            type: object
        risks_mitigated:
          type: array
          items:
            type: integer
        tags:
          type: array
          items:
            type: string

    ISO42001SaveClauseRequest:
      type: object
      properties:
        user_id:
          type: string
        project_id:
          type: string
        status:
          type: string
          enum: [Not started, Draft, In review, Done]
        owner:
          type: integer
          nullable: true
        reviewer:
          type: integer
          nullable: true
        approver:
          type: integer
          nullable: true
        implementation_details:
          type: string
        tags:
          type: string
          description: JSON-encoded array of tag strings
        delete:
          type: string
          description: JSON-encoded array of file IDs to unlink
        risksDelete:
          type: string
          description: JSON-encoded array of risk IDs to remove
        risksMitigated:
          type: string
          description: JSON-encoded array of risk IDs to add
        files:
          type: array
          items:
            type: string
            format: binary

    ISO42001SaveAnnexRequest:
      type: object
      properties:
        user_id:
          type: string
        project_id:
          type: string
        status:
          type: string
          enum: [Not started, Draft, In review, Done]
        owner:
          type: integer
          nullable: true
        reviewer:
          type: integer
          nullable: true
        approver:
          type: integer
          nullable: true
        implementation_details:
          type: string
        tags:
          type: string
          description: JSON-encoded array of tag strings
        delete:
          type: string
          description: JSON-encoded array of file IDs to unlink
        risksDelete:
          type: string
          description: JSON-encoded array of risk IDs to remove
        risksMitigated:
          type: string
          description: JSON-encoded array of risk IDs to add
        files:
          type: array
          items:
            type: string
            format: binary

    # ---- NIST AI RMF ----

    NISTFunction:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
          example: GOVERN
        description:
          type: string
        organization_id:
          type: integer

    NISTCategory:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        description:
          type: string
        function_id:
          type: integer
        organization_id:
          type: integer

    NISTSubcategory:
      type: object
      properties:
        id:
          type: integer
        subcategory_meta_id:
          type: integer
        organization_id:
          type: integer
        status:
          type: string
          enum: [Not started, Draft, In review, Done]
        owner:
          type: integer
          nullable: true
        reviewer:
          type: integer
          nullable: true
        approver:
          type: integer
          nullable: true
        implementation_details:
          type: string
          nullable: true
        evidence_links:
          type: array
          items:
            type: object
        risks_mitigated:
          type: array
          items:
            type: integer
        tags:
          type: array
          items:
            type: string

    NISTSubcategoryUpdateRequest:
      type: object
      properties:
        user_id:
          type: string
          description: User ID for file upload attribution
        project_id:
          type: string
          description: Project ID for file upload association
        status:
          type: string
          enum: [Not started, Draft, In review, Done]
        owner:
          type: integer
          nullable: true
        reviewer:
          type: integer
          nullable: true
        approver:
          type: integer
          nullable: true
        implementation_details:
          type: string
        tags:
          type: string
          description: JSON-encoded array of tag strings
        delete:
          type: string
          description: JSON-encoded array of file IDs to unlink
        risksDelete:
          type: string
          description: JSON-encoded array of risk IDs to remove
        risksMitigated:
          type: string
          description: JSON-encoded array of risk IDs to add
        files:
          type: array
          items:
            type: string
            format: binary
          description: Evidence files to upload

    NISTSubcategoryStatusUpdate:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum: [Not started, Draft, In review, Done]
          description: New status value

    NISTProgress:
      type: object
      properties:
        totalSubcategories:
          type: integer
        doneSubcategories:
          type: integer

    NISTAssignments:
      type: object
      properties:
        totalSubcategories:
          type: integer
        assignedSubcategories:
          type: integer

    # ---- Compliance Score ----

    ComplianceScore:
      type: object
      properties:
        organizationId:
          type: integer
        overallScore:
          type: integer
          minimum: 0
          maximum: 100
        calculatedAt:
          type: string
          format: date-time
        modules:
          type: object
          properties:
            riskManagement:
              $ref: "#/components/schemas/ModuleScore"
            vendorManagement:
              $ref: "#/components/schemas/ModuleScore"
            projectGovernance:
              $ref: "#/components/schemas/ModuleScore"
            modelLifecycle:
              $ref: "#/components/schemas/ModuleScore"
            policyDocumentation:
              $ref: "#/components/schemas/ModuleScore"
        metadata:
          $ref: "#/components/schemas/ComplianceMetadata"

    ModuleScore:
      type: object
      properties:
        score:
          type: number
          minimum: 0
          maximum: 100
        weight:
          type: number
          description: Module weight (sums to 1.0 across all modules)
        components:
          type: array
          items:
            $ref: "#/components/schemas/ComponentScore"
        totalDataPoints:
          type: integer
        qualityScore:
          type: number
          minimum: 0
          maximum: 1
          description: Data completeness indicator

    ComponentScore:
      type: object
      properties:
        name:
          type: string
        score:
          type: number
        weight:
          type: number
        dataPoints:
          type: integer
        details:
          type: object
          description: Module-specific details

    ComplianceMetadata:
      type: object
      properties:
        totalProjects:
          type: integer
        applicableProjects:
          type: integer
        lastUpdated:
          type: string
          format: date-time
        dataFreshness:
          type: object
          properties:
            risks:
              type: string
              format: date-time
            vendors:
              type: string
              format: date-time
            projects:
              type: string
              format: date-time
            models:
              type: string
              format: date-time
            policies:
              type: string
              format: date-time
        calculationMethod:
          type: string
          enum: [balanced_weighted_average]
        version:
          type: string

    ComplianceDetails:
      allOf:
        - $ref: "#/components/schemas/ComplianceScore"
        - type: object
          properties:
            insights:
              type: object
              properties:
                strongestModule:
                  type: object
                  properties:
                    name:
                      type: string
                    score:
                      type: number
                weakestModule:
                  type: object
                  properties:
                    name:
                      type: string
                    score:
                      type: number
                improvementPriority:
                  type: array
                  items:
                    type: object
                    properties:
                      module:
                        type: string
                      score:
                        type: number
                      weight:
                        type: number
                      impact:
                        type: number
                        description: "(100 - score) * weight"
                overallTrend:
                  type: string
                  enum: [up, down, stable]
                dataQuality:
                  type: object
                  properties:
                    riskManagement:
                      type: number
                    vendorManagement:
                      type: number
                    projectGovernance:
                      type: number
                    modelLifecycle:
                      type: number
                    policyDocumentation:
                      type: number

    # ---- Shared ----

    AssignmentResponse:
      type: object
      properties:
        total:
          type: integer
        assigned:
          type: integer

    RisksResponse:
      type: object
      properties:
        message:
          type: string
        data:
          type: array
          items:
            $ref: "#/components/schemas/Risk"

    Risk:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        description:
          type: string
        risk_level:
          type: string
        status:
          type: string
        organization_id:
          type: integer
    # ─── Generic wrapper ────────────────────────────────────────────────────────

    StatusCodeWrapper:
      type: object
      properties:
        code:
          type: integer
        data:
          description: Response payload

    # ─── Share Links ────────────────────────────────────────────────────────────

    ShareLinkSettings:
      type: object
      properties:
        shareAllFields:
          type: boolean
          default: false
        allowDataExport:
          type: boolean
          default: true
        allowViewersToOpenRecords:
          type: boolean
          default: false
        displayToolbar:
          type: boolean
          default: true

    ShareLinkCreateRequest:
      type: object
      required: [resource_type, resource_id]
      properties:
        resource_type:
          type: string
          enum: [model, vendor, project, policy, risk]
        resource_id:
          type: integer
          minimum: 0
          description: Use 0 for sharing the entire table/list view
        settings:
          $ref: "#/components/schemas/ShareLinkSettings"
        expires_at:
          type: string
          format: date-time
          nullable: true

    ShareLinkUpdateRequest:
      type: object
      properties:
        settings:
          $ref: "#/components/schemas/ShareLinkSettings"
        is_enabled:
          type: boolean
        expires_at:
          type: string
          format: date-time
          nullable: true

    ShareLinkResponse:
      type: object
      properties:
        id:
          type: integer
        share_token:
          type: string
        resource_type:
          type: string
        resource_id:
          type: integer
        settings:
          $ref: "#/components/schemas/ShareLinkSettings"
        is_enabled:
          type: boolean
        expires_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        shareable_url:
          type: string
          format: uri

    ShareLinkListItem:
      allOf:
        - $ref: "#/components/schemas/ShareLinkResponse"
        - properties:
            is_valid:
              type: boolean
              description: Whether the link is currently active and not expired

    ShareLinkMetadata:
      type: object
      properties:
        id:
          type: integer
        share_token:
          type: string
        resource_type:
          type: string
        resource_id:
          type: integer
        settings:
          $ref: "#/components/schemas/ShareLinkSettings"
        is_enabled:
          type: boolean
        expires_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        is_valid:
          type: boolean

    SharedDataResponse:
      type: object
      properties:
        share_link:
          type: object
          properties:
            resource_type:
              type: string
            settings:
              $ref: "#/components/schemas/ShareLinkSettings"
        data:
          description: Resource data (object for single record, array for table view)
          oneOf:
            - type: object
            - type: array
              items:
                type: object
        permissions:
          type: object
          properties:
            allowDataExport:
              type: boolean
            allowViewersToOpenRecords:
              type: boolean

    # ─── Notes ──────────────────────────────────────────────────────────────────

    NoteCreateRequest:
      type: object
      required: [content, attached_to, attached_to_id]
      properties:
        content:
          type: string
          maxLength: 5000
        attached_to:
          type: string
          enum: [project, vendor, model, risk, policy, task, incident]
        attached_to_id:
          type: string

    Note:
      type: object
      properties:
        id:
          type: integer
        content:
          type: string
        author_id:
          type: integer
        attached_to:
          type: string
        attached_to_id:
          type: string
        organization_id:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    # ─── Search ─────────────────────────────────────────────────────────────────

    SearchResponse:
      type: object
      properties:
        results:
          type: object
          description: Results grouped by entity type (projects, vendors, models, etc.)
          additionalProperties:
            type: array
            items:
              type: object
              description: Entity-specific result object
        totalCount:
          type: integer
        query:
          type: string
        message:
          type: string
          description: Present when query is too short

    # ─── Reporting ──────────────────────────────────────────────────────────────

    ReportGenerateRequest:
      type: object
      required: [projectId, frameworkId, projectFrameworkId, reportType]
      properties:
        projectId:
          type: integer
        frameworkId:
          type: integer
        projectFrameworkId:
          type: integer
        reportType:
          oneOf:
            - type: string
              enum:
                - projectRisks
                - vendorRisks
                - modelRisks
                - compliance
                - assessment
                - clausesAndAnnexes
                - nistSubcategories
                - vendors
                - models
                - trainingRegistry
                - policyManager
                - incidentManagement
                - all
            - type: array
              items:
                type: string
        reportName:
          type: string
        format:
          type: string
          enum: [pdf, docx]
          default: docx
        aiEnhanced:
          type: boolean
          default: false
        llmKeyId:
          type: integer
          description: LLM key ID for AI-enhanced reports

    GeneratedReport:
      type: object
      properties:
        id:
          type: integer
        filename:
          type: string
        project_id:
          type: integer
        report_type:
          type: string
        created_by:
          type: integer
        organization_id:
          type: integer
        created_at:
          type: string
          format: date-time

    # ─── Dashboard ──────────────────────────────────────────────────────────────

    DashboardData:
      type: object
      properties:
        projects:
          type: integer
          description: Total project count
        trainings:
          type: integer
          description: Total training records
        models:
          type: integer
          description: Total model count
        reports:
          type: integer
          description: Total report count
        task_radar:
          type: object
          properties:
            overdue:
              type: integer
            due:
              type: integer
            upcoming:
              type: integer
        projects_list:
          type: array
          items:
            type: object
            description: Project summary objects

    # ─── CE Marking ────────────────────────────────────────────────────────────

    ConformityStep:
      type: object
      properties:
        id:
          type: integer
        step:
          type: string
        description:
          type: string
          nullable: true
        status:
          type: string
          enum: [Not started, In progress, Completed, Not needed]
        owner:
          type: string
          nullable: true
        dueDate:
          type: string
          format: date
          nullable: true
        completedDate:
          type: string
          format: date
          nullable: true

    CEMarkingResponse:
      type: object
      properties:
        isHighRiskAISystem:
          type: boolean
        roleInProduct:
          type: string
          enum: [standalone, safety_component, product_itself]
        annexIIICategory:
          type: string
        controlsCompleted:
          type: integer
        controlsTotal:
          type: integer
        assessmentsCompleted:
          type: integer
        assessmentsTotal:
          type: integer
        conformitySteps:
          type: array
          items:
            $ref: "#/components/schemas/ConformityStep"
        completedStepsCount:
          type: integer
        totalStepsCount:
          type: integer
        declarationStatus:
          type: string
          enum: [draft, ready, signed]
        signedOn:
          type: string
          format: date
          nullable: true
        signatory:
          type: string
          nullable: true
        declarationDocument:
          type: string
          nullable: true
        registrationStatus:
          type: string
          enum: [not_registered, pending, registered]
        euRegistrationId:
          type: string
          nullable: true
        registrationDate:
          type: string
          format: date
          nullable: true
        euRecordUrl:
          type: string
          format: uri
          nullable: true
        policiesLinked:
          type: integer
        evidenceLinked:
          type: integer
        linkedPolicies:
          type: array
          items:
            type: integer
        linkedEvidences:
          type: array
          items:
            type: integer
        totalIncidents:
          type: integer
        aiActReportableIncidents:
          type: integer
        lastIncident:
          type: string
          format: date-time
          nullable: true
        linkedIncidents:
          type: array
          items:
            type: integer

    CEMarkingUpdateRequest:
      type: object
      properties:
        isHighRiskAISystem:
          type: boolean
        roleInProduct:
          type: string
        annexIIICategory:
          type: string
        declarationStatus:
          type: string
        signedOn:
          type: string
          format: date
        signatory:
          type: string
        declarationDocument:
          type: string
        registrationStatus:
          type: string
        euRegistrationId:
          type: string
        registrationDate:
          type: string
          format: date
        euRecordUrl:
          type: string
        linkedPolicies:
          type: array
          items:
            type: integer
        linkedEvidences:
          type: array
          items:
            type: integer
        linkedIncidents:
          type: array
          items:
            type: integer
        conformitySteps:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              description:
                type: string
              status:
                type: string
                enum: [Not started, In progress, Completed, Not needed]
              owner:
                type: string
              dueDate:
                type: string
                format: date
              completedDate:
                type: string
                format: date

    # ─── Roles ──────────────────────────────────────────────────────────────────

    Role:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          enum: [Admin, Reviewer, Editor, Auditor]
        description:
          type: string

    # ─── Subscriptions ──────────────────────────────────────────────────────────

    SubscriptionCreateRequest:
      type: object
      required: [organization_id, tier_id, status, start_date]
      properties:
        organization_id:
          type: integer
        tier_id:
          type: integer
        stripe_sub_id:
          type: string
          nullable: true
        status:
          type: string
          enum: [active, cancelled, past_due, trialing]
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
          nullable: true

    SubscriptionUpdateRequest:
      type: object
      properties:
        tier_id:
          type: integer
        stripe_sub_id:
          type: string
        status:
          type: string
          enum: [active, cancelled, past_due, trialing]
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
          nullable: true

    Subscription:
      type: object
      properties:
        id:
          type: integer
        organization_id:
          type: integer
        tier_id:
          type: integer
        stripe_sub_id:
          type: string
          nullable: true
        status:
          type: string
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    # ─── Tiers ──────────────────────────────────────────────────────────────────

    TierFeatures:
      type: object
      description: Tier details with associated feature flags
      properties:
        id:
          type: integer
        name:
          type: string
        features:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              enabled:
                type: boolean

    # ─── API Tokens ─────────────────────────────────────────────────────────────

    ApiTokenCreateRequest:
      type: object
      required: [name, expires_in_days]
      properties:
        name:
          type: string
          description: Descriptive name for the token
        expires_in_days:
          type: integer
          minimum: 1
          description: Number of days until token expires

    ApiToken:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        expires_at:
          type: string
          format: date-time
        created_by:
          type: integer
        organization_id:
          type: integer
        created_at:
          type: string
          format: date-time

    ApiTokenCreated:
      allOf:
        - $ref: "#/components/schemas/ApiToken"
        - properties:
            token:
              type: string
              description: Full JWT token value (only shown on creation)

    # ─── LLM Keys ──────────────────────────────────────────────────────────────

    LLMKeyCreateRequest:
      type: object
      required: [name, key]
      properties:
        name:
          type: string
          enum: [Anthropic, OpenAI, OpenRouter, Custom]
          description: LLM provider name
        key:
          type: string
          description: API key value
        model:
          type: string
          description: Default model to use with this key
        url:
          type: string
          format: uri
          description: Required for Custom provider; auto-populated for others
        custom_headers:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: Optional custom headers (string key-value pairs)

    LLMKeyUpdateRequest:
      type: object
      properties:
        name:
          type: string
          enum: [Anthropic, OpenAI, OpenRouter, Custom]
        key:
          type: string
        model:
          type: string
        url:
          type: string
          format: uri
        custom_headers:
          type: object
          additionalProperties:
            type: string
          nullable: true

    LLMKey:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        key:
          type: string
          description: Masked key value
        url:
          type: string
        model:
          type: string
          nullable: true
        custom_headers:
          type: object
          additionalProperties:
            type: string
          nullable: true
        organization_id:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    LLMKeyStatus:
      type: object
      properties:
        hasKeys:
          type: boolean
        keyCount:
          type: integer
        providers:
          type: array
          items:
            type: string

    # ─── User Preferences ───────────────────────────────────────────────────────

    UserPreferenceCreateRequest:
      type: object
      required: [user_id, date_format]
      properties:
        user_id:
          type: integer
          minimum: 1
        date_format:
          type: string
          description: "Preferred date format (e.g., YYYY-MM-DD, DD/MM/YYYY)"

    UserPreferenceUpdateRequest:
      type: object
      properties:
        date_format:
          type: string

    UserPreference:
      type: object
      properties:
        id:
          type: integer
        user_id:
          type: integer
        date_format:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    FileUploadResponse:
      type: object
      properties:
        id:
          type: integer
        filename:
          type: string
        size:
          type: integer
        mimetype:
          type: string
        upload_date:
          type: string
          format: date-time
        uploaded_by:
          type: integer
        modelId:
          type: integer
          nullable: true
        review_status:
          type: string
          enum: [draft, pending_review]
        approval_workflow_id:
          type: integer
          nullable: true
        approval_request_id:
          type: integer
          nullable: true

    FileListResponse:
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileListItem'
        pagination:
          $ref: '#/components/schemas/Pagination'

    FileListItem:
      type: object
      properties:
        id:
          type: integer
        filename:
          type: string
        size:
          type: integer
        formattedSize:
          type: string
        mimetype:
          type: string
        upload_date:
          type: string
          format: date-time
        uploaded_by:
          type: integer
        uploader_name:
          type: string
        uploader_surname:
          type: string
        review_status:
          type: string
        approval_workflow_id:
          type: integer
          nullable: true

    FileSearchResponse:
      type: object
      properties:
        files:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              filename:
                type: string
              snippet:
                type: string
                description: Highlighted text snippet matching the query
              rank:
                type: number
        pagination:
          $ref: '#/components/schemas/Pagination'

    FileMetadata:
      type: object
      properties:
        id:
          type: integer
        tags:
          type: array
          items:
            type: string
        review_status:
          type: string
          enum: [draft, pending_review, approved, rejected, expired]
        version:
          type: string
        expiry_date:
          type: string
          format: date-time
          nullable: true
        description:
          type: string
          nullable: true

    UpdateFileMetadataRequest:
      type: object
      properties:
        tags:
          type: array
          items:
            type: string
          maxItems: 50
          description: Each tag max 100 chars, alphanumeric/spaces/hyphens/underscores only
        review_status:
          type: string
          enum: [draft, pending_review, approved, rejected, expired]
        version:
          type: string
        expiry_date:
          type: string
          format: date-time
        description:
          type: string

    HighlightedFiles:
      type: object
      properties:
        due_for_update:
          type: array
          items:
            type: integer
        pending_approval:
          type: array
          items:
            type: integer
        recently_modified:
          type: array
          items:
            type: integer

    VirtualFolder:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
          nullable: true
        parent_id:
          type: integer
          nullable: true
        color:
          type: string
          nullable: true
        icon:
          type: string
          nullable: true
        is_system:
          type: boolean
        file_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateFolderRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type: string
        parent_id:
          type: integer
          nullable: true
          description: Parent folder ID (null for root)
        color:
          type: string
          description: Hex color code
        icon:
          type: string
          description: Icon identifier

    UpdateFolderRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type: string
        parent_id:
          type: integer
          nullable: true
          description: New parent (null to move to root). Cannot create circular refs.
        color:
          type: string
        icon:
          type: string

    AssignFilesRequest:
      type: object
      required: [file_ids]
      properties:
        file_ids:
          type: array
          items:
            type: integer
          minItems: 1

    # ─── Plugin Schemas ─────────────────────────────────────────────────────

    Plugin:
      type: object
      properties:
        key:
          type: string
        name:
          type: string
        description:
          type: string
        category:
          type: string
        version:
          type: string
        author:
          type: string
        icon_url:
          type: string
        documentation_url:
          type: string

    PluginInstallation:
      type: object
      properties:
        id:
          type: integer
        plugin_key:
          type: string
        organization_id:
          type: integer
        installed_by:
          type: integer
        installed_at:
          type: string
          format: date-time
        configuration:
          type: object
          additionalProperties: true
        status:
          type: string

    ConnectionTestResult:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        details:
          type: object

    # ─── Shadow AI Schemas ──────────────────────────────────────────────────

    ShadowAiToolStatus:
      type: string
      enum: [detected, under_review, approved, restricted, blocked, dismissed]

    ApiKeyCreateResponse:
      type: object
      properties:
        id:
          type: integer
        key:
          type: string
          description: Full API key (shown only on creation)
        key_prefix:
          type: string
        label:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time

    ApiKeyRecord:
      type: object
      properties:
        id:
          type: integer
        key_prefix:
          type: string
        label:
          type: string
          nullable: true
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
          nullable: true

    InsightsSummary:
      type: object
      properties:
        total_events:
          type: integer
        total_users:
          type: integer
        total_tools:
          type: integer
        total_departments:
          type: integer

    UserDetail:
      type: object
      properties:
        email:
          type: string
        department:
          type: string
        tools:
          type: array
          items:
            type: object
            properties:
              tool_name:
                type: string
              event_count:
                type: integer
        total_prompts:
          type: integer

    ShadowAiToolDetail:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        domain:
          type: string
        status:
          $ref: '#/components/schemas/ShadowAiToolStatus'
        first_seen:
          type: string
          format: date-time
        last_seen:
          type: string
          format: date-time
        event_count:
          type: integer
        user_count:
          type: integer
        departments:
          type: array
          items:
            type: object
            properties:
              department:
                type: string
              user_count:
                type: integer
        top_users:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
              event_count:
                type: integer

    StartGovernanceRequest:
      type: object
      required: [model_inventory, governance_owner_id]
      properties:
        model_inventory:
          type: object
          required: [provider, model]
          properties:
            provider:
              type: string
            model:
              type: string
            version:
              type: string
            status:
              type: string
              enum: [Approved, Restricted, Pending, Blocked]
        governance_owner_id:
          type: integer
          minimum: 1
        start_lifecycle:
          type: boolean
          default: false

    StartGovernanceResponse:
      type: object
      properties:
        model_inventory_id:
          type: integer
        tool_id:
          type: integer
        lifecycle_initialized:
          type: boolean

    ShadowAiRule:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
          nullable: true
        is_active:
          type: boolean
        trigger_type:
          type: string
        trigger_config:
          type: object
        actions:
          type: array
          items:
            type: object
        cooldown_minutes:
          type: integer
          nullable: true
        notification_user_ids:
          type: array
          items:
            type: integer
        created_at:
          type: string
          format: date-time

    CreateRuleRequest:
      type: object
      required: [name, trigger_type, actions]
      properties:
        name:
          type: string
        description:
          type: string
        is_active:
          type: boolean
          default: true
        trigger_type:
          type: string
        trigger_config:
          type: object
          default: {}
        actions:
          type: array
          items:
            type: object
        cooldown_minutes:
          type: integer
        notification_user_ids:
          type: array
          items:
            type: integer

    UpdateRuleRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        is_active:
          type: boolean
        trigger_type:
          type: string
        trigger_config:
          type: object
        actions:
          type: array
          items:
            type: object
        cooldown_minutes:
          type: integer
        notification_user_ids:
          type: array
          items:
            type: integer

    SyslogConfig:
      type: object
      properties:
        id:
          type: integer
        source_identifier:
          type: string
        parser_type:
          type: string
          enum: [zscaler, netskope, squid, generic_kv]
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time

    CreateSyslogConfigRequest:
      type: object
      required: [source_identifier, parser_type]
      properties:
        source_identifier:
          type: string
        parser_type:
          type: string
          enum: [zscaler, netskope, squid, generic_kv]
        is_active:
          type: boolean
          default: true

    UpdateSyslogConfigRequest:
      type: object
      properties:
        source_identifier:
          type: string
        parser_type:
          type: string
          enum: [zscaler, netskope, squid, generic_kv]
        is_active:
          type: boolean

    ShadowAiSettings:
      type: object
      properties:
        rate_limit_max_events_per_hour:
          type: integer
        retention_events_days:
          type: integer
        retention_daily_rollups_days:
          type: integer
        retention_alert_history_days:
          type: integer

    UpdateSettingsRequest:
      type: object
      properties:
        rate_limit_max_events_per_hour:
          type: integer
        retention_events_days:
          type: integer
        retention_daily_rollups_days:
          type: integer
        retention_alert_history_days:
          type: integer

    # ─── Post-Market Monitoring Schemas ─────────────────────────────────────

    PMMConfig:
      type: object
      properties:
        id:
          type: integer
        project_id:
          type: integer
        frequency:
          type: string
          description: Monitoring frequency (e.g., "monthly", "quarterly")
        stakeholder_id:
          type: integer
          nullable: true
        is_active:
          type: boolean
        questions_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    PMMConfigCreateRequest:
      type: object
      required: [project_id]
      properties:
        project_id:
          type: integer
        frequency:
          type: string
        stakeholder_id:
          type: integer
        is_active:
          type: boolean
          default: true

    PMMConfigUpdateRequest:
      type: object
      properties:
        frequency:
          type: string
        stakeholder_id:
          type: integer
        is_active:
          type: boolean

    PMMQuestion:
      type: object
      properties:
        id:
          type: integer
        config_id:
          type: integer
          nullable: true
        question_text:
          type: string
        question_type:
          type: string
          enum: [yes_no, multi_select, multi_line_text]
        options:
          type: array
          items:
            type: string
          nullable: true
        is_required:
          type: boolean
        is_default:
          type: boolean
        display_order:
          type: integer
        created_at:
          type: string
          format: date-time

    PMMQuestionCreate:
      type: object
      required: [question_text, question_type]
      properties:
        config_id:
          type: integer
          nullable: true
        question_text:
          type: string
        question_type:
          type: string
          enum: [yes_no, multi_select, multi_line_text]
        options:
          type: array
          items:
            type: string
        is_required:
          type: boolean
          default: false
        display_order:
          type: integer

    PMMQuestionUpdate:
      type: object
      properties:
        question_text:
          type: string
        question_type:
          type: string
          enum: [yes_no, multi_select, multi_line_text]
        options:
          type: array
          items:
            type: string
        is_required:
          type: boolean
        display_order:
          type: integer

    PMMCycle:
      type: object
      properties:
        id:
          type: integer
        config_id:
          type: integer
        project_id:
          type: integer
        project_title:
          type: string
        cycle_number:
          type: integer
        status:
          type: string
          enum: [active, completed]
        assigned_stakeholder_id:
          type: integer
          nullable: true
        due_date:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time

    PMMResponse:
      type: object
      properties:
        id:
          type: integer
        cycle_id:
          type: integer
        question_id:
          type: integer
        response_value:
          type: string
        is_flagged:
          type: boolean
        created_at:
          type: string
          format: date-time

    PMMSaveResponsesRequest:
      type: object
      required: [responses]
      properties:
        responses:
          type: array
          minItems: 1
          items:
            type: object
            required: [question_id, response_value]
            properties:
              question_id:
                type: integer
              response_value:
                type: string
              is_flagged:
                type: boolean
                default: false

    PMMSubmitCycleResponse:
      type: object
      properties:
        message:
          type: string
        report_generated:
          type: boolean
        report_filename:
          type: string
          nullable: true

    PMMReportsResponse:
      type: object
      properties:
        reports:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              cycle_id:
                type: integer
              file_id:
                type: integer
                nullable: true
              completed_by:
                type: integer
              created_at:
                type: string
                format: date-time
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer

    # ===== Tasks schemas =====
    TaskPriority:
      type: string
      enum: [Low, Medium, High]
      description: Task priority level.
    TaskStatus:
      type: string
      enum: [Open, In Progress, Completed, Overdue, Deleted]
      description: Task lifecycle status. "Deleted" represents a soft-deleted (archived) task.
    EntityType:
      type: string
      enum:
        - vendor
        - model
        - policy
        - nist_subcategory
        - iso42001_subclause
        - iso42001_annexcategory
        - iso27001_subclause
        - iso27001_annexcontrol
        - eu_control
        - eu_subcontrol
      description: Type of entity that can be linked to a task.
    CreateTaskRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          example: Review vendor risk assessment
        description:
          type: string
          nullable: true
        due_date:
          type: string
          format: date-time
          nullable: true
          example: "2026-05-15T00:00:00.000Z"
        priority:
          $ref: "#/components/schemas/TaskPriority"
        status:
          $ref: "#/components/schemas/TaskStatus"
        categories:
          type: array
          items:
            type: string
          example: ["compliance", "vendor"]
        assignees:
          type: array
          items:
            oneOf:
              - type: integer
              - type: object
                properties:
                  user_id:
                    type: integer
                required:
                  - user_id
          example: [1, 2, 3]
        entity_links:
          type: array
          items:
            type: object
            properties:
              entity_id:
                type: integer
              entity_type:
                $ref: "#/components/schemas/EntityType"
              entity_name:
                type: string
    UpdateTaskRequest:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
          nullable: true
        due_date:
          type: string
          format: date-time
          nullable: true
        priority:
          $ref: "#/components/schemas/TaskPriority"
        status:
          $ref: "#/components/schemas/TaskStatus"
        categories:
          type: array
          items:
            type: string
        assignees:
          type: array
          items:
            type: integer
        entity_links:
          type: array
          items:
            type: object
            properties:
              entity_id:
                type: integer
              entity_type:
                $ref: "#/components/schemas/EntityType"
              entity_name:
                type: string
    AddEntityLinkRequest:
      type: object
      required:
        - entity_id
        - entity_type
      properties:
        entity_id:
          type: integer
          example: 42
        entity_type:
          $ref: "#/components/schemas/EntityType"
        entity_name:
          type: string
          example: Acme Corp
    Task:
      type: object
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: Review vendor risk assessment
        description:
          type: string
          nullable: true
        creator_id:
          type: integer
        organization_id:
          type: integer
        due_date:
          type: string
          format: date-time
          nullable: true
        priority:
          $ref: "#/components/schemas/TaskPriority"
        status:
          $ref: "#/components/schemas/TaskStatus"
        categories:
          type: array
          items:
            type: string
        is_demo:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    TaskWithAssignees:
      allOf:
        - $ref: "#/components/schemas/Task"
        - type: object
          properties:
            assignees:
              type: array
              items:
                type: integer
    TaskWithRelations:
      allOf:
        - $ref: "#/components/schemas/Task"
        - type: object
          properties:
            assignees:
              type: array
              items:
                type: integer
            entity_links:
              type: array
              items:
                $ref: "#/components/schemas/EntityLinkSummary"
    TaskDetail:
      allOf:
        - $ref: "#/components/schemas/Task"
        - type: object
          properties:
            assignees:
              type: array
              items:
                type: integer
            creator_name:
              type: string
              example: Jane Smith
            assignee_names:
              type: array
              items:
                type: string
              example: ["John Doe", "Alice Johnson"]
            entity_links:
              type: array
              items:
                $ref: "#/components/schemas/EntityLinkSummary"
    EntityLinkSummary:
      type: object
      properties:
        id:
          type: integer
        entity_id:
          type: integer
        entity_type:
          $ref: "#/components/schemas/EntityType"
        entity_name:
          type: string
    TaskEntityLink:
      type: object
      properties:
        id:
          type: integer
        task_id:
          type: integer
        entity_id:
          type: integer
        entity_type:
          $ref: "#/components/schemas/EntityType"
        entity_name:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    # ===== Training schemas =====
    EnvelopeBase:
      type: object
      properties:
        message:
          type: string
      required:
        - message
    EnvelopeEmpty:
      allOf:
        - $ref: "#/components/schemas/EnvelopeBase"
        - type: object
          properties:
            message:
              example: No Content
            data:
              type: array
              items: {}
              example: []
    EnvelopeNotFound:
      allOf:
        - $ref: "#/components/schemas/EnvelopeBase"
        - type: object
          properties:
            message:
              example: Not Found
            data:
              nullable: true
              example: null
    EnvelopeBadRequest:
      allOf:
        - $ref: "#/components/schemas/EnvelopeBase"
        - type: object
          properties:
            message:
              example: Bad Request
            data:
              type: string
              example: Invalid training ID
    EnvelopeError:
      type: object
      properties:
        message:
          type: string
          example: Internal Server Error
        error:
          type: string
      required:
        - message
        - error
    Training:
      type: object
      properties:
        id:
          type: integer
          example: 42
        training_name:
          type: string
          example: AI Governance Fundamentals
        duration:
          type: string
          example: 2 hours
        provider:
          type: string
          example: Internal
        department:
          type: string
          example: Compliance
        status:
          type: string
          enum: [Planned, In Progress, Completed]
          example: Planned
        numberOfPeople:
          type: integer
          example: 25
        description:
          type: string
          example: Introductory course on EU AI Act compliance
        progressPercentage:
          type: integer
          enum: [0, 50, 100]
          example: 0
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - training_name
        - duration
        - provider
        - department
        - status
        - numberOfPeople
        - description
        - progressPercentage
    TrainingCreateRequest:
      type: object
      required:
        - training_name
        - duration
        - provider
        - department
        - status
        - numberOfPeople
      properties:
        training_name:
          type: string
          example: AI Governance Fundamentals
        duration:
          type: string
          example: 2 hours
        provider:
          type: string
          example: Internal
        department:
          type: string
          example: Compliance
        status:
          type: string
          enum: [Planned, In Progress, Completed]
          example: Planned
        numberOfPeople:
          type: integer
          example: 25
        description:
          type: string
          example: Introductory course on EU AI Act compliance
        is_demo:
          type: boolean
          default: false
    TrainingUpdateRequest:
      type: object
      properties:
        training_name:
          type: string
          example: Advanced AI Risk Management
        duration:
          type: string
          example: 3 days
        provider:
          type: string
          example: External
        department:
          type: string
          example: Engineering
        status:
          type: string
          enum: [Planned, In Progress, Completed]
          example: In Progress
        numberOfPeople:
          type: integer
          example: 30
        description:
          type: string
          example: Updated scope to cover ISO 42001
    TrainingListResponse:
      allOf:
        - $ref: "#/components/schemas/EnvelopeBase"
        - type: object
          properties:
            message:
              example: OK
            data:
              type: array
              items:
                $ref: "#/components/schemas/Training"
    TrainingSingleResponse:
      allOf:
        - $ref: "#/components/schemas/EnvelopeBase"
        - type: object
          properties:
            message:
              example: OK
            data:
              $ref: "#/components/schemas/Training"
    ChangeHistoryEntry:
      type: object
      properties:
        id:
          type: integer
          example: 101
        entity_type:
          type: string
          example: training
        entity_id:
          type: integer
          example: 42
        field_name:
          type: string
          example: status
        old_value:
          type: string
          nullable: true
          example: Planned
        new_value:
          type: string
          nullable: true
          example: In Progress
        change_type:
          type: string
          enum: [created, updated, deleted]
          example: updated
        changed_by:
          type: integer
          example: 5
        user_name:
          type: string
          example: Gorkem
        user_surname:
          type: string
          example: Cetin
        organization_id:
          type: integer
          example: 1
        created_at:
          type: string
          format: date-time
    ChangeHistoryData:
      type: object
      required:
        - data
        - hasMore
        - total
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ChangeHistoryEntry"
        hasMore:
          type: boolean
          example: false
        total:
          type: integer
          example: 5
    ChangeHistoryResponse:
      allOf:
        - $ref: "#/components/schemas/EnvelopeBase"
        - type: object
          properties:
            message:
              example: OK
            data:
              $ref: "#/components/schemas/ChangeHistoryData"

    # ===== Organizations schemas =====
    CreateOrganizationRequest:
      type: object
      required:
        - name
        - userEmail
        - userName
        - userSurname
        - userPassword
      properties:
        name:
          type: string
          example: Acme Corp
        logo:
          type: string
          format: uri
          nullable: true
          example: https://example.com/logo.png
        userEmail:
          type: string
          format: email
          example: admin@acme.com
        userName:
          type: string
          example: John
        userSurname:
          type: string
          example: Doe
        userPassword:
          type: string
          format: password
          example: SecurePassword123!
    UpdateOrganizationRequest:
      type: object
      properties:
        name:
          type: string
          example: Acme Corporation
        logo:
          type: string
          format: uri
          nullable: true
          example: https://example.com/new-logo.png
    Organization:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Acme Corp
        logo:
          type: string
          nullable: true
          example: https://example.com/logo.png
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        onboarding_status:
          type: string
          enum: [pending, completed]
          example: pending
        tenant_id:
          type: string
          nullable: true
          example: a1b2c3d4e5
        risk_assessment_mode:
          type: string
          enum: [qualitative, quantitative]
          example: qualitative
        ageInDays:
          type: integer
          example: 45
    OrganizationExistsResult:
      type: object
      properties:
        exists:
          type: boolean
          example: true
    CreateOrganizationResponse:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/SafeUser"
        organization:
          type: object
          properties:
            id:
              type: integer
              example: 1
            name:
              type: string
              example: Acme Corp
        token:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    SafeUser:
      type: object
      properties:
        id:
          type: integer
          example: 1
        email:
          type: string
          format: email
          example: admin@acme.com
        name:
          type: string
          example: John
        surname:
          type: string
          example: Doe
        role_id:
          type: integer
          example: 1
        organization_id:
          type: integer
          example: 1
    OnboardingStatusResponse:
      type: object
      properties:
        onboarding_status:
          type: string
          enum: [completed]
          example: completed

    # ===== Notifications schemas =====
    NotificationType:
      type: string
      enum:
        - task_assigned
        - task_updated
        - task_completed
        - review_requested
        - review_approved
        - review_rejected
        - approval_requested
        - approval_approved
        - approval_rejected
        - approval_complete
        - policy_due_soon
        - policy_overdue
        - training_assigned
        - training_completed
        - vendor_review_due
        - file_uploaded
        - comment_added
        - mention
        - shadow_ai_alert
        - ai_gateway_budget_warning
        - ai_gateway_budget_exhausted
        - ai_gateway_guardrail_spike
        - ai_gateway_config_change
        - ai_gateway_virtual_key_budget_exhausted
        - system
        - assignment_owner
        - assignment_reviewer
        - assignment_approver
        - assignment_member
        - assignment_assignee
        - assignment_action_owner
    NotificationEntityType:
      type: string
      enum:
        - project
        - task
        - policy
        - vendor
        - model
        - training
        - file
        - use_case
        - risk
        - assessment
        - comment
        - user
        - shadow_ai_tool
        - ai_gateway
    NotificationJSON:
      type: object
      required:
        - id
        - user_id
        - type
        - title
        - message
        - is_read
        - created_at
      properties:
        id:
          type: integer
          example: 42
        user_id:
          type: integer
          example: 7
        type:
          $ref: "#/components/schemas/NotificationType"
        title:
          type: string
          example: "Task assigned to you"
        message:
          type: string
          example: "You have been assigned to task 'Review vendor contract'."
        entity_type:
          allOf:
            - $ref: "#/components/schemas/NotificationEntityType"
          nullable: true
        entity_id:
          type: integer
          nullable: true
          example: 15
        entity_name:
          type: string
          nullable: true
          example: "Review vendor contract"
        action_url:
          type: string
          nullable: true
          example: "/projects/3/tasks/15"
        is_read:
          type: boolean
          example: false
        read_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
          example: "2026-04-20T10:00:00.000Z"
        created_by:
          type: integer
          nullable: true
          example: 3
        metadata:
          type: object
          nullable: true
          additionalProperties: true
    NotificationSummary:
      type: object
      required:
        - unread_count
        - total_count
        - recent_notifications
      properties:
        unread_count:
          type: integer
          example: 3
        total_count:
          type: integer
          example: 47
        recent_notifications:
          type: array
          maxItems: 10
          items:
            $ref: "#/components/schemas/NotificationJSON"
    RealtimeNotification:
      type: object
      required:
        - type
        - data
      properties:
        type:
          type: string
          enum: [notification]
        data:
          $ref: "#/components/schemas/NotificationJSON"

    # ===== FRIA schemas =====
    ApiEnvelope:
      type: object
      properties:
        status:
          type: integer
          example: 200
        data:
          description: Response payload (varies per endpoint)
    FriaErrorEnvelope:
      type: object
      properties:
        status:
          type: integer
          example: 400
        data:
          type: string
          example: "Invalid project ID"
    DeletedResponse:
      type: object
      properties:
        deleted:
          type: boolean
          example: true
    FriaStatus:
      type: string
      enum: [draft, submitted, approved, rejected]
    FriaRiskLevel:
      type: string
      enum: [Low, Medium, High]
    FriaLikelihood:
      type: string
      enum: [Low, Medium, High]
    FriaSeverity:
      type: string
      enum: [Low, Medium, High]
    FriaAssessment:
      type: object
      properties:
        id:
          type: integer
        organization_id:
          type: integer
        project_id:
          type: integer
        version:
          type: integer
        status:
          $ref: "#/components/schemas/FriaStatus"
        assessment_owner:
          type: string
          nullable: true
        assessment_date:
          type: string
          nullable: true
        operational_context:
          type: string
          nullable: true
        is_high_risk:
          type: string
          nullable: true
        high_risk_basis:
          type: string
          nullable: true
        deployer_type:
          type: string
          nullable: true
        annex_iii_category:
          type: string
          nullable: true
        first_use_date:
          type: string
          nullable: true
        review_cycle:
          type: string
          nullable: true
        period_frequency:
          type: string
          nullable: true
        fria_rationale:
          type: string
          nullable: true
        affected_groups:
          type: string
          nullable: true
        vulnerability_context:
          type: string
          nullable: true
        group_flags:
          type: array
          items:
            type: string
          nullable: true
        risk_scenarios:
          type: string
          nullable: true
        provider_info_used:
          type: string
          nullable: true
        human_oversight:
          type: string
          nullable: true
        transparency_measures:
          type: string
          nullable: true
        redress_process:
          type: string
          nullable: true
        data_governance:
          type: string
          nullable: true
        legal_review:
          type: string
          nullable: true
        dpo_review:
          type: string
          nullable: true
        owner_approval:
          type: string
          nullable: true
        stakeholders_consulted:
          type: string
          nullable: true
        consultation_notes:
          type: string
          nullable: true
        deployment_decision:
          type: string
          nullable: true
        decision_conditions:
          type: string
          nullable: true
        completion_pct:
          type: integer
        risk_score:
          type: integer
        risk_level:
          $ref: "#/components/schemas/FriaRiskLevel"
        rights_flagged:
          type: integer
        created_by:
          type: integer
        updated_by:
          type: integer
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
        project_title:
          type: string
          nullable: true
        organization_name:
          type: string
          nullable: true
        created_by_name:
          type: string
          nullable: true
        updated_by_name:
          type: string
          nullable: true
    FriaUpdateRequest:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/FriaStatus"
        assessment_owner:
          type: string
        assessment_date:
          type: string
        operational_context:
          type: string
        is_high_risk:
          type: string
        high_risk_basis:
          type: string
        deployer_type:
          type: string
        annex_iii_category:
          type: string
        first_use_date:
          type: string
        review_cycle:
          type: string
        period_frequency:
          type: string
        fria_rationale:
          type: string
        affected_groups:
          type: string
        vulnerability_context:
          type: string
        group_flags:
          type: array
          items:
            type: string
        risk_scenarios:
          type: string
        provider_info_used:
          type: string
        human_oversight:
          type: string
        transparency_measures:
          type: string
        redress_process:
          type: string
        data_governance:
          type: string
        legal_review:
          type: string
        dpo_review:
          type: string
        owner_approval:
          type: string
        stakeholders_consulted:
          type: string
        consultation_notes:
          type: string
        deployment_decision:
          type: string
        decision_conditions:
          type: string
    FriaFullResponse:
      type: object
      properties:
        assessment:
          $ref: "#/components/schemas/FriaAssessment"
        rights:
          type: array
          items:
            $ref: "#/components/schemas/FriaRight"
        riskItems:
          type: array
          items:
            $ref: "#/components/schemas/FriaRiskItem"
        modelLinks:
          type: array
          items:
            $ref: "#/components/schemas/FriaModelLink"
    FriaRight:
      type: object
      properties:
        id:
          type: integer
        organization_id:
          type: integer
        fria_id:
          type: integer
        right_key:
          type: string
        right_title:
          type: string
        charter_ref:
          type: string
        flagged:
          type: boolean
        severity:
          type: integer
        confidence:
          type: integer
        impact_pathway:
          type: string
          nullable: true
        mitigation:
          type: string
          nullable: true
    FriaRightsUpdateRequest:
      type: object
      required:
        - rights
      properties:
        rights:
          type: array
          items:
            type: object
            required:
              - right_key
            properties:
              right_key:
                type: string
              flagged:
                type: boolean
              severity:
                type: integer
              confidence:
                type: integer
              impact_pathway:
                type: string
              mitigation:
                type: string
    FriaRiskItem:
      type: object
      properties:
        id:
          type: integer
        organization_id:
          type: integer
        fria_id:
          type: integer
        risk_description:
          type: string
        likelihood:
          $ref: "#/components/schemas/FriaLikelihood"
        severity:
          $ref: "#/components/schemas/FriaSeverity"
        existing_controls:
          type: string
          nullable: true
        further_action:
          type: string
          nullable: true
        linked_project_risk_id:
          type: integer
          nullable: true
        sort_order:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
        linked_risk_name:
          type: string
          nullable: true
        linked_risk_description:
          type: string
          nullable: true
    FriaRiskItemCreateRequest:
      type: object
      required:
        - risk_description
      properties:
        risk_description:
          type: string
        likelihood:
          $ref: "#/components/schemas/FriaLikelihood"
        severity:
          $ref: "#/components/schemas/FriaSeverity"
        existing_controls:
          type: string
        further_action:
          type: string
        linked_project_risk_id:
          type: integer
        sort_order:
          type: integer
    FriaRiskItemUpdateRequest:
      type: object
      properties:
        risk_description:
          type: string
        likelihood:
          $ref: "#/components/schemas/FriaLikelihood"
        severity:
          $ref: "#/components/schemas/FriaSeverity"
        existing_controls:
          type: string
        further_action:
          type: string
        linked_project_risk_id:
          type: integer
        sort_order:
          type: integer
    FriaModelLink:
      type: object
      properties:
        id:
          type: integer
        organization_id:
          type: integer
        fria_id:
          type: integer
        model_id:
          type: integer
        provider:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        version:
          type: string
          nullable: true
        model_status:
          type: string
          nullable: true
    FriaEvidenceLinkRequest:
      type: object
      required:
        - file_id
        - entity_type
      properties:
        file_id:
          type: integer
        entity_type:
          type: string
    FriaSnapshot:
      type: object
      properties:
        id:
          type: integer
        organization_id:
          type: integer
        fria_id:
          type: integer
        version:
          type: integer
        snapshot_data:
          type: object
          properties:
            assessment:
              $ref: "#/components/schemas/FriaAssessment"
            rights:
              type: array
              items:
                $ref: "#/components/schemas/FriaRight"
            riskItems:
              type: array
              items:
                $ref: "#/components/schemas/FriaRiskItem"
            modelLinks:
              type: array
              items:
                $ref: "#/components/schemas/FriaModelLink"
        snapshot_reason:
          type: string
          nullable: true
        created_by:
          type: integer
        created_at:
          type: string
          format: date-time
        created_by_name:
          type: string
          nullable: true
    FriaSubmitRequest:
      type: object
      properties:
        reason:
          type: string

    # ===== Integrations schemas =====
    StandardResponse:
      type: object
      properties:
        message:
          type: string
        data:
          description: Response payload (present on 1xx-4xx)
        error:
          type: string
    ErrorResponse400:
      type: object
      properties:
        message:
          type: string
          example: "Bad Request"
        data:
          type: string
          example: "userId query parameter is required"
    ErrorResponse401:
      type: object
      properties:
        message:
          type: string
          example: "Unauthorized"
        data:
          type: string
    ErrorResponse403:
      type: object
      properties:
        message:
          type: string
          example: "Forbidden"
        data:
          type: string
    ErrorResponse404:
      type: object
      properties:
        message:
          type: string
          example: "Not Found"
        data:
          type: string
    ErrorResponse500:
      type: object
      properties:
        message:
          type: string
          example: "Internal Server Error"
        error:
          type: string
    SlackNotificationRoutingType:
      type: string
      enum:
        - "Membership and roles"
        - "Projects and organizations"
        - "Policy reminders and status"
        - "Evidence and task alerts"
        - "Control or policy changes"
    SlackWebhookFull:
      type: object
      properties:
        id:
          type: integer
          example: 1
        access_token:
          type: string
        access_token_iv:
          type: string
        scope:
          type: string
          example: "incoming-webhook,chat:write"
        user_id:
          type: integer
          example: 5
        team_name:
          type: string
          example: "Acme Corp"
        team_id:
          type: string
          example: "T01234ABC"
        channel:
          type: string
          example: "#general"
        channel_id:
          type: string
          example: "C01234ABC"
        configuration_url:
          type: string
          format: uri
        url:
          type: string
        url_iv:
          type: string
        is_active:
          type: boolean
          example: true
        routing_type:
          type: array
          items:
            $ref: "#/components/schemas/SlackNotificationRoutingType"
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SlackWebhookJSON:
      type: object
      properties:
        id:
          type: integer
        scope:
          type: string
        user_id:
          type: integer
        team_name:
          type: string
        team_id:
          type: string
        channel:
          type: string
        channel_id:
          type: string
        created_at:
          type: string
          format: date-time
        is_active:
          type: boolean
        routing_type:
          type: array
          items:
            $ref: "#/components/schemas/SlackNotificationRoutingType"
          nullable: true
    CreateSlackWebhookRequest:
      type: object
      required:
        - code
        - userId
      properties:
        code:
          type: string
          example: "1234567890.abcdef"
        userId:
          type: integer
          example: 5
    UpdateSlackWebhookRequest:
      type: object
      properties:
        is_active:
          type: boolean
          example: false
        routing_type:
          type: array
          items:
            $ref: "#/components/schemas/SlackNotificationRoutingType"
    SendSlackMessageRequest:
      type: object
      required:
        - title
        - message
      properties:
        title:
          type: string
          example: "New policy update"
        message:
          type: string
          example: "Policy *Data Retention* has been updated."
    SlackMessageSentResult:
      type: object
      properties:
        success:
          type: boolean
          example: true
        messageId:
          type: string
          example: "1234567890.123456"
        channel:
          type: string
          example: "C01234ABC"
    GitHubTokenStatus:
      type: object
      properties:
        configured:
          type: boolean
          example: true
        token_name:
          type: string
          example: "GitHub Personal Access Token"
        last_used_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
    SaveGitHubTokenRequest:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          example: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        token_name:
          type: string
          default: "GitHub Personal Access Token"
          example: "CI/CD Scanner Token"
    TestGitHubTokenRequest:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          example: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    GitHubTokenTestResult:
      type: object
      properties:
        valid:
          type: boolean
          example: true
        scopes:
          type: array
          items:
            type: string
          example: ["repo", "read:org"]
        rate_limit:
          type: object
          properties:
            limit:
              type: integer
              example: 5000
            remaining:
              type: integer
              example: 4999
            reset:
              type: string
              format: date-time
        error:
          type: string
          example: "Invalid or expired token"
    GitHubWebhookPayload:
      type: object
      required:
        - repository
      properties:
        repository:
          type: object
          required:
            - owner
            - name
          properties:
            owner:
              type: object
              required:
                - login
              properties:
                login:
                  type: string
                  example: "verifywise-ai"
            name:
              type: string
              example: "verifywise"
        ref:
          type: string
          example: "refs/heads/main"
        action:
          type: string
          example: "opened"
        pull_request:
          type: object
    GitHubWebhookResult:
      type: object
      properties:
        triggered:
          type: boolean
        reason:
          type: string
          example: "Scan triggered for push to main"
    GitHubWebhookPong:
      type: object
      properties:
        message:
          type: string
          example: "pong"
    GitHubWebhookSkipped:
      type: object
      properties:
        message:
          type: string
          example: "Repository not registered or CI not enabled"
    SuccessResponse_SlackWebhookArray:
      type: object
      properties:
        message:
          type: string
          example: "OK"
        data:
          type: array
          items:
            $ref: "#/components/schemas/SlackWebhookFull"
    SuccessResponse_SlackWebhookJSON:
      type: object
      properties:
        message:
          type: string
          example: "OK"
        data:
          $ref: "#/components/schemas/SlackWebhookJSON"
    CreatedResponse_SlackWebhookFull:
      type: object
      properties:
        message:
          type: string
          example: "Created"
        data:
          $ref: "#/components/schemas/SlackWebhookFull"
    AcceptedResponse_SlackWebhookFull:
      type: object
      properties:
        message:
          type: string
          example: "Accepted"
        data:
          $ref: "#/components/schemas/SlackWebhookFull"
    SuccessResponse_SlackMessageSent:
      type: object
      properties:
        message:
          type: string
          example: "OK"
        data:
          $ref: "#/components/schemas/SlackMessageSentResult"
    SuccessResponse_GitHubTokenStatus:
      type: object
      properties:
        message:
          type: string
          example: "OK"
        data:
          $ref: "#/components/schemas/GitHubTokenStatus"
    CreatedResponse_GitHubTokenStatus:
      type: object
      properties:
        message:
          type: string
          example: "Created"
        data:
          $ref: "#/components/schemas/GitHubTokenStatus"
    SuccessResponse_GitHubTokenDeleted:
      type: object
      properties:
        message:
          type: string
          example: "OK"
        data:
          type: object
          properties:
            message:
              type: string
              example: "GitHub token deleted successfully"
    SuccessResponse_GitHubTokenTest:
      type: object
      properties:
        message:
          type: string
          example: "OK"
        data:
          $ref: "#/components/schemas/GitHubTokenTestResult"

tags:
  - name: AI Advisor
  - name: AI Detection
  - name: AI Trust Centre
  - name: Agent Discovery
  - name: Approval Workflows
  - name: Assessments
  - name: Audit
  - name: Authentication
  - name: Automations
  - name: CE Marking
  - name: Change History
  - name: Compliance
  - name: Dashboard
  - name: Datasets
  - name: Demo Data
  - name: EU AI Act
  - name: Entity Graph
  - name: Evidence
  - name: FRIA
  - name: Files
  - name: Frameworks
  - name: ISO 27001
  - name: ISO 42001
  - name: Incidents
  - name: Intake Forms
  - name: Integrations
  - name: Internal
  - name: Invitations
  - name: LLM Keys
  - name: Mail
  - name: Model Inventory
  - name: Model Risks
  - name: NIST AI RMF
  - name: Notes
  - name: Notifications
  - name: Organizations
  - name: Plugins
  - name: Policies
  - name: Post-Market Monitoring
  - name: Project Risks
  - name: Projects
  - name: Quantitative Risks
  - name: Reporting
  - name: Risk Benchmarks
  - name: Risk History
  - name: Roles
  - name: Search
  - name: Settings
  - name: Shadow AI
  - name: Share Links
  - name: Subscriptions
  - name: Super Admin
  - name: System
  - name: Tasks
  - name: Training
  - name: Users
  - name: Vendor Risks
  - name: Vendors
  - name: Webhooks

paths:
  /advisor:
    post:
      tags:
        - AI Advisor
      summary: Run Advisor
      operationId: runAdvisor
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /advisor/chat:
    post:
      tags:
        - AI Advisor
      summary: Stream Advisor V2
      operationId: streamAdvisorV2
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /advisor/conversations/{domain}:
    get:
      tags:
        - AI Advisor
      summary: Get Conversation
      operationId: getConversation
      security:
        - bearerAuth: []
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - AI Advisor
      summary: Save Conversation
      operationId: saveConversation
      security:
        - bearerAuth: []
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /advisor/stream:
    post:
      tags:
        - AI Advisor
      summary: Stream Advisor
      operationId: streamAdvisor
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /agent-primitives:
    get:
      tags:
        - Agent Discovery
      summary: Get All Agent Primitives
      operationId: getAllAgentPrimitives
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Agent Discovery
      summary: Create Agent Primitive
      operationId: createAgentPrimitive
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /agent-primitives/stats:
    get:
      tags:
        - Agent Discovery
      summary: Get Agent Stats
      operationId: getAgentStats
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /agent-primitives/sync:
    post:
      tags:
        - Agent Discovery
      summary: Trigger Sync
      operationId: triggerSync
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /agent-primitives/sync/logs:
    get:
      tags:
        - Agent Discovery
      summary: Get Sync Logs
      operationId: getSyncLogs
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /agent-primitives/sync/status:
    get:
      tags:
        - Agent Discovery
      summary: Get Sync Status
      operationId: getSyncStatus
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /agent-primitives/{id}:
    get:
      tags:
        - Agent Discovery
      summary: Get Agent Primitive By Id
      operationId: getAgentPrimitiveById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Agent Discovery
      summary: Update Agent Primitive
      operationId: updateAgentPrimitive
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Agent Discovery
      summary: Delete Agent Primitive By Id
      operationId: deleteAgentPrimitiveById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /agent-primitives/{id}/audit-logs:
    get:
      tags:
        - Agent Discovery
      summary: Get Agent Audit Logs
      operationId: getAgentAuditLogs
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /agent-primitives/{id}/link-model:
    patch:
      tags:
        - Agent Discovery
      summary: Link Model To Agent
      operationId: linkModelToAgent
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /agent-primitives/{id}/review:
    patch:
      tags:
        - Agent Discovery
      summary: Review Agent Primitive
      operationId: reviewAgentPrimitive
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /agent-primitives/{id}/unlink-model:
    patch:
      tags:
        - Agent Discovery
      summary: Unlink Model From Agent
      operationId: unlinkModelFromAgent
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/repositories:
    get:
      tags:
        - AI Detection
      summary: List Repositories
      operationId: listRepositories
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - AI Detection
      summary: Create Repository
      operationId: createRepository
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/repositories/{id}:
    get:
      tags:
        - AI Detection
      summary: Get Repository
      operationId: getRepository
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - AI Detection
      summary: Update Repository
      operationId: updateRepository
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - AI Detection
      summary: Delete Repository
      operationId: deleteRepository
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/repositories/{id}/scan:
    post:
      tags:
        - AI Detection
      summary: Trigger Repository Scan
      operationId: triggerRepositoryScan
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/repositories/{id}/scans:
    get:
      tags:
        - AI Detection
      summary: Get Repository Scans
      operationId: getRepositoryScans
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/repositories/{id}/webhook-secret:
    post:
      tags:
        - AI Detection
      summary: Generate Webhook Secret Controller
      operationId: generateWebhookSecretController
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/risk-scoring/config:
    get:
      tags:
        - AI Detection
      summary: Get Risk Scoring Config Controller
      operationId: getRiskScoringConfigController
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - AI Detection
      summary: Update Risk Scoring Config Controller
      operationId: updateRiskScoringConfigController
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans:
    post:
      tags:
        - AI Detection
      summary: Start Scan Controller
      operationId: startScanController
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    get:
      tags:
        - AI Detection
      summary: Get Scans Controller
      operationId: getScansController
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/active:
    get:
      tags:
        - AI Detection
      summary: Get Active Scan Controller
      operationId: getActiveScanController
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}:
    get:
      tags:
        - AI Detection
      summary: Get Scan Controller
      operationId: getScanController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - AI Detection
      summary: Delete Scan Controller
      operationId: deleteScanController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/cancel:
    post:
      tags:
        - AI Detection
      summary: Cancel Scan Controller
      operationId: cancelScanController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/compliance:
    get:
      tags:
        - AI Detection
      summary: Get Compliance Mapping Controller
      operationId: getComplianceMappingController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/dependency-graph:
    get:
      tags:
        - AI Detection
      summary: Get Dependency Graph Controller
      operationId: getDependencyGraphController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/export/ai-bom:
    get:
      tags:
        - AI Detection
      summary: Export A I B O M Controller
      operationId: exportAIBOMController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/findings:
    get:
      tags:
        - AI Detection
      summary: Get Scan Findings Controller
      operationId: getScanFindingsController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/findings/{findingId}/governance:
    patch:
      tags:
        - AI Detection
      summary: Update Governance Status Controller
      operationId: updateGovernanceStatusController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
        - name: findingId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/governance-summary:
    get:
      tags:
        - AI Detection
      summary: Get Governance Summary Controller
      operationId: getGovernanceSummaryController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/risk-score:
    get:
      tags:
        - AI Detection
      summary: Get Risk Score Controller
      operationId: getRiskScoreController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/risk-score/recalculate:
    post:
      tags:
        - AI Detection
      summary: Recalculate Risk Score Controller
      operationId: recalculateRiskScoreController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/security-findings:
    get:
      tags:
        - AI Detection
      summary: Get Security Findings Controller
      operationId: getSecurityFindingsController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/security-summary:
    get:
      tags:
        - AI Detection
      summary: Get Security Summary Controller
      operationId: getSecuritySummaryController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/scans/{scanId}/status:
    get:
      tags:
        - AI Detection
      summary: Get Scan Status Controller
      operationId: getScanStatusController
      security:
        - bearerAuth: []
      parameters:
        - name: scanId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-detection/stats:
    get:
      tags:
        - AI Detection
      summary: Get A I Detection Stats Controller
      operationId: getAIDetectionStatsController
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-incident-managements:
    get:
      tags:
        - Incidents
      summary: Get All Incidents
      operationId: getAllIncidents
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Incidents
      summary: Create New Incident
      operationId: createNewIncident
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-incident-managements/{id}:
    get:
      tags:
        - Incidents
      summary: Get Incident By Id
      operationId: getIncidentById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Incidents
      summary: Update Incident By Id
      operationId: updateIncidentById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Incidents
      summary: Delete Incident By Id
      operationId: deleteIncidentById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ai-incident-managements/{id}/archive:
    patch:
      tags:
        - Incidents
      summary: Archive Incident By Id
      operationId: archiveIncidentById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /aiTrustCentre/logo:
    post:
      tags:
        - AI Trust Centre
      summary: Upload company logo
      operationId: uploadCompanyLogo
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - AI Trust Centre
      summary: Delete Company Logo
      operationId: deleteCompanyLogo
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /aiTrustCentre/overview:
    get:
      tags:
        - AI Trust Centre
      summary: Get A I Trust Centre Overview
      operationId: getAITrustCentreOverview
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - AI Trust Centre
      summary: Update A I Trust Overview
      operationId: updateAITrustOverview
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /aiTrustCentre/resources:
    get:
      tags:
        - AI Trust Centre
      summary: Get A I Trust Centre Resources
      operationId: getAITrustCentreResources
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - AI Trust Centre
      summary: Create A I Trust Resource
      operationId: createAITrustResource
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /aiTrustCentre/resources/{id}:
    put:
      tags:
        - AI Trust Centre
      summary: Update A I Trust Resource
      operationId: updateAITrustResource
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - AI Trust Centre
      summary: Delete A I Trust Resource
      operationId: deleteAITrustResource
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /aiTrustCentre/subprocessors:
    get:
      tags:
        - AI Trust Centre
      summary: Get A I Trust Centre Subprocessors
      operationId: getAITrustCentreSubprocessors
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - AI Trust Centre
      summary: Create A I Trust Subprocessor
      operationId: createAITrustSubprocessor
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /aiTrustCentre/subprocessors/{id}:
    put:
      tags:
        - AI Trust Centre
      summary: Update A I Trust Subprocessor
      operationId: updateAITrustSubprocessor
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - AI Trust Centre
      summary: Delete A I Trust Subprocessor
      operationId: deleteAITrustSubprocessor
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /aiTrustCentre/{hash}:
    get:
      tags:
        - AI Trust Centre
      summary: Get A I Trust Centre Public Page
      operationId: getAITrustCentrePublicPage
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
  /aiTrustCentre/{hash}/logo:
    get:
      tags:
        - AI Trust Centre
      summary: Get Company Logo
      operationId: getCompanyLogo
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
  /aiTrustCentre/{hash}/resources/{id}:
    get:
      tags:
        - AI Trust Centre
      summary: Get A I Trust Centre Public Resource
      operationId: getAITrustCentrePublicResource
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
  /approval-requests:
    post:
      tags:
        - Approval Workflows
      summary: Create Approval Request
      operationId: createApprovalRequest
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /approval-requests/all:
    get:
      tags:
        - Approval Workflows
      summary: Get All Approval Requests
      operationId: getAllApprovalRequests
      security:
        - bearerAuth: []
      description: "Requires role: Admin"
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /approval-requests/my-requests:
    get:
      tags:
        - Approval Workflows
      summary: Get My Approval Requests
      operationId: getMyApprovalRequests
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /approval-requests/pending-approvals:
    get:
      tags:
        - Approval Workflows
      summary: Get Pending Approvals
      operationId: getPendingApprovals
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /approval-requests/{id}:
    get:
      tags:
        - Approval Workflows
      summary: Get Approval Request By Id
      operationId: getApprovalRequestById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /approval-requests/{id}/approve:
    post:
      tags:
        - Approval Workflows
      summary: Approve Request
      operationId: approveRequest
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /approval-requests/{id}/reject:
    post:
      tags:
        - Approval Workflows
      summary: Reject Request
      operationId: rejectRequest
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /approval-requests/{id}/withdraw:
    post:
      tags:
        - Approval Workflows
      summary: Withdraw approval request
      operationId: withdrawApprovalRequest
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /approval-workflows:
    get:
      tags:
        - Approval Workflows
      summary: Get All Approval Workflows
      operationId: getAllApprovalWorkflows
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Approval Workflows
      summary: Create Approval Workflow
      operationId: createApprovalWorkflow
      security:
        - bearerAuth: []
      description: "Requires role: Admin"
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /approval-workflows/{id}:
    get:
      tags:
        - Approval Workflows
      summary: Get Approval Workflow By Id
      operationId: getApprovalWorkflowById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - Approval Workflows
      summary: Update Approval Workflow
      operationId: updateApprovalWorkflow
      security:
        - bearerAuth: []
      description: "Requires role: Admin"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
    delete:
      tags:
        - Approval Workflows
      summary: Delete Approval Workflow
      operationId: deleteApprovalWorkflow
      security:
        - bearerAuth: []
      description: "Requires role: Admin"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /assessments:
    get:
      tags:
        - Assessments
      summary: Get All Assessments
      operationId: getAllAssessments
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Assessments
      summary: Create Assessment
      operationId: createAssessment
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /assessments/getAnswers/{id}:
    get:
      tags:
        - Assessments
      summary: Get Answers
      operationId: getAnswers
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /assessments/project/byid/{id}:
    get:
      tags:
        - Assessments
      summary: Get Assessment By Project Id
      operationId: getAssessmentByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /assessments/saveAnswers:
    post:
      tags:
        - Assessments
      summary: Save Answers
      operationId: saveAnswers
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /assessments/updateAnswers/{id}:
    put:
      tags:
        - Assessments
      summary: Update Answers
      operationId: updateAnswers
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /assessments/{id}:
    get:
      tags:
        - Assessments
      summary: Get Assessment By Id
      operationId: getAssessmentById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - Assessments
      summary: Update Assessment By Id
      operationId: updateAssessmentById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Assessments
      summary: Delete Assessment By Id
      operationId: deleteAssessmentById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /audit-ledger:
    get:
      tags:
        - Audit
      summary: Get Audit Ledger
      operationId: getAuditLedger
      security:
        - bearerAuth: []
      description: "Requires role: Admin or SuperAdmin"
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /audit-ledger/verify:
    get:
      tags:
        - Audit
      summary: Verify Audit Ledger
      operationId: verifyAuditLedger
      security:
        - bearerAuth: []
      description: "Requires role: Admin"
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /autoDrivers:
    post:
      tags:
        - Demo Data
      summary: Post Auto Driver
      operationId: postAutoDriver
      security:
        - bearerAuth: []
      description: "Requires role: Admin"
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
    delete:
      tags:
        - Demo Data
      summary: Delete Auto Driver
      operationId: deleteAutoDriver
      security:
        - bearerAuth: []
      description: "Requires role: Admin"
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /automations:
    get:
      tags:
        - Automations
      summary: Get All Automations
      operationId: getAllAutomations
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Automations
      summary: Create Automation
      operationId: createAutomation
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /automations/actions/by-triggerId/{triggerId}:
    get:
      tags:
        - Automations
      summary: Get All Automation Actions By Trigger Id
      operationId: getAllAutomationActionsByTriggerId
      security:
        - bearerAuth: []
      parameters:
        - name: triggerId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /automations/triggers:
    get:
      tags:
        - Automations
      summary: Get All Automation Triggers
      operationId: getAllAutomationTriggers
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /automations/{id}:
    get:
      tags:
        - Automations
      summary: Get Automation By Id
      operationId: getAutomationById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - Automations
      summary: Update Automation
      operationId: updateAutomation
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Automations
      summary: Delete Automation By Id
      operationId: deleteAutomationById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /automations/{id}/history:
    get:
      tags:
        - Automations
      summary: Get Automation History
      operationId: getAutomationHistory
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /automations/{id}/stats:
    get:
      tags:
        - Automations
      summary: Get Automation Stats
      operationId: getAutomationStats
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /ce-marking/{projectId}:
    get:
      tags:
        - CE Marking
      summary: Get C E Marking
      operationId: getCEMarking
      security:
        - bearerAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - CE Marking
      summary: Update C E Marking
      operationId: updateCEMarking
      security:
        - bearerAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /compliance/details/{organizationId}:
    get:
      tags:
        - Compliance
      summary: Get Compliance Details
      operationId: getComplianceDetails
      security:
        - bearerAuth: []
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /compliance/score:
    get:
      tags:
        - Compliance
      summary: Get Compliance Score
      operationId: getComplianceScore
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /compliance/score/{organizationId}:
    get:
      tags:
        - Compliance
      summary: Get Compliance Score By Organization
      operationId: getComplianceScoreByOrganization
      security:
        - bearerAuth: []
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /dashboard:
    get:
      tags:
        - Dashboard
      summary: Get Dashboard Data
      operationId: getDashboardData
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /dataset-bulk-upload/upload:
    post:
      tags:
        - Datasets
      summary: Handle Multer Error
      operationId: handleMulterError
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Editor"
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /dataset-change-history/{id}:
    get:
      tags:
        - Change History
      summary: Get Dataset Change History By Id
      operationId: getDatasetChangeHistoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /datasets:
    get:
      tags:
        - Datasets
      summary: Get All Datasets
      operationId: getAllDatasets
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Datasets
      summary: Create New Dataset
      operationId: createNewDataset
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /datasets/by-model/{modelId}:
    get:
      tags:
        - Datasets
      summary: Get Datasets By Model Id
      operationId: getDatasetsByModelId
      security:
        - bearerAuth: []
      parameters:
        - name: modelId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /datasets/by-project/{projectId}:
    get:
      tags:
        - Datasets
      summary: Get Datasets By Project Id
      operationId: getDatasetsByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /datasets/{id}:
    get:
      tags:
        - Datasets
      summary: Get Dataset By Id
      operationId: getDatasetById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Datasets
      summary: Update Dataset By Id
      operationId: updateDatasetById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Datasets
      summary: Delete Dataset By Id
      operationId: deleteDatasetById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /datasets/{id}/history:
    get:
      tags:
        - Datasets
      summary: Get Dataset History
      operationId: getDatasetHistory
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /entity-graph/annotations:
    post:
      tags:
        - Entity Graph
      summary: Save Annotation
      operationId: saveAnnotation
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    get:
      tags:
        - Entity Graph
      summary: Get Annotations
      operationId: getAnnotations
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /entity-graph/annotations/entity/{entityType}/{entityId}:
    delete:
      tags:
        - Entity Graph
      summary: Delete Annotation By Entity
      operationId: deleteAnnotationByEntity
      security:
        - bearerAuth: []
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /entity-graph/annotations/{entityType}/{entityId}:
    get:
      tags:
        - Entity Graph
      summary: Get Annotation By Entity
      operationId: getAnnotationByEntity
      security:
        - bearerAuth: []
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /entity-graph/annotations/{id}:
    delete:
      tags:
        - Entity Graph
      summary: Delete Annotation
      operationId: deleteAnnotation
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /entity-graph/gap-rules:
    post:
      tags:
        - Entity Graph
      summary: Save Gap Rules
      operationId: saveGapRules
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    get:
      tags:
        - Entity Graph
      summary: Get Gap Rules
      operationId: getGapRules
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Entity Graph
      summary: Reset Gap Rules
      operationId: resetGapRules
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /entity-graph/gap-rules/defaults:
    get:
      tags:
        - Entity Graph
      summary: Get Default Gap Rules
      operationId: getDefaultGapRules
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
  /entity-graph/views:
    post:
      tags:
        - Entity Graph
      summary: Create View
      operationId: createView
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    get:
      tags:
        - Entity Graph
      summary: Get Views
      operationId: getViews
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /entity-graph/views/{id}:
    get:
      tags:
        - Entity Graph
      summary: Get View By Id
      operationId: getViewById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - Entity Graph
      summary: Update View
      operationId: updateView
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Entity Graph
      summary: Delete View
      operationId: deleteView
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/all/assessments/progress:
    get:
      tags:
        - EU AI Act
      summary: Get All Projects Assessment Progress
      operationId: getAllProjectsAssessmentProgress
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/all/compliances/progress:
    get:
      tags:
        - EU AI Act
      summary: Get All Projects Compliance Progress
      operationId: getAllProjectsComplianceProgress
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/assessments/byProjectId/{id}:
    get:
      tags:
        - EU AI Act
      summary: Get Assessments By Project Id
      operationId: getAssessmentsByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - EU AI Act
      summary: Delete Assessments By Project Id
      operationId: deleteAssessmentsByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/assessments/progress/{id}:
    get:
      tags:
        - EU AI Act
      summary: Get Project Assessment Progress
      operationId: getProjectAssessmentProgress
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/compliances/byProjectId/{id}:
    get:
      tags:
        - EU AI Act
      summary: Get Compliances By Project Id
      operationId: getCompliancesByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - EU AI Act
      summary: Delete Compliances By Project Id
      operationId: deleteCompliancesByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/compliances/progress/{id}:
    get:
      tags:
        - EU AI Act
      summary: Get Project Compliance Progress
      operationId: getProjectComplianceProgress
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/controlById:
    get:
      tags:
        - EU AI Act
      summary: Get Control By Id
      operationId: getControlById
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/controlCategories:
    get:
      tags:
        - EU AI Act
      summary: Get All Control Categories
      operationId: getAllControlCategories
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/controls/byControlCategoryId/{id}:
    get:
      tags:
        - EU AI Act
      summary: Get Controls By Control Category Id
      operationId: getControlsByControlCategoryId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/saveAnswer/{id}:
    patch:
      tags:
        - EU AI Act
      summary: Update Question By Id
      operationId: updateQuestionById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/saveControls/{id}:
    patch:
      tags:
        - EU AI Act
      summary: Save Controls
      operationId: saveControls
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/topicById:
    get:
      tags:
        - EU AI Act
      summary: Get Topic By Id
      operationId: getTopicById
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /eu-ai-act/topics:
    get:
      tags:
        - EU AI Act
      summary: Get All Topics
      operationId: getAllTopics
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /evidenceHub:
    get:
      tags:
        - Evidence
      summary: Get All Evidences
      operationId: getAllEvidences
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Evidence
      summary: Create New Evidence
      operationId: createNewEvidence
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /evidenceHub/{id}:
    get:
      tags:
        - Evidence
      summary: Get Evidence By Id
      operationId: getEvidenceById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Evidence
      summary: Update Evidence By Id
      operationId: updateEvidenceById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Evidence
      summary: Delete Evidence By Id
      operationId: deleteEvidenceById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /feature-settings:
    get:
      tags:
        - Settings
      summary: Get Feature Settings
      operationId: getFeatureSettings
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Settings
      summary: Update Feature Settings
      operationId: updateFeatureSettings
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /file-change-history/{id}:
    get:
      tags:
        - Change History
      summary: Get File Change History By Id
      operationId: getFileChangeHistoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /file-manager:
    post:
      tags:
        - Files
      summary: Upload File
      operationId: uploadFile
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Reviewer or Editor"
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
    get:
      tags:
        - Files
      summary: List Files
      operationId: listFiles
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /file-manager/highlighted:
    get:
      tags:
        - Files
      summary: Get Highlighted
      operationId: getHighlighted
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /file-manager/search:
    get:
      tags:
        - Files
      summary: Search Files
      operationId: searchFiles
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /file-manager/with-metadata:
    get:
      tags:
        - Files
      summary: List Files With Metadata
      operationId: listFilesWithMetadata
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /file-manager/{id}:
    get:
      tags:
        - Files
      summary: Download File
      operationId: downloadFile
      security:
        - bearerAuth: []
      description: "Requires role: Admin"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
    delete:
      tags:
        - Files
      summary: Remove File
      operationId: removeFile
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Reviewer or Editor"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /file-manager/{id}/metadata:
    get:
      tags:
        - Files
      summary: Get File Metadata
      operationId: getFileMetadata
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Files
      summary: Update Metadata
      operationId: updateMetadata
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Reviewer or Editor"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /file-manager/{id}/preview:
    get:
      tags:
        - Files
      summary: Preview File
      operationId: previewFile
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /file-manager/{id}/versions:
    get:
      tags:
        - Files
      summary: Get File Version History
      operationId: getFileVersionHistory
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files:
    get:
      tags:
        - Files
      summary: Get User Files Meta Data
      operationId: getUserFilesMetaData
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Files
      summary: Post File Content
      operationId: postFileContent
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files/attach:
    post:
      tags:
        - Files
      summary: Attach File To Entity
      operationId: attachFileToEntity
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files/attach-bulk:
    post:
      tags:
        - Files
      summary: Attach Files To Entity
      operationId: attachFilesToEntity
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files/by-projid/{id}:
    get:
      tags:
        - Files
      summary: Get File Meta By Project Id
      operationId: getFileMetaByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files/detach:
    delete:
      tags:
        - Files
      summary: Detach File From Entity
      operationId: detachFileFromEntity
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files/entity/{framework_type}/{entity_type}/{entity_id}:
    get:
      tags:
        - Files
      summary: Get Entity Files
      operationId: getEntityFiles
      security:
        - bearerAuth: []
      parameters:
        - name: framework_type
          in: path
          required: true
          schema:
            type: string
        - name: entity_type
          in: path
          required: true
          schema:
            type: string
        - name: entity_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files/tree:
    get:
      tags:
        - Files
      summary: Get Folder Tree
      operationId: getFolderTree
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files/uncategorized:
    get:
      tags:
        - Files
      summary: Get Uncategorized Files
      operationId: getUncategorizedFiles
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files/{id}:
    get:
      tags:
        - Files
      summary: Get File Content By Id
      operationId: getFileContentById
      security:
        - bearerAuth: []
      description: "Requires role: Admin"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
    patch:
      tags:
        - Files
      summary: Update Folder
      operationId: updateFolder
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Files
      summary: Delete Folder
      operationId: deleteFolder
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files/{id}/files:
    get:
      tags:
        - Files
      summary: Get Files In Folder
      operationId: getFilesInFolder
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Files
      summary: Assign Files To Folder
      operationId: assignFilesToFolder
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files/{id}/files/{fileId}:
    delete:
      tags:
        - Files
      summary: Remove File From Folder
      operationId: removeFileFromFolder
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: fileId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /files/{id}/path:
    get:
      tags:
        - Files
      summary: Get Folder Path
      operationId: getFolderPath
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /frameworks:
    get:
      tags:
        - Frameworks
      summary: Get All Frameworks
      operationId: getAllFrameworks
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /frameworks/fromProject:
    delete:
      tags:
        - Frameworks
      summary: Delete Framework From Project
      operationId: deleteFrameworkFromProject
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /frameworks/toProject:
    post:
      tags:
        - Frameworks
      summary: Add Framework To Project
      operationId: addFrameworkToProject
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /frameworks/{id}:
    get:
      tags:
        - Frameworks
      summary: Get Framework By Id
      operationId: getFrameworkById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /fria/{friaId}/evidence:
    get:
      tags:
        - FRIA
      summary: Get Fria Evidence
      operationId: getFriaEvidence
      security:
        - bearerAuth: []
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - FRIA
      summary: Link Fria Evidence
      operationId: linkFriaEvidence
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Editor"
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /fria/{friaId}/evidence/{linkId}:
    delete:
      tags:
        - FRIA
      summary: Unlink Fria Evidence
      operationId: unlinkFriaEvidence
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Editor"
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
        - name: linkId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /fria/{friaId}/models:
    get:
      tags:
        - FRIA
      summary: Get Model Links
      operationId: getModelLinks
      security:
        - bearerAuth: []
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /fria/{friaId}/models/{modelId}:
    post:
      tags:
        - FRIA
      summary: Link Model
      operationId: linkModel
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Editor"
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
        - name: modelId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
    delete:
      tags:
        - FRIA
      summary: Unlink Model
      operationId: unlinkModel
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Editor"
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
        - name: modelId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /fria/{friaId}/rights:
    put:
      tags:
        - FRIA
      summary: Update Fria Rights
      operationId: updateFriaRights
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Editor"
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /fria/{friaId}/risk-items:
    get:
      tags:
        - FRIA
      summary: Get Risk Items
      operationId: getRiskItems
      security:
        - bearerAuth: []
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - FRIA
      summary: Add Risk Item
      operationId: addRiskItem
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Editor"
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /fria/{friaId}/risk-items/{itemId}:
    patch:
      tags:
        - FRIA
      summary: Update Risk Item
      operationId: updateRiskItem
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Editor"
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
        - name: itemId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
    delete:
      tags:
        - FRIA
      summary: Delete Risk Item
      operationId: deleteRiskItem
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Editor"
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
        - name: itemId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /fria/{friaId}/submit:
    post:
      tags:
        - FRIA
      summary: Submit Fria
      operationId: submitFria
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Editor"
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /fria/{friaId}/versions:
    get:
      tags:
        - FRIA
      summary: Get Versions
      operationId: getVersions
      security:
        - bearerAuth: []
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /fria/{friaId}/versions/{version}:
    get:
      tags:
        - FRIA
      summary: Get Version
      operationId: getVersion
      security:
        - bearerAuth: []
      parameters:
        - name: friaId
          in: path
          required: true
          schema:
            type: integer
        - name: version
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /fria/{projectId}:
    get:
      tags:
        - FRIA
      summary: Get Fria
      operationId: getFria
      security:
        - bearerAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - FRIA
      summary: Update Fria
      operationId: updateFria
      security:
        - bearerAuth: []
      description: "Requires role: Admin or Editor"
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /health:
    get:
      tags:
        - System
      summary: Health Check
      operationId: healthCheck
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
  /incident-change-history/{incidentId}:
    get:
      tags:
        - Change History
      summary: Get Incident History
      operationId: getIncidentHistory
      security:
        - bearerAuth: []
      parameters:
        - name: incidentId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/forms:
    get:
      tags:
        - Intake Forms
      summary: Get All Intake Forms
      operationId: getAllIntakeForms
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Intake Forms
      summary: Create Intake Form
      operationId: createIntakeForm
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/forms/field-guidance:
    post:
      tags:
        - Intake Forms
      summary: Get Field Guidance
      operationId: getFieldGuidance
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/forms/suggested-questions:
    post:
      tags:
        - Intake Forms
      summary: Get L L M Suggested Questions
      operationId: getLLMSuggestedQuestions
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/forms/{id}:
    get:
      tags:
        - Intake Forms
      summary: Get Intake Form By Id
      operationId: getIntakeFormById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Intake Forms
      summary: Update Intake Form
      operationId: updateIntakeForm
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Intake Forms
      summary: Delete Intake Form
      operationId: deleteIntakeForm
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/forms/{id}/archive:
    post:
      tags:
        - Intake Forms
      summary: Archive Intake Form
      operationId: archiveIntakeForm
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/forms/{id}/preview:
    get:
      tags:
        - Intake Forms
      summary: Preview Form
      operationId: previewForm
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/forms/{id}/submissions:
    get:
      tags:
        - Intake Forms
      summary: Get Form Submissions
      operationId: getFormSubmissions
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/public/by-id/{publicId}:
    get:
      tags:
        - Intake Forms
      summary: Get Public Form By Public Id
      operationId: getPublicFormByPublicId
      parameters:
        - name: publicId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
    post:
      tags:
        - Intake Forms
      summary: Submit Public Form By Public Id
      operationId: submitPublicFormByPublicId
      parameters:
        - name: publicId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "500":
          description: Internal server error
  /intake/public/captcha:
    get:
      tags:
        - Intake Forms
      summary: Get Captcha
      operationId: getCaptcha
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
  /intake/public/{tenantSlug}/{formSlug}:
    get:
      tags:
        - Intake Forms
      summary: Get Public Form
      operationId: getPublicForm
      parameters:
        - name: tenantSlug
          in: path
          required: true
          schema:
            type: string
        - name: formSlug
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
    post:
      tags:
        - Intake Forms
      summary: Submit Public Form
      operationId: submitPublicForm
      parameters:
        - name: tenantSlug
          in: path
          required: true
          schema:
            type: string
        - name: formSlug
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "500":
          description: Internal server error
  /intake/submissions:
    get:
      tags:
        - Intake Forms
      summary: Get Pending Submissions
      operationId: getPendingSubmissions
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/submissions/by-entity/{entityType}/{entityId}:
    get:
      tags:
        - Intake Forms
      summary: Get Submission By Entity
      operationId: getSubmissionByEntity
      security:
        - bearerAuth: []
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/submissions/stats:
    get:
      tags:
        - Intake Forms
      summary: Get Submission Stats
      operationId: getSubmissionStats
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/submissions/{id}:
    get:
      tags:
        - Intake Forms
      summary: Get Submission By Id
      operationId: getSubmissionById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/submissions/{id}/approve:
    post:
      tags:
        - Intake Forms
      summary: Approve Submission
      operationId: approveSubmission
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/submissions/{id}/preview:
    get:
      tags:
        - Intake Forms
      summary: Get Submission Preview
      operationId: getSubmissionPreview
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/submissions/{id}/reject:
    post:
      tags:
        - Intake Forms
      summary: Reject Submission
      operationId: rejectSubmission
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /intake/submissions/{id}/risk-override:
    patch:
      tags:
        - Intake Forms
      summary: Override Submission Risk
      operationId: overrideSubmissionRisk
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /integrations/github/token:
    get:
      tags:
        - Integrations
      summary: Get Git Hub Token Status Controller
      operationId: getGitHubTokenStatusController
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Integrations
      summary: Save Git Hub Token Controller
      operationId: saveGitHubTokenController
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Integrations
      summary: Delete Git Hub Token Controller
      operationId: deleteGitHubTokenController
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /integrations/github/token/test:
    post:
      tags:
        - Integrations
      summary: Test Git Hub Token Controller
      operationId: testGitHubTokenController
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /internal/ai-gateway/notify:
    post:
      tags:
        - Internal
      summary: AI Gateway notification callback
      operationId: aiGatewayNotify
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "500":
          description: Internal server error
  /invitations:
    get:
      tags:
        - Invitations
      summary: Get Invitations
      operationId: getInvitations
      security:
        - bearerAuth: []
      description: "Requires role: Admin or SuperAdmin"
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /invitations/{id}:
    delete:
      tags:
        - Invitations
      summary: Revoke Invitation
      operationId: revokeInvitation
      security:
        - bearerAuth: []
      description: "Requires role: Admin or SuperAdmin"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /invitations/{id}/resend:
    post:
      tags:
        - Invitations
      summary: Resend Invitation
      operationId: resendInvitation
      security:
        - bearerAuth: []
      description: "Requires role: Admin or SuperAdmin"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /iso-27001/all/annexes/progress:
    get:
      tags:
        - ISO 27001
      summary: Get All Projects Annxes Progress
      operationId: getAllProjectsAnnxesProgress
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/all/clauses/progress:
    get:
      tags:
        - ISO 27001
      summary: Get All Projects Clauses Progress
      operationId: getAllProjectsClausesProgress
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/annexControl/byId/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get Annex Control By Id
      operationId: getAnnexControlById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/annexControls/byAnnexId/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get Annex Controls By Annex Id
      operationId: getAnnexControlsByAnnexId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/annexes:
    get:
      tags:
        - ISO 27001
      summary: Get All Annexes
      operationId: getAllAnnexes
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/annexes/assignments/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get Project Annexes Assignments
      operationId: getProjectAnnexesAssignments
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/annexes/byProjectId/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get Annexes By Project Id
      operationId: getAnnexesByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - ISO 27001
      summary: Delete Reference Controls
      operationId: deleteReferenceControls
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/annexes/progress/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get Project Annxes Progress
      operationId: getProjectAnnxesProgress
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/annexes/struct/byProjectId/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get All Annexes Struct For Project
      operationId: getAllAnnexesStructForProject
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/clauses:
    get:
      tags:
        - ISO 27001
      summary: Get All Clauses
      operationId: getAllClauses
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/clauses/assignments/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get Project Clauses Assignments
      operationId: getProjectClausesAssignments
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/clauses/byProjectId/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get Clauses By Project Id
      operationId: getClausesByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - ISO 27001
      summary: Delete Management System Clauses
      operationId: deleteManagementSystemClauses
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/clauses/progress/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get Project Clauses Progress
      operationId: getProjectClausesProgress
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/clauses/struct/byProjectId/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get All Clauses Struct For Project
      operationId: getAllClausesStructForProject
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/saveAnnexes/{id}:
    patch:
      tags:
        - ISO 27001
      summary: Save Annexes
      operationId: saveAnnexes
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/saveClauses/{id}:
    patch:
      tags:
        - ISO 27001
      summary: Save Clauses
      operationId: saveClauses
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/subClause/byId/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get Sub Clause By Id
      operationId: getSubClauseById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-27001/subClauses/byClauseId/{id}:
    get:
      tags:
        - ISO 27001
      summary: Get Sub Clauses By Clause Id
      operationId: getSubClausesByClauseId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/all/annexes/progress:
    get:
      tags:
        - ISO 42001
      summary: Get All Projects Annxes Progress
      operationId: iso_42001_getAllProjectsAnnxesProgress
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/all/clauses/progress:
    get:
      tags:
        - ISO 42001
      summary: Get All Projects Clauses Progress
      operationId: iso_42001_getAllProjectsClausesProgress
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/annexCategories/byAnnexId/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get Annex Categories By Annex Id
      operationId: getAnnexCategoriesByAnnexId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/annexCategories/{id}/risks:
    get:
      tags:
        - ISO 42001
      summary: Get Annex Category Risks
      operationId: getAnnexCategoryRisks
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/annexCategory/byId/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get Annex Category By Id
      operationId: getAnnexCategoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/annexes:
    get:
      tags:
        - ISO 42001
      summary: Get All Annexes
      operationId: iso_42001_getAllAnnexes
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/annexes/assignments/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get Project Annexes Assignments
      operationId: iso_42001_getProjectAnnexesAssignments
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/annexes/byProjectId/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get Annexes By Project Id
      operationId: iso_42001_getAnnexesByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - ISO 42001
      summary: Delete Reference Controls
      operationId: iso_42001_deleteReferenceControls
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/annexes/progress/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get Project Annxes Progress
      operationId: iso_42001_getProjectAnnxesProgress
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/annexes/struct/byProjectId/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get All Annexes Struct For Project
      operationId: iso_42001_getAllAnnexesStructForProject
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/clauses:
    get:
      tags:
        - ISO 42001
      summary: Get All Clauses
      operationId: iso_42001_getAllClauses
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/clauses/assignments/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get Project Clauses Assignments
      operationId: iso_42001_getProjectClausesAssignments
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/clauses/byProjectId/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get Clauses By Project Id
      operationId: iso_42001_getClausesByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - ISO 42001
      summary: Delete Management System Clauses
      operationId: iso_42001_deleteManagementSystemClauses
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/clauses/progress/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get Project Clauses Progress
      operationId: iso_42001_getProjectClausesProgress
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/clauses/struct/byProjectId/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get All Clauses Struct For Project
      operationId: iso_42001_getAllClausesStructForProject
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/saveAnnexes/{id}:
    patch:
      tags:
        - ISO 42001
      summary: Save Annexes
      operationId: iso_42001_saveAnnexes
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/saveClauses/{id}:
    patch:
      tags:
        - ISO 42001
      summary: Save Clauses
      operationId: iso_42001_saveClauses
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/subClause/byId/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get Sub Clause By Id
      operationId: iso_42001_getSubClauseById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/subClauses/byClauseId/{id}:
    get:
      tags:
        - ISO 42001
      summary: Get Sub Clauses By Clause Id
      operationId: iso_42001_getSubClausesByClauseId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /iso-42001/subclauses/{id}/risks:
    get:
      tags:
        - ISO 42001
      summary: Get Sub Clause Risks
      operationId: getSubClauseRisks
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /llm-keys:
    get:
      tags:
        - LLM Keys
      summary: Get L L M Keys
      operationId: getLLMKeys
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - LLM Keys
      summary: Create L L M Key
      operationId: createLLMKey
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /llm-keys/status:
    get:
      tags:
        - LLM Keys
      summary: Get L L M Key Status
      operationId: getLLMKeyStatus
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /llm-keys/{id}:
    patch:
      tags:
        - LLM Keys
      summary: Update L L M Key
      operationId: updateLLMKey
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - LLM Keys
      summary: Delete L L M Key
      operationId: deleteLLMKey
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /llm-keys/{name}:
    get:
      tags:
        - LLM Keys
      summary: Get L L M Key
      operationId: getLLMKey
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /logger/events:
    get:
      tags:
        - System
      summary: Get Events
      operationId: getEvents
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /logger/logs:
    get:
      tags:
        - System
      summary: Get Logs
      operationId: getLogs
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /mail/invite:
    post:
      tags:
        - Mail
      summary: Invite Limiter
      operationId: inviteLimiter
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /mail/reset-password:
    post:
      tags:
        - Mail
      summary: Email
      operationId: email
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "500":
          description: Internal server error
  /model-risk-change-history/{id}:
    get:
      tags:
        - Change History
      summary: Get Model Risk Change History By Id
      operationId: getModelRiskChangeHistoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /modelInventory:
    get:
      tags:
        - Model Inventory
      summary: Get all model inventories
      description: >
        Returns every model inventory record belonging to the caller's organization,
        ordered by created_at DESC, id ASC. Each record includes its associated
        project and framework IDs.
      operationId: getAllModelInventories
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of model inventories (may be empty)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ModelInventoryResponse"
        "401":
          description: Missing or invalid JWT
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
    post:
      tags:
        - Model Inventory
      summary: Create a new model inventory
      description: >
        Creates a model inventory record, links it to the supplied project and
        framework IDs, records a change-history entry, fires any "model_added"
        automations, and notifies the approver (if set).
      operationId: createNewModelInventory
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModelInventoryCreateRequest"
      responses:
        "201":
          description: Model inventory created
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Created
                  data:
                    $ref: "#/components/schemas/ModelInventoryResponse"
        "401":
          description: Missing or invalid JWT
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /modelInventory/evaluations:
    get:
      tags:
        - Model Inventory
      summary: Get All Model Evaluations
      operationId: getAllModelEvaluations
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /modelInventory/{id}/evaluations:
    get:
      tags:
        - Model Inventory
      summary: Get Model Evaluations
      operationId: getModelEvaluations
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /modelInventory/by-frameworkId/{frameworkId}:
    get:
      tags:
        - Model Inventory
      summary: Get model inventories by framework ID
      description: >
        Returns all model inventories associated with a framework (via the
        model_inventories_projects_frameworks join table where framework_id matches).
      operationId: getModelByFrameworkId
      security:
        - bearerAuth: []
      parameters:
        - name: frameworkId
          in: path
          required: true
          description: Framework ID
          schema:
            type: integer
      responses:
        "200":
          description: List of model inventories for the framework (may be empty)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ModelInventoryResponse"
        "401":
          description: Missing or invalid JWT
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /modelInventory/by-projectId/{projectId}:
    get:
      tags:
        - Model Inventory
      summary: Get model inventories by project ID
      description: >
        Returns all model inventories associated with a project (via the
        model_inventories_projects_frameworks join table where framework_id IS NULL).
        Non-numeric project IDs (e.g. plugin-sourced) return an empty array.
      operationId: getModelByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          description: Project ID (integer). Non-numeric values return an empty array.
          schema:
            type: integer
      responses:
        "200":
          description: List of model inventories for the project (may be empty)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ModelInventoryResponse"
        "401":
          description: Missing or invalid JWT
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /modelInventory/{id}:
    get:
      tags:
        - Model Inventory
      summary: Get a model inventory by ID
      description: >
        Returns a single model inventory record with its associated project and
        framework IDs. Returns 204 if the record does not exist.
      operationId: getModelInventoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Model inventory ID
          schema:
            type: integer
      responses:
        "200":
          description: Model inventory found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/ModelInventoryResponse"
        "204":
          description: No model inventory found for the given ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: No Content
                  data:
                    nullable: true
        "401":
          description: Missing or invalid JWT
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
    patch:
      tags:
        - Model Inventory
      summary: Update a model inventory by ID
      description: >
        Partially updates a model inventory record. All body fields are optional;
        only provided fields are changed. Project and framework associations can be
        replaced or cleared. Fires "model_updated" automations and notifies a new
        approver if changed.
      operationId: updateModelInventoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Model inventory ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModelInventoryUpdateRequest"
      responses:
        "200":
          description: Model inventory updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/ModelInventoryResponse"
        "401":
          description: Missing or invalid JWT
        "404":
          description: Model inventory not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not Found
                  data:
                    type: string
                    example: Model inventory not found
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
    delete:
      tags:
        - Model Inventory
      summary: Delete a model inventory by ID
      description: >
        Deletes a model inventory record and its project/framework associations.
        Optionally deletes linked model risks when deleteRisks=true.
        Records deletion in change history and fires "model_deleted" automations.
      operationId: deleteModelInventoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Model inventory ID
          schema:
            type: integer
        - name: deleteRisks
          in: query
          required: false
          description: >
            When "true", also deletes associated rows from the model_risks table.
          schema:
            type: string
            enum:
              - "true"
              - "false"
            default: "false"
      responses:
        "200":
          description: Model inventory deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: string
                    example: Model inventory deleted successfully
        "401":
          description: Missing or invalid JWT
        "404":
          description: Model inventory not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not Found
                  data:
                    type: string
                    example: Model inventory not found
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /modelInventoryHistory/current-counts:
    get:
      tags:
        - Model Inventory
      summary: Get Current Counts
      operationId: getCurrentCounts
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /modelInventoryHistory/snapshot:
    post:
      tags:
        - Model Inventory
      summary: Create Snapshot
      operationId: createSnapshot
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /modelInventoryHistory/timeseries:
    get:
      tags:
        - Model Inventory
      summary: Get Timeseries
      operationId: getTimeseries
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /modelRisks:
    get:
      tags:
        - Model Risks
      summary: Get All Model Risks
      operationId: getAllModelRisks
      security:
        - bearerAuth: []
      parameters:
        - name: filter
          in: query
          required: false
          schema:
            type: string
            enum: [active, deleted, all]
            default: active
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ModelRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Model Risks
      summary: Create New Model Risk
      operationId: createNewModelRisk
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModelRiskInput"
      responses:
        "201":
          description: Created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/ModelRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /modelRisks/{id}:
    get:
      tags:
        - Model Risks
      summary: Get Model Risk By Id
      operationId: getModelRiskById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/ModelRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - Model Risks
      summary: Update Model Risk By Id
      operationId: updateModelRiskById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModelRiskInput"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/ModelRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Model Risks
      summary: Update Model Risk By Id
      operationId: modelRisks_updateModelRiskById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModelRiskInput"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/ModelRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Model Risks
      summary: Delete Model Risk By Id
      operationId: deleteModelRiskById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/assignments:
    get:
      tags:
        - NIST AI RMF
      summary: Get N I S T A I R M F Assignments
      operationId: getNISTAIRMFAssignments
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/assignments-by-function:
    get:
      tags:
        - NIST AI RMF
      summary: Get N I S T A I R M F Assignments By Function
      operationId: getNISTAIRMFAssignmentsByFunction
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/categories/{title}:
    get:
      tags:
        - NIST AI RMF
      summary: Get All N I S T A I R M F Categories Byfunction Id
      operationId: getAllNISTAIRMFCategoriesByfunctionId
      security:
        - bearerAuth: []
      parameters:
        - name: title
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/functions:
    get:
      tags:
        - NIST AI RMF
      summary: Get All N I S T A I R M Ffunctions
      operationId: getAllNISTAIRMFfunctions
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/functions/{id}:
    get:
      tags:
        - NIST AI RMF
      summary: Get N I S T A I R M Ffunction By Id
      operationId: getNISTAIRMFfunctionById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/overview:
    get:
      tags:
        - NIST AI RMF
      summary: Get N I S T A I R M F Overview
      operationId: getNISTAIRMFOverview
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/progress:
    get:
      tags:
        - NIST AI RMF
      summary: Get N I S T A I R M F Progress
      operationId: getNISTAIRMFProgress
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/progress-by-function:
    get:
      tags:
        - NIST AI RMF
      summary: Get N I S T A I R M F Progress By Function
      operationId: getNISTAIRMFProgressByFunction
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/status-breakdown:
    get:
      tags:
        - NIST AI RMF
      summary: Get N I S T A I R M F Status Breakdown
      operationId: getNISTAIRMFStatusBreakdown
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/subcategories/byId/{id}:
    get:
      tags:
        - NIST AI RMF
      summary: Get N I S T A I R M F Subcategory By Id
      operationId: getNISTAIRMFSubcategoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/subcategories/{categoryId}/{title}:
    get:
      tags:
        - NIST AI RMF
      summary: Get All N I S T A I R M F Subcategories Bycategory Id Andtitle
      operationId: getAllNISTAIRMFSubcategoriesBycategoryIdAndtitle
      security:
        - bearerAuth: []
      parameters:
        - name: categoryId
          in: path
          required: true
          schema:
            type: integer
        - name: title
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/subcategories/{id}:
    patch:
      tags:
        - NIST AI RMF
      summary: Update N I S T A I R M F Subcategory By Id
      operationId: updateNISTAIRMFSubcategoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/subcategories/{id}/risks:
    get:
      tags:
        - NIST AI RMF
      summary: Get N I S T A I R M F Subcategory Risks
      operationId: getNISTAIRMFSubcategoryRisks
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /nist-ai-rmf/subcategories/{id}/status:
    patch:
      tags:
        - NIST AI RMF
      summary: Update N I S T A I R M F Subcategory Status
      operationId: updateNISTAIRMFSubcategoryStatus
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /notes:
    post:
      tags:
        - Notes
      summary: Create Note
      operationId: createNote
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    get:
      tags:
        - Notes
      summary: Get Notes
      operationId: getNotes
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /notes/{id}:
    put:
      tags:
        - Notes
      summary: Update Note
      operationId: updateNote
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Notes
      summary: Delete Note
      operationId: deleteNote
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /notifications:
    get:
      tags:
        - Notifications
      summary: Get Notifications
      operationId: getNotifications
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /notifications/read-all:
    patch:
      tags:
        - Notifications
      summary: Mark All As Read
      operationId: markAllAsRead
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /notifications/stream:
    get:
      tags:
        - Notifications
      summary: Stream Notifications
      operationId: streamNotifications
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /notifications/summary:
    get:
      tags:
        - Notifications
      summary: Get Notification Summary
      operationId: getNotificationSummary
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /notifications/unread-count:
    get:
      tags:
        - Notifications
      summary: Get Unread Count
      operationId: getUnreadCount
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /notifications/{id}:
    delete:
      tags:
        - Notifications
      summary: Delete Notification
      operationId: deleteNotification
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /notifications/{id}/read:
    patch:
      tags:
        - Notifications
      summary: Mark As Read
      operationId: markAsRead
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /organizations:
    post:
      tags:
        - Organizations
      summary: Create Organization
      operationId: createOrganization
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /organizations/exists:
    get:
      tags:
        - Organizations
      summary: Get Organizations Exists
      operationId: getOrganizationsExists
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
  /organizations/{id}:
    get:
      tags:
        - Organizations
      summary: Get Organization By Id
      operationId: getOrganizationById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Organizations
      summary: Update Organization By Id
      operationId: updateOrganizationById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Organizations
      summary: Delete Organization By Id
      operationId: deleteOrganizationById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /organizations/{id}/onboarding-status:
    patch:
      tags:
        - Organizations
      summary: Update Onboarding Status
      operationId: updateOnboardingStatus
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /plugins/categories:
    get:
      tags:
        - Plugins
      summary: Get Categories
      operationId: getCategories
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /plugins/install:
    post:
      tags:
        - Plugins
      summary: Install Plugin
      operationId: installPlugin
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /plugins/installations:
    get:
      tags:
        - Plugins
      summary: Get Installed Plugins
      operationId: getInstalledPlugins
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /plugins/installations/{id}:
    delete:
      tags:
        - Plugins
      summary: Uninstall Plugin
      operationId: uninstallPlugin
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /plugins/installations/{id}/configuration:
    put:
      tags:
        - Plugins
      summary: Update Plugin Configuration
      operationId: updatePluginConfiguration
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /plugins/marketplace:
    get:
      tags:
        - Plugins
      summary: Get All Plugins
      operationId: getAllPlugins
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /plugins/marketplace/search:
    get:
      tags:
        - Plugins
      summary: Search Plugins
      operationId: searchPlugins
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /plugins/marketplace/{key}:
    get:
      tags:
        - Plugins
      summary: Get Plugin By Key
      operationId: getPluginByKey
      security:
        - bearerAuth: []
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /plugins/{key}/test-connection:
    post:
      tags:
        - Plugins
      summary: Test Plugin Connection
      operationId: testPluginConnection
      security:
        - bearerAuth: []
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /plugins/{key}/ui/dist/{filename}:
    get:
      tags:
        - Plugins
      summary: Serve plugin UI assets
      operationId: servePluginUI
      security:
        - bearerAuth: []
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
        - name: filename
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/active-cycle/{projectId}:
    get:
      tags:
        - Post-Market Monitoring
      summary: Get Active Cycle
      operationId: getActiveCycle
      security:
        - bearerAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/config:
    post:
      tags:
        - Post-Market Monitoring
      summary: Create Config
      operationId: createConfig
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/config/{configId}:
    put:
      tags:
        - Post-Market Monitoring
      summary: Update Config
      operationId: updateConfig
      security:
        - bearerAuth: []
      parameters:
        - name: configId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Post-Market Monitoring
      summary: Delete Config
      operationId: deleteConfig
      security:
        - bearerAuth: []
      parameters:
        - name: configId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/config/{configId}/questions:
    get:
      tags:
        - Post-Market Monitoring
      summary: Get Questions
      operationId: getQuestions
      security:
        - bearerAuth: []
      parameters:
        - name: configId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Post-Market Monitoring
      summary: Add Question
      operationId: addQuestion
      security:
        - bearerAuth: []
      parameters:
        - name: configId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/config/{projectId}:
    get:
      tags:
        - Post-Market Monitoring
      summary: Get Config By Project Id
      operationId: getConfigByProjectId
      security:
        - bearerAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/cycles/{cycleId}:
    get:
      tags:
        - Post-Market Monitoring
      summary: Get Cycle By Id
      operationId: getCycleById
      security:
        - bearerAuth: []
      parameters:
        - name: cycleId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/cycles/{cycleId}/flag:
    post:
      tags:
        - Post-Market Monitoring
      summary: Flag Concern
      operationId: flagConcern
      security:
        - bearerAuth: []
      parameters:
        - name: cycleId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/cycles/{cycleId}/reassign:
    post:
      tags:
        - Post-Market Monitoring
      summary: Reassign Stakeholder
      operationId: reassignStakeholder
      security:
        - bearerAuth: []
      parameters:
        - name: cycleId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/cycles/{cycleId}/responses:
    get:
      tags:
        - Post-Market Monitoring
      summary: Get Responses
      operationId: getResponses
      security:
        - bearerAuth: []
      parameters:
        - name: cycleId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Post-Market Monitoring
      summary: Save Responses
      operationId: saveResponses
      security:
        - bearerAuth: []
      parameters:
        - name: cycleId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/cycles/{cycleId}/submit:
    post:
      tags:
        - Post-Market Monitoring
      summary: Submit Cycle
      operationId: submitCycle
      security:
        - bearerAuth: []
      parameters:
        - name: cycleId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/org/questions:
    get:
      tags:
        - Post-Market Monitoring
      summary: Get Questions
      operationId: pmm_getQuestions
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/projects/{projectId}/start-cycle:
    post:
      tags:
        - Post-Market Monitoring
      summary: Start New Cycle
      operationId: startNewCycle
      security:
        - bearerAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/questions/reorder:
    post:
      tags:
        - Post-Market Monitoring
      summary: Reorder Questions
      operationId: reorderQuestions
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/questions/{questionId}:
    put:
      tags:
        - Post-Market Monitoring
      summary: Update Question
      operationId: updateQuestion
      security:
        - bearerAuth: []
      parameters:
        - name: questionId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Post-Market Monitoring
      summary: Delete Question
      operationId: deleteQuestion
      security:
        - bearerAuth: []
      parameters:
        - name: questionId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/reports:
    get:
      tags:
        - Post-Market Monitoring
      summary: Get Reports
      operationId: getReports
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /pmm/reports/{reportId}/download:
    get:
      tags:
        - Post-Market Monitoring
      summary: Download Report
      operationId: downloadReport
      security:
        - bearerAuth: []
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /policies:
    get:
      tags:
        - Policies
      summary: Get all policies
      description: Returns all policies for the authenticated user's organization, including assigned reviewer IDs.
      operationId: getAllPolicies
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of policies retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/PolicyWithReviewers"
        "500":
          $ref: "#/components/responses/InternalServerError"
    post:
      tags:
        - Policies
      summary: Create a new policy
      description: Creates a new policy. The author_id and last_updated_by are set from the JWT token automatically.
      operationId: createPolicy
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PolicyCreateRequest"
      responses:
        "201":
          description: Policy created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Created
                  data:
                    $ref: "#/components/schemas/PolicyWithReviewers"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: Service unavailable — policy creation failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /policies/tags:
    get:
      tags:
        - Policies
      summary: Get available policy tags
      description: Returns the static list of allowed policy tags.
      operationId: getPolicyTags
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of available tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: array
                    items:
                      type: string
                      enum:
                        - AI ethics
                        - Fairness
                        - Transparency
                        - Explainability
                        - Bias mitigation
                        - Privacy
                        - Data governance
                        - Model risk
                        - Accountability
                        - Security
                        - LLM
                        - Human oversight
                        - EU AI Act
                        - ISO 42001
                        - NIST RMF
                        - Red teaming
                        - Audit
                        - Monitoring
                        - Vendor management
        "500":
          $ref: "#/components/responses/InternalServerError"
  /policies/import/docx:
    post:
      tags:
        - Policies
      summary: Import DOCX and convert to HTML
      description: >
        Uploads a .docx file (max 10 MB) and converts it to HTML suitable for
        the policy content editor. Returns the converted HTML and any conversion warnings.
      operationId: importDocx
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: A .docx file (max 10 MB).
      responses:
        "200":
          description: DOCX converted to HTML successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: object
                    properties:
                      html:
                        type: string
                        description: The converted HTML content
                      warnings:
                        type: array
                        items:
                          type: string
                        description: Conversion warnings (e.g., unsupported formatting)
        "400":
          description: Bad request — no file uploaded or invalid file type
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /policies/{id}:
    get:
      tags:
        - Policies
      summary: Get policy by ID
      description: Returns a single policy by its ID, including assigned reviewer IDs.
      operationId: getPolicyById
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PolicyId"
      responses:
        "200":
          description: Policy retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/PolicyWithReviewers"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    put:
      tags:
        - Policies
      summary: Update a policy
      description: >
        Updates an existing policy. Only provided fields are updated.
        The last_updated_by and last_updated_at are set automatically from the JWT token.
        If assigned_reviewer_ids is provided, the reviewer list is fully replaced.
      operationId: updatePolicy
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PolicyId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PolicyUpdateRequest"
      responses:
        "202":
          description: Policy updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Accepted
                  data:
                    $ref: "#/components/schemas/PolicyWithReviewers"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags:
        - Policies
      summary: Delete a policy by ID
      description: Permanently deletes a policy and its associated reviewer mappings (via CASCADE).
      operationId: deletePolicyById
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PolicyId"
      responses:
        "202":
          description: Policy deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Accepted
                  data:
                    type: boolean
                    example: true
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /policies/{id}/export/pdf:
    get:
      tags:
        - Policies
      summary: Export policy as PDF
      description: Generates and downloads the policy as a PDF file.
      operationId: exportPolicyPDF
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PolicyId"
      responses:
        "200":
          description: PDF file stream
          content:
            application/pdf:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              schema:
                type: string
                example: 'attachment; filename="AI_Ethics_Policy.pdf"'
            Content-Length:
              schema:
                type: integer
        "400":
          description: Invalid policy ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /policies/{id}/export/docx:
    get:
      tags:
        - Policies
      summary: Export policy as DOCX
      description: Generates and downloads the policy as a DOCX file.
      operationId: exportPolicyDOCX
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PolicyId"
      responses:
        "200":
          description: DOCX file stream
          content:
            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              schema:
                type: string
                example: 'attachment; filename="AI_Ethics_Policy.docx"'
            Content-Length:
              schema:
                type: integer
        "400":
          description: Invalid policy ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /policies/{id}/review/request:
    post:
      tags:
        - Policies
      summary: Request review for a policy
      description: >
        Sets the policy review status to pending_review and sends in-app
        notifications to each specified reviewer.
      operationId: requestPolicyReview
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PolicyId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reviewer_ids
              properties:
                reviewer_ids:
                  type: array
                  items:
                    type: integer
                  description: List of user IDs to request review from
                  example: [2, 5, 8]
                message:
                  type: string
                  description: Optional message to include in the review request notification
                  example: "Please review the updated data governance section."
      responses:
        "200":
          description: Review requested successfully; returns the updated policy
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/PolicyWithReviewers"
        "400":
          description: Invalid policy ID or missing reviewer_ids
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /policies/{id}/review/approve:
    put:
      tags:
        - Policies
      summary: Approve a policy review
      description: >
        Sets the policy review status to approved and sends an in-app
        notification to the policy author.
      operationId: approvePolicyReview
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PolicyId"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: Optional approval comment
                  example: "Looks good, approved."
      responses:
        "200":
          description: Policy review approved; returns the updated policy
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/PolicyWithReviewers"
        "400":
          description: Invalid policy ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /policies/{id}/review/reject:
    put:
      tags:
        - Policies
      summary: Reject a policy review (request changes)
      description: >
        Sets the policy review status to changes_requested and sends an in-app
        notification to the policy author. A comment is required.
      operationId: rejectPolicyReview
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PolicyId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - comment
              properties:
                comment:
                  type: string
                  description: Reason for requesting changes (required)
                  example: "Section 3 needs more detail on bias mitigation procedures."
      responses:
        "200":
          description: Policy review rejected; returns the updated policy
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/PolicyWithReviewers"
        "400":
          description: Invalid policy ID or missing comment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /policies/folders/{folderId}/policies:
    get:
      tags:
        - Policies
      summary: Get Policies In Folder
      operationId: getPoliciesInFolder
      security:
        - bearerAuth: []
      parameters:
        - name: folderId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /policies/{id}/folders:
    get:
      tags:
        - Policies
      summary: Get Policy Folders
      operationId: getPolicyFolders
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Policies
      summary: Update Policy Folders
      operationId: updatePolicyFolders
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /policy-change-history/{id}:
    get:
      tags:
        - Change History
      summary: Get Policy Change History By Id
      operationId: getPolicyChangeHistoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /projectRisks:
    get:
      tags:
        - Project Risks
      summary: Get All Risks
      operationId: getAllRisks
      security:
        - bearerAuth: []
      parameters:
        - name: filter
          in: query
          required: false
          schema:
            type: string
            enum: [active, deleted, all]
            default: active
          description: Filter by soft-delete state.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProjectRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Project Risks
      summary: Create Risk
      operationId: createRisk
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectRiskInput"
      responses:
        "201":
          description: Created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/ProjectRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /projectRisks/by-frameworkid/{id}:
    get:
      tags:
        - Project Risks
      summary: Get Risks By Framework
      operationId: getRisksByFramework
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: filter
          in: query
          required: false
          schema:
            type: string
            enum: [active, deleted, all]
            default: active
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProjectRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /projectRisks/by-projid/{id}:
    get:
      tags:
        - Project Risks
      summary: Get Risks By Project
      operationId: getRisksByProject
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: filter
          in: query
          required: false
          schema:
            type: string
            enum: [active, deleted, all]
            default: active
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProjectRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /projectRisks/{id}:
    get:
      tags:
        - Project Risks
      summary: Get Risk By Id
      operationId: getRiskById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/ProjectRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - Project Risks
      summary: Update Risk By Id
      operationId: updateRiskById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectRiskInput"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/ProjectRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Project Risks
      summary: Delete Risk By Id
      operationId: deleteRiskById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/ProjectRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /projects:
    get:
      summary: Get all projects
      description: >
        Returns all projects visible to the authenticated user. Admins and SuperAdmins
        see all projects in the organization; other roles see only projects they own or
        are members of.
      operationId: getAllProjects
      tags: [Projects]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of projects retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProjectListItem"
        "401":
          description: Unauthorized — missing or invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
    post:
      summary: Create a new project (use case)
      description: >
        Creates a new project with associated members and frameworks. If an
        approval_workflow_id is provided, framework creation is deferred until
        the approval request is approved.
      operationId: createProject
      tags: [Projects]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProjectRequest"
      responses:
        "201":
          description: Project created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Created
                  data:
                    type: object
                    properties:
                      project:
                        $ref: "#/components/schemas/Project"
                      frameworks:
                        type: object
                        additionalProperties: true
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Business logic error (e.g. framework not allowed)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
        "503":
          description: Service unavailable — project creation returned null
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /projects/all/assessment/progress:
    get:
      summary: Get assessment progress across all projects
      operationId: allProjectsAssessmentProgress
      tags: [Projects]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Aggregated assessment progress returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/AssessmentProgress"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: No projects found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /projects/all/compliance/progress:
    get:
      summary: Get compliance progress across all projects
      operationId: allProjectsComplianceProgress
      tags: [Projects]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Aggregated compliance progress returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/ComplianceProgress"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: No projects found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /projects/assessment/progress/{id}:
    get:
      summary: Get assessment progress for a single project
      operationId: projectAssessmentProgress
      tags: [Projects]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: Assessment progress returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/AssessmentProgress"
        "404":
          description: Project not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /projects/calculateProjectRisks/{id}:
    get:
      summary: Calculate project risk distribution
      operationId: getProjectRisksCalculations
      tags: [Projects]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: Risk calculations returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProjectRiskCount"
        "204":
          description: No risk data available
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: No Content
                  data:
                    nullable: true
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /projects/calculateVendorRisks/{id}:
    get:
      summary: Calculate vendor risk distribution
      operationId: getVendorRisksCalculations
      tags: [Projects]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: Vendor risk calculations returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/VendorRiskCount"
        "204":
          description: No vendor risk data available
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: No Content
                  data:
                    nullable: true
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /projects/complainces/{projid}:
    get:
      summary: Get compliance data for a project
      operationId: getCompliances
      tags: [Projects]
      security:
        - bearerAuth: []
      parameters:
        - name: projid
          in: path
          required: true
          description: The project ID
          schema:
            type: integer
      responses:
        "200":
          description: Compliance data returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ControlCategory"
        "404":
          description: Project not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /projects/compliance/progress/{id}:
    get:
      summary: Get compliance progress for a single project
      operationId: projectComplianceProgress
      tags: [Projects]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: Compliance progress returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/ComplianceProgress"
        "404":
          description: Project not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /projects/saveControls:
    post:
      tags:
        - Projects
      summary: Save Controls
      operationId: projects_saveControls
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /projects/stats/{id}:
    get:
      summary: Get project statistics by ID
      operationId: getProjectStatsById
      tags: [Projects]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "202":
          description: Project stats retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Accepted
                  data:
                    $ref: "#/components/schemas/ProjectStats"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /projects/{id}:
    get:
      summary: Get a project by ID
      description: Returns a single project with its frameworks, owner name, members, and approval status.
      operationId: getProjectById
      tags: [Projects]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: Project found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/ProjectDetail"
        "404":
          description: Project not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
    patch:
      summary: Update a project by ID
      description: Partially updates a project and its member list. Only provided fields are updated.
      operationId: updateProjectById
      tags: [Projects]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProjectRequest"
      responses:
        "202":
          description: Project updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Accepted
                  data:
                    $ref: "#/components/schemas/ProjectWithMembers"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Business logic error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Project not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
    delete:
      summary: Delete a project by ID
      description: Deletes a project and all dependent entities (files, risks, members, framework data).
      operationId: deleteProjectById
      tags: [Projects]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "202":
          description: Project deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Accepted
                  data:
                    type: boolean
                    example: true
        "404":
          description: Project not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /projects/{id}/status:
    patch:
      summary: Update project status
      operationId: updateProjectStatus
      tags: [Projects]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  $ref: "#/components/schemas/ProjectStatus"
      responses:
        "200":
          description: Project status updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/ProjectWithMembers"
        "404":
          description: Project not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
  /quantitative-risks/assessment-mode:
    get:
      tags:
        - Quantitative Risks
      summary: Get Risk Assessment Mode
      operationId: getRiskAssessmentMode
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - Quantitative Risks
      summary: Update Risk Assessment Mode
      operationId: updateRiskAssessmentMode
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /quantitative-risks/portfolio/org:
    get:
      tags:
        - Quantitative Risks
      summary: Get Org Portfolio
      operationId: getOrgPortfolio
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /quantitative-risks/portfolio/project/{projectId}:
    get:
      tags:
        - Quantitative Risks
      summary: Get Project Portfolio
      operationId: getProjectPortfolio
      security:
        - bearerAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /quantitative-risks/portfolio/trend:
    get:
      tags:
        - Quantitative Risks
      summary: Get Portfolio Trend Handler
      operationId: getPortfolioTrendHandler
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /quantitative-risks/{riskId}/apply-benchmark/{benchmarkId}:
    post:
      tags:
        - Quantitative Risks
      summary: Apply Benchmark
      operationId: applyBenchmark
      security:
        - bearerAuth: []
      parameters:
        - name: riskId
          in: path
          required: true
          schema:
            type: integer
        - name: benchmarkId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /questions:
    get:
      tags:
        - Assessments
      summary: Get All Questions
      operationId: getAllQuestions
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Assessments
      summary: Create Question
      operationId: createQuestion
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /questions/bysubtopic/{id}:
    get:
      tags:
        - Assessments
      summary: Get Questions By Subtopic Id
      operationId: getQuestionsBySubtopicId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /questions/bytopic/{id}:
    get:
      tags:
        - Assessments
      summary: Get Questions By Topic Id
      operationId: getQuestionsByTopicId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /questions/{id}:
    get:
      tags:
        - Assessments
      summary: Get Question By Id
      operationId: getQuestionById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Assessments
      summary: Update Question By Id
      operationId: questions_updateQuestionById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Assessments
      summary: Delete Question By Id
      operationId: deleteQuestionById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /reporting/generate-report:
    post:
      tags:
        - Reporting
      summary: Generate Reports
      operationId: generateReports
      security:
        - bearerAuth: []
      description: "Requires role: Admin"
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
    get:
      tags:
        - Reporting
      summary: Get All Generated Reports
      operationId: getAllGeneratedReports
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /reporting/v2/generate-report:
    post:
      tags:
        - Reporting
      summary: Generate Reports V2
      operationId: generateReportsV2
      security:
        - bearerAuth: []
      description: "Requires role: Admin"
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /reporting/{id}:
    delete:
      tags:
        - Reporting
      summary: Delete Generated Report By Id
      operationId: deleteGeneratedReportById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /risk-benchmarks:
    get:
      tags:
        - Risk Benchmarks
      summary: Get All Benchmarks
      operationId: getAllBenchmarks
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /risk-benchmarks/filters:
    get:
      tags:
        - Risk Benchmarks
      summary: Get Benchmark Filters
      operationId: getBenchmarkFilters
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /risk-benchmarks/{id}:
    get:
      tags:
        - Risk Benchmarks
      summary: Get Benchmark By Id
      operationId: getBenchmarkById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /risk-change-history/{projectRiskId}:
    get:
      tags:
        - Change History
      summary: Get Project Risk Change History By Risk Id
      operationId: getProjectRiskChangeHistoryByRiskId
      security:
        - bearerAuth: []
      parameters:
        - name: projectRiskId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /riskHistory/current-counts:
    get:
      tags:
        - Risk History
      summary: Get Current Counts
      operationId: riskHistory_getCurrentCounts
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /riskHistory/snapshot:
    post:
      tags:
        - Risk History
      summary: Create Snapshot
      operationId: riskHistory_createSnapshot
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /riskHistory/timeseries:
    get:
      tags:
        - Risk History
      summary: Get Timeseries
      operationId: riskHistory_getTimeseries
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /roles:
    get:
      tags:
        - Roles
      summary: Get All Roles
      operationId: getAllRoles
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Roles
      summary: Create Role
      operationId: createRole
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /roles/{id}:
    get:
      tags:
        - Roles
      summary: Get Role By Id
      operationId: getRoleById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - Roles
      summary: Update Role By Id
      operationId: updateRoleById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Roles
      summary: Delete Role By Id
      operationId: deleteRoleById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /search:
    get:
      tags:
        - Search
      summary: Search
      operationId: search
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/api-keys:
    post:
      tags:
        - Shadow AI
      summary: Create Api Key
      operationId: createApiKey
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    get:
      tags:
        - Shadow AI
      summary: List Api Keys
      operationId: listApiKeys
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/api-keys/{id}:
    delete:
      tags:
        - Shadow AI
      summary: Revoke Api Key
      operationId: revokeApiKey
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/api-keys/{id}/permanent:
    delete:
      tags:
        - Shadow AI
      summary: Delete Api Key
      operationId: deleteApiKey
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/config/syslog:
    get:
      tags:
        - Shadow AI
      summary: Get Syslog Configs
      operationId: getSyslogConfigs
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Shadow AI
      summary: Create Syslog Config
      operationId: createSyslogConfig
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/config/syslog/{id}:
    patch:
      tags:
        - Shadow AI
      summary: Update Syslog Config
      operationId: updateSyslogConfig
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Shadow AI
      summary: Delete Syslog Config
      operationId: deleteSyslogConfig
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/departments:
    get:
      tags:
        - Shadow AI
      summary: Get Department Activity
      operationId: getDepartmentActivity
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/insights/summary:
    get:
      tags:
        - Shadow AI
      summary: Get Insights Summary
      operationId: getInsightsSummary
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/insights/tools-by-events:
    get:
      tags:
        - Shadow AI
      summary: Get Tools By Events
      operationId: getToolsByEvents
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/insights/tools-by-users:
    get:
      tags:
        - Shadow AI
      summary: Get Tools By Users
      operationId: getToolsByUsers
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/insights/trend:
    get:
      tags:
        - Shadow AI
      summary: Get Trend
      operationId: getTrend
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/insights/users-by-department:
    get:
      tags:
        - Shadow AI
      summary: Get Users By Department
      operationId: getUsersByDepartment
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/rules:
    get:
      tags:
        - Shadow AI
      summary: Get Rules
      operationId: getRules
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Shadow AI
      summary: Create Rule
      operationId: createRule
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/rules/alert-history:
    get:
      tags:
        - Shadow AI
      summary: Get Alert History
      operationId: getAlertHistory
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/rules/{id}:
    patch:
      tags:
        - Shadow AI
      summary: Update Rule
      operationId: updateRule
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Shadow AI
      summary: Delete Rule
      operationId: deleteRule
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/settings:
    get:
      tags:
        - Shadow AI
      summary: Get Settings
      operationId: getSettings
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Shadow AI
      summary: Update Settings
      operationId: updateSettings
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/tools:
    get:
      tags:
        - Shadow AI
      summary: Get Tools
      operationId: getTools
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/tools/{id}:
    get:
      tags:
        - Shadow AI
      summary: Get Tool By Id
      operationId: getToolById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/tools/{id}/start-governance:
    post:
      tags:
        - Shadow AI
      summary: Start Governance
      operationId: startGovernance
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/tools/{id}/status:
    patch:
      tags:
        - Shadow AI
      summary: Update Tool Status
      operationId: updateToolStatus
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/users:
    get:
      tags:
        - Shadow AI
      summary: Get Users
      operationId: getUsers
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shadow-ai/users/{email}/activity:
    get:
      tags:
        - Shadow AI
      summary: Get User Detail
      operationId: getUserDetail
      security:
        - bearerAuth: []
      parameters:
        - name: email
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shares:
    post:
      tags:
        - Share Links
      summary: Create Share Link
      operationId: createShareLink
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shares/token/{token}:
    get:
      tags:
        - Share Links
      summary: Get Share Link By Token
      operationId: getShareLinkByToken
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
  /shares/view/{token}:
    get:
      tags:
        - Share Links
      summary: Get Shared Data By Token
      operationId: getSharedDataByToken
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
  /shares/{id}:
    patch:
      tags:
        - Share Links
      summary: Update Share Link
      operationId: updateShareLink
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Share Links
      summary: Delete Share Link
      operationId: deleteShareLink
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /shares/{resourceType}/{resourceId}:
    get:
      tags:
        - Share Links
      summary: Get Share Links For Resource
      operationId: getShareLinksForResource
      security:
        - bearerAuth: []
      parameters:
        - name: resourceType
          in: path
          required: true
          schema:
            type: string
        - name: resourceId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /slackWebhooks:
    get:
      tags:
        - Integrations
      summary: Get All Slack Webhooks
      operationId: getAllSlackWebhooks
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Integrations
      summary: Create New Slack Webhook
      operationId: createNewSlackWebhook
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /slackWebhooks/{id}:
    get:
      tags:
        - Integrations
      summary: Get Slack Webhook By Id
      operationId: getSlackWebhookById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Integrations
      summary: Update Slack Webhook By Id
      operationId: updateSlackWebhookById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Integrations
      summary: Delete Slack Webhook By Id
      operationId: deleteSlackWebhookById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /slackWebhooks/{id}/send:
    post:
      tags:
        - Integrations
      summary: Send Slack Message
      operationId: sendSlackMessage
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /subscriptions:
    get:
      tags:
        - Subscriptions
      summary: Get Subscription Controller
      operationId: getSubscriptionController
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Subscriptions
      summary: Create Subscription Controller
      operationId: createSubscriptionController
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /subscriptions/{id}:
    put:
      tags:
        - Subscriptions
      summary: Update Subscription Controller
      operationId: updateSubscriptionController
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /super-admin/organizations:
    get:
      tags:
        - Super Admin
      summary: List Organizations
      operationId: listOrganizations
      security:
        - bearerAuth: []
      description: "Requires role: Super Admin"
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
    post:
      tags:
        - Super Admin
      summary: Create Org
      operationId: createOrg
      security:
        - bearerAuth: []
      description: "Requires role: Super Admin"
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /super-admin/organizations/{id}:
    delete:
      tags:
        - Super Admin
      summary: Delete Org
      operationId: deleteOrg
      security:
        - bearerAuth: []
      description: "Requires role: Super Admin"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
    patch:
      tags:
        - Super Admin
      summary: Update Org
      operationId: updateOrg
      security:
        - bearerAuth: []
      description: "Requires role: Super Admin"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /super-admin/organizations/{id}/invite:
    post:
      tags:
        - Super Admin
      summary: Invite User To Org
      operationId: inviteUserToOrg
      security:
        - bearerAuth: []
      description: "Requires role: Super Admin"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /super-admin/organizations/{id}/users:
    get:
      tags:
        - Super Admin
      summary: List Org Users
      operationId: listOrgUsers
      security:
        - bearerAuth: []
      description: "Requires role: Super Admin"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /super-admin/users:
    get:
      tags:
        - Super Admin
      summary: List All Users
      operationId: listAllUsers
      security:
        - bearerAuth: []
      description: "Requires role: Super Admin"
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /super-admin/users/count:
    get:
      tags:
        - Super Admin
      summary: Get User Count
      operationId: getUserCount
      security:
        - bearerAuth: []
      description: "Requires role: Super Admin"
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /super-admin/users/{id}:
    delete:
      tags:
        - Super Admin
      summary: Remove User
      operationId: removeUser
      security:
        - bearerAuth: []
      description: "Requires role: Super Admin"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - insufficient role
        "500":
          description: Internal server error
  /task-change-history/{id}:
    get:
      tags:
        - Change History
      summary: Get Task Change History By Id
      operationId: getTaskChangeHistoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /tasks:
    get:
      tags:
        - Tasks
      summary: Get All Tasks
      operationId: getAllTasks
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Tasks
      summary: Create Task
      operationId: createTask
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /tasks/{id}:
    get:
      tags:
        - Tasks
      summary: Get Task By Id
      operationId: getTaskById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags:
        - Tasks
      summary: Update Task
      operationId: updateTask
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Tasks
      summary: Delete Task
      operationId: deleteTask
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /tasks/{id}/entities:
    get:
      tags:
        - Tasks
      summary: Get Task Entity Links
      operationId: getTaskEntityLinks
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Tasks
      summary: Add Task Entity Link
      operationId: addTaskEntityLink
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /tasks/{id}/entities/{linkId}:
    delete:
      tags:
        - Tasks
      summary: Remove Task Entity Link
      operationId: removeTaskEntityLink
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: linkId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /tasks/{id}/hard:
    delete:
      tags:
        - Tasks
      summary: Hard Delete Task
      operationId: hardDeleteTask
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /tasks/{id}/restore:
    put:
      tags:
        - Tasks
      summary: Restore Task
      operationId: restoreTask
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /tiers/features/{id}:
    get:
      tags:
        - Subscriptions
      summary: Get Tiers Features
      operationId: getTiersFeatures
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /tokens:
    get:
      tags:
        - Authentication
      summary: Get Api Tokens
      operationId: getApiTokens
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Authentication
      summary: Create Api Token
      operationId: createApiToken
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /tokens/{id}:
    delete:
      tags:
        - Authentication
      summary: Delete Api Token
      operationId: deleteApiToken
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /training:
    get:
      tags:
        - Training
      summary: Get All Training Registar
      operationId: getAllTrainingRegistar
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Training
      summary: Create New Training Registar
      operationId: createNewTrainingRegistar
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /training-change-history/{id}:
    get:
      tags:
        - Change History
      summary: Get Training Change History By Id
      operationId: getTrainingChangeHistoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /training/training-id/{id}:
    get:
      tags:
        - Training
      summary: Get Training Registar By Id
      operationId: getTrainingRegistarById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /training/{id}:
    patch:
      tags:
        - Training
      summary: Update Training Registar By Id
      operationId: updateTrainingRegistarById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Training
      summary: Delete Training Registar By Id
      operationId: deleteTrainingRegistarById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /use-case-change-history/{useCaseId}:
    get:
      tags:
        - Change History
      summary: Get Use Case History
      operationId: getUseCaseHistory
      security:
        - bearerAuth: []
      parameters:
        - name: useCaseId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /user-preferences:
    post:
      tags:
        - Users
      summary: Create User Preferences
      operationId: createUserPreferences
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /user-preferences/{userId}:
    get:
      tags:
        - Users
      summary: Get Preferences By User
      operationId: getPreferencesByUser
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Users
      summary: Update User Preferences
      operationId: updateUserPreferences
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /users:
    get:
      summary: List all users in organization
      description: |
        Returns all users belonging to the authenticated user's organization,
        ordered by created_at DESC, id ASC. Password hashes are excluded.
      tags:
        - Users - CRUD
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Users found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "OK"
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/UserSafe"
        "204":
          description: No users found (empty organization)
        "500":
          description: Internal server error
  /users/by-email/{email}:
    get:
      tags:
        - Users
      summary: Get User By Email
      operationId: getUserByEmail
      parameters:
        - name: email
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
  /users/check/exists:
    get:
      summary: Check if any user exists
      description: |
        Returns a boolean indicating whether any user record exists in the database.
        Used during initial setup flow to determine if onboarding is needed.
      tags:
        - Users - Utility
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Check result
          content:
            application/json:
              schema:
                type: boolean
                example: true
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Internal server error"
  /users/chng-pass/{id}:
    patch:
      summary: Change password (authenticated)
      description: |
        Changes the password for the authenticated user. Requires the current
        password for verification. Protected by selfOnly middleware (users can
        only change their own password). Rate-limited.
      tags:
        - Users - Password
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: User ID (must match authenticated user via selfOnly middleware)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id, currentPassword, newPassword]
              properties:
                id:
                  type: integer
                  description: User ID (must match path parameter)
                  example: 1
                currentPassword:
                  type: string
                  format: password
                  description: Current password for verification
                  example: "OldPassword123!"
                newPassword:
                  type: string
                  format: password
                  description: "Must be 8+ chars with uppercase, lowercase, and digit"
                  example: "NewPassword456!"
      responses:
        "202":
          description: Password changed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Password updated successfully"
                  data:
                    $ref: "#/components/schemas/UserSafe"
        "400":
          description: Validation error (weak password, missing fields)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "403":
          description: Business logic error (wrong current password)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "404":
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "User not found"
        "500":
          description: Internal server error
  /users/login:
    post:
      summary: Authenticate user
      description: |
        Validates email/password credentials via bcrypt. Returns a JWT access token
        in the response body and sets a refresh token in an HTTP-only cookie.
        Rate-limited to 5 requests per minute per IP.
      tags:
        - Users - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                  example: "user@example.com"
                password:
                  type: string
                  format: password
                  example: "SecurePassword123!"
      responses:
        "202":
          description: Authentication successful
          headers:
            Set-Cookie:
              schema:
                type: string
              description: "refresh_token=<jwt>; Path=/api/users; HttpOnly; Secure (prod); SameSite=none (prod) / lax (dev)"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Accepted"
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                        description: JWT access token
                      isSuperAdmin:
                        type: boolean
                        description: Only present when user is super-admin (role_id=5)
                      onboarding_status:
                        type: string
                        description: Organization onboarding status (not present for super-admin)
                        example: "completed"
                      is_org_creator:
                        type: boolean
                        description: Whether user is the first admin of the org (not present for super-admin)
        "401":
          description: Invalid email or password
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
        "429":
          description: Too many login attempts
        "500":
          description: Internal server error
  /users/refresh-token:
    post:
      summary: Refresh access token
      description: |
        Reads the refresh_token from an HTTP-only cookie and issues a new
        JWT access token if the refresh token is still valid.
      tags:
        - Users - Authentication
      security: []
      parameters:
        - in: cookie
          name: refresh_token
          required: true
          schema:
            type: string
          description: JWT refresh token set during login
      responses:
        "200":
          description: New access token issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "OK"
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                        description: New JWT access token
        "400":
          description: Refresh token missing from cookie
        "401":
          description: Invalid refresh token
        "406":
          description: Refresh token expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        example: "Token expired"
        "500":
          description: Internal server error
  /users/register:
    post:
      summary: Register a new user
      description: |
        Creates a new user account. Requires a valid registration JWT (set by registerJWT middleware).
        Validates email uniqueness, password strength, and required fields.
        Marks any pending invitation as accepted after successful creation.
      tags:
        - Users - Registration
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, surname, email, password, roleId, organizationId]
              properties:
                name:
                  type: string
                  description: User's first name
                  example: "John"
                surname:
                  type: string
                  description: User's last name
                  example: "Doe"
                email:
                  type: string
                  format: email
                  example: "john@example.com"
                password:
                  type: string
                  format: password
                  description: "Must be 8+ chars with uppercase, lowercase, and digit"
                  example: "SecurePassword123!"
                roleId:
                  type: integer
                  description: "1=Admin, 2=Reviewer, 3=Editor, 4=Auditor"
                  example: 3
                organizationId:
                  type: integer
                  description: Organization to assign the user to
                  example: 1
      responses:
        "201":
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Created"
                  data:
                    $ref: "#/components/schemas/UserSafe"
        "400":
          description: Validation error (missing fields, weak password, invalid email)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
        "403":
          description: Business logic error
        "409":
          description: User with this email already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
        "500":
          description: Internal server error
  /users/reset-password:
    post:
      summary: Reset user password
      description: |
        Resets the password for a user identified by email. Protected by
        resetPasswordMiddleware (validates reset token/permission).
        Password is hashed via bcrypt before storage.
      tags:
        - Users - Password
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, newPassword]
              properties:
                email:
                  type: string
                  format: email
                  example: "user@example.com"
                newPassword:
                  type: string
                  format: password
                  description: "Must be 8+ chars with uppercase, lowercase, and digit"
                  example: "NewSecure123!"
      responses:
        "202":
          description: Password reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Accepted"
                  data:
                    $ref: "#/components/schemas/UserSafe"
        "400":
          description: Validation error (weak password)
        "403":
          description: Business logic error
        "404":
          description: User not found
        "500":
          description: Internal server error
  /users/{id}:
    get:
      summary: Get user by ID
      description: |
        Retrieves a single user by their numeric ID. Super-admins can access
        any user; regular users can only access users within their organization
        (or their own record).
      tags:
        - Users - CRUD
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: User ID
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "OK"
                  data:
                    $ref: "#/components/schemas/UserSafe"
        "403":
          description: Access denied (user belongs to different organization)
        "404":
          description: User not found
        "500":
          description: Internal server error
    patch:
      summary: Update user by ID
      description: |
        Updates user fields (name, surname, email, roleId, last_login).
        Only provided fields are updated. Organization isolation enforced.
        Sends Slack notification on role change. Sends email notification
        when role changes from Editor (3) to Admin (1).
      tags:
        - Users - CRUD
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: User ID to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: First name
                  example: "Jane"
                surname:
                  type: string
                  description: Last name
                  example: "Smith"
                email:
                  type: string
                  format: email
                  example: "jane@example.com"
                roleId:
                  type: integer
                  description: "New role ID (1=Admin, 2=Reviewer, 3=Editor, 4=Auditor). Can be sent as string."
                  example: 1
                last_login:
                  type: string
                  format: date-time
                  description: Override last login timestamp
              description: All fields are optional; only provided fields are updated
      responses:
        "202":
          description: User updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Accepted"
                  data:
                    $ref: "#/components/schemas/UserSafe"
        "400":
          description: Validation error
        "403":
          description: Access denied or business logic error
        "404":
          description: User not found
        "500":
          description: Internal server error
    delete:
      summary: Delete user by ID
      description: |
        Deletes a user and nullifies all their foreign key references across
        projects, vendors, risks, vendor risks, files, automations, and invitations.
        Also removes the user from projects_members. Demo users and super-admins
        cannot be deleted.
      tags:
        - Users - CRUD
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: User ID to delete
      responses:
        "202":
          description: User deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Accepted"
                  data:
                    type: boolean
                    description: true if deletion succeeded
        "403":
          description: "Forbidden: demo user, super-admin, or wrong organization"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
        "404":
          description: User not found
        "500":
          description: Internal server error
  /users/{id}/calculate-progress:
    get:
      summary: Calculate user project progress
      description: |
        Computes completion metrics across all projects the user is a member of.
        Calculates subcontrol completion (status="Done") and assessment question
        completion (has answer) per project and as aggregated totals.
      tags:
        - Users - Analytics
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: User ID to calculate progress for
      responses:
        "200":
          description: Progress calculated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProgressResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Internal server error"
  /users/{id}/profile-photo:
    post:
      summary: Upload profile photo
      description: |
        Uploads a profile photo for the specified user. The file is stored in the
        tenant-scoped files table. If the user already has a profile photo, the old
        one is deleted and replaced. Uses multer for multipart file handling.
      tags:
        - Users - Profile Photo
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: User ID
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [photo]
              properties:
                photo:
                  type: string
                  format: binary
                  description: Image file (JPEG, PNG, etc.)
      responses:
        "200":
          description: Profile photo uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "OK"
                  data:
                    type: object
                    properties:
                      profile_photo_id:
                        type: integer
                        description: ID of the new file record
        "400":
          description: No file provided
        "403":
          description: Access denied (wrong organization)
        "500":
          description: Internal server error
    get:
      summary: Get profile photo
      description: |
        Returns the profile photo binary content for the specified user.
        The response includes the raw file content and its MIME type.
      tags:
        - Users - Profile Photo
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: User ID
      responses:
        "200":
          description: Profile photo returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "OK"
                  data:
                    type: object
                    properties:
                      content:
                        type: string
                        format: byte
                        description: Base64-encoded file content
                      type:
                        type: string
                        description: MIME type
                        example: "image/png"
        "404":
          description: No profile photo found
        "500":
          description: Internal server error
    delete:
      summary: Delete profile photo
      description: |
        Removes the profile photo from the user record and deletes the associated
        file from the files table.
      tags:
        - Users - Profile Photo
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: User ID
      responses:
        "200":
          description: Profile photo deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "OK"
                  data:
                    type: boolean
                    description: true if photo was deleted
        "500":
          description: Internal server error
  /v1/shadow-ai/events:
    post:
      tags:
        - Shadow AI
      summary: Ingest Events
      operationId: ingestEvents
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "500":
          description: Internal server error
  /vendor-change-history/{id}:
    get:
      tags:
        - Change History
      summary: Get Vendor Change History By Id
      operationId: getVendorChangeHistoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /vendor-risk-change-history/{id}:
    get:
      tags:
        - Change History
      summary: Get Vendor Risk Change History By Id
      operationId: getVendorRiskChangeHistoryById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /vendorRisks:
    post:
      tags:
        - Vendor Risks
      summary: Create Vendor Risk
      operationId: createVendorRisk
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VendorRiskInput"
      responses:
        "201":
          description: Created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/VendorRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /vendorRisks/all:
    get:
      tags:
        - Vendor Risks
      summary: Get All Vendor Risks All Projects
      operationId: getAllVendorRisksAllProjects
      security:
        - bearerAuth: []
      parameters:
        - name: filter
          in: query
          required: false
          schema:
            type: string
            enum: [active, deleted, all]
            default: active
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/VendorRiskAllProjectsResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /vendorRisks/by-projid/{id}:
    get:
      tags:
        - Vendor Risks
      summary: Get All Vendor Risks
      operationId: getAllVendorRisks
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: filter
          in: query
          required: false
          schema:
            type: string
            enum: [active, deleted, all]
            default: active
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/VendorRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /vendorRisks/by-vendorid/{id}:
    get:
      tags:
        - Vendor Risks
      summary: Get All Vendor Risks By Vendor Id
      operationId: getAllVendorRisksByVendorId
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: filter
          in: query
          required: false
          schema:
            type: string
            enum: [active, deleted, all]
            default: active
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/VendorRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /vendorRisks/{id}:
    get:
      tags:
        - Vendor Risks
      summary: Get Vendor Risk By Id
      operationId: getVendorRiskById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/VendorRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Vendor Risks
      summary: Update Vendor Risk By Id
      operationId: updateVendorRiskById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VendorRiskInput"
      responses:
        "202":
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/VendorRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Vendor Risks
      summary: Delete Vendor Risk By Id
      operationId: deleteVendorRiskById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "202":
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/VendorRiskResponse"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /vendors:
    get:
      tags:
        - Vendors
      summary: Get all vendors
      description: Retrieves all vendors for the authenticated user's organization, ordered by creation date descending. Each vendor includes its associated project IDs and the reviewer's full name.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Vendors retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/VendorWithReviewerName"
        "204":
          description: No vendors found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: No Content
                  data:
                    type: "null"
        "401":
          description: Unauthorized - missing or invalid JWT
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal Server Error
                  error:
                    type: string
    post:
      tags:
        - Vendors
      summary: Create a vendor
      description: |
        Creates a new vendor in the authenticated user's organization.
        Validates required fields, checks demo restrictions, associates
        projects via the vendors_projects join table, records creation
        in change history, fires automation triggers (vendor_added),
        and sends in-app assignment notifications to assignee and reviewer.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VendorInput"
      responses:
        "201":
          description: Vendor created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Created
                  data:
                    $ref: "#/components/schemas/Vendor"
        "400":
          description: Validation error (missing or invalid required fields)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Bad Request
                  data:
                    type: string
                    description: Validation error message
        "401":
          description: Unauthorized - missing or invalid JWT
        "403":
          description: Business logic error (e.g. demo vendor restriction)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Forbidden
                  data:
                    type: string
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal Server Error
                  error:
                    type: string
        "503":
          description: Service unavailable - vendor creation returned null
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Service Unavailable
                  error:
                    type: object
  /vendors/project-id/{id}:
    get:
      tags:
        - Vendors
      summary: Get vendors by project ID
      description: Retrieves all vendors associated with a specific project. Returns 404 if the project does not exist.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Project ID
      responses:
        "200":
          description: Vendors retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Vendor"
        "401":
          description: Unauthorized - missing or invalid JWT
        "404":
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not Found
                  data:
                    type: array
                    items: {}
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal Server Error
                  error:
                    type: string
  /vendors/{id}:
    get:
      tags:
        - Vendors
      summary: Get vendor by ID
      description: Retrieves a single vendor by its ID, including associated project IDs.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Vendor ID
      responses:
        "200":
          description: Vendor retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OK
                  data:
                    $ref: "#/components/schemas/Vendor"
        "401":
          description: Unauthorized - missing or invalid JWT
        "404":
          description: Vendor not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not Found
                  data:
                    type: "null"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal Server Error
                  error:
                    type: string
    patch:
      tags:
        - Vendors
      summary: Update a vendor
      description: |
        Partially updates an existing vendor. Only provided fields are updated.
        Review and scorecard fields can be explicitly set to null to clear them.
        Required fields (vendor_name, vendor_provides, website, vendor_contact_person)
        are only updated if they have a non-empty value.
        Records field-level changes in change history, fires automation triggers
        (vendor_updated), and sends in-app notifications when assignee or reviewer changes.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Vendor ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VendorUpdate"
      responses:
        "202":
          description: Vendor updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Accepted
                  data:
                    $ref: "#/components/schemas/Vendor"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Bad Request
                  data:
                    type: string
        "401":
          description: Unauthorized - missing or invalid JWT, or missing userId/role
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
        "403":
          description: Business logic error (e.g. demo vendor restriction)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Forbidden
                  data:
                    type: string
        "404":
          description: Vendor not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not Found
                  data:
                    type: object
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal Server Error
                  error:
                    type: string
    delete:
      tags:
        - Vendors
      summary: Delete a vendor
      description: |
        Deletes a vendor and all associated data in a transaction:
        1. Deletes vendor risks (vendor_risks table)
        2. Deletes project associations (vendors_projects table)
        3. Deletes the vendor record itself
        Fires automation triggers (vendor_deleted).
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Vendor ID
      responses:
        "202":
          description: Vendor deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Accepted
                  data:
                    type: boolean
                    example: true
        "401":
          description: Unauthorized - missing or invalid JWT
        "404":
          description: Vendor not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not Found
                  data:
                    type: object
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal Server Error
                  error:
                    type: string
  /version:
    get:
      tags:
        - System
      summary: Get application version
      operationId: getAppVersion
      responses:
        "200":
          description: Success
        "500":
          description: Internal server error
  /virtual-folders:
    get:
      tags:
        - Files
      summary: Get All Folders
      operationId: virtual_folders_getAllFolders
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Files
      summary: Create Folder
      operationId: virtual_folders_createFolder
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /virtual-folders/tree:
    get:
      tags:
        - Files
      summary: Get Folder Tree
      operationId: virtual_folders_getFolderTree
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /virtual-folders/uncategorized:
    get:
      tags:
        - Files
      summary: Get Uncategorized Files
      operationId: virtual_folders_getUncategorizedFiles
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /virtual-folders/{id}:
    get:
      tags:
        - Files
      summary: Get Folder By Id
      operationId: virtual_folders_getFolderById
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    patch:
      tags:
        - Files
      summary: Update Folder
      operationId: virtual_folders_updateFolder
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags:
        - Files
      summary: Delete Folder
      operationId: virtual_folders_deleteFolder
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /virtual-folders/{id}/files:
    get:
      tags:
        - Files
      summary: Get Files In Folder
      operationId: virtual_folders_getFilesInFolder
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags:
        - Files
      summary: Assign Files To Folder
      operationId: virtual_folders_assignFilesToFolder
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /virtual-folders/{id}/files/{fileId}:
    delete:
      tags:
        - Files
      summary: Remove File From Folder
      operationId: virtual_folders_removeFileFromFolder
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: fileId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Deleted successfully
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /virtual-folders/{id}/path:
    get:
      tags:
        - Files
      summary: Get Folder Path
      operationId: virtual_folders_getFolderPath
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
  /webhooks/github:
    post:
      tags:
        - Webhooks
      summary: Github Webhook Controller
      operationId: githubWebhookController
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created successfully
        "500":
          description: Internal server error