openapi: 3.1.0
info:
  title: Kyverno Policy Reporter API
  description: >-
    The Kyverno Policy Reporter REST API provides endpoints for querying
    PolicyReport and ClusterPolicyReport custom resources generated by Kyverno.
    It exposes policy results, status counts, and resource-level violation data,
    serving as the backend for the Policy Reporter UI. The API enables
    programmatic access to policy compliance status across namespaces and
    clusters.
  version: '2.0.0'
  contact:
    name: Kyverno Community
    url: https://kyverno.io/community/
  termsOfService: https://kyverno.io/
externalDocs:
  description: Policy Reporter API Reference
  url: https://kyverno.github.io/policy-reporter/core/api-reference/
servers:
  - url: http://localhost:8080
    description: Default Policy Reporter server
tags:
  - name: ClusterPolicyReports
    description: Cluster-scoped policy report endpoints
  - name: Health
    description: Health and readiness endpoints
  - name: Namespaces
    description: Namespace listing endpoints
  - name: Policies
    description: Policy listing and detail endpoints
  - name: PolicyReports
    description: Namespaced policy report endpoints
  - name: Results
    description: Policy result query endpoints
  - name: Sources
    description: Policy source listing endpoints
paths:
  /healthz:
    get:
      operationId: getHealthz
      summary: Kyverno Health check
      description: >-
        Returns the health status of the Policy Reporter server. Used by
        Kubernetes liveness and readiness probes to confirm the server is
        operational.
      tags:
        - Health
      responses:
        '200':
          description: Policy Reporter is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '503':
          description: Policy Reporter is not healthy
  /api/v1/targets:
    get:
      operationId: listTargets
      summary: Kyverno List notification targets
      description: >-
        Returns a list of configured notification targets such as Slack, Teams,
        Loki, Elasticsearch, and others. Each target entry includes its name,
        minimum priority filter, and enabled sources.
      tags:
        - Policies
      responses:
        '200':
          description: List of notification targets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Target'
  /api/v1/namespaces:
    get:
      operationId: listNamespaces
      summary: Kyverno List namespaces with policy reports
      description: >-
        Returns a list of namespace names that have associated PolicyReport
        resources. Useful for filtering result queries by namespace.
      tags:
        - Namespaces
      responses:
        '200':
          description: List of namespace names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: default
  /api/v1/sources:
    get:
      operationId: listSources
      summary: Kyverno List policy sources
      description: >-
        Returns a list of policy source names that have generated reports. Policy
        sources include kyverno, kube-bench, trivy, and other policy engines that
        produce PolicyReport resources.
      tags:
        - Sources
      responses:
        '200':
          description: List of policy source names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: kyverno
  /api/v1/policies:
    get:
      operationId: listPolicies
      summary: Kyverno List policies
      description: >-
        Returns a list of policies with result counts grouped by status. Supports
        filtering by namespace, source, and category. Each entry includes counts
        of pass, fail, warn, error, and skip results.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/namespaceParam'
        - $ref: '#/components/parameters/sourceParam'
        - $ref: '#/components/parameters/categoryParam'
      responses:
        '200':
          description: List of policies with result counts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PolicySummary'
  /api/v1/rules:
    get:
      operationId: listRules
      summary: Kyverno List policy rules
      description: >-
        Returns a list of policy rule names that have results across all
        namespaces. Can be filtered by namespace and source to narrow the results.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/namespaceParam'
        - $ref: '#/components/parameters/sourceParam'
      responses:
        '200':
          description: List of policy rule names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: require-labels
  /api/v1/categories:
    get:
      operationId: listCategories
      summary: Kyverno List policy categories
      description: >-
        Returns a list of policy category names used to group related policies.
        Categories are defined in policy metadata and may include values such as
        Pod Security Standards or Best Practices.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/sourceParam'
      responses:
        '200':
          description: List of category names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: Pod Security Standards
  /api/v1/policy-reports:
    get:
      operationId: listPolicyReports
      summary: Kyverno List namespaced policy reports
      description: >-
        Returns a paginated list of PolicyReport resources across all namespaces
        or filtered by a specific namespace. Each report includes summary counts
        and metadata about the namespace and source.
      tags:
        - PolicyReports
      parameters:
        - $ref: '#/components/parameters/namespaceParam'
        - $ref: '#/components/parameters/sourceParam'
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam'
      responses:
        '200':
          description: Paginated list of policy reports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyReportList'
  /api/v1/cluster-policy-reports:
    get:
      operationId: listClusterPolicyReports
      summary: Kyverno List cluster-scoped policy reports
      description: >-
        Returns a paginated list of ClusterPolicyReport resources. These reports
        cover cluster-scoped resources such as Nodes, Namespaces, and
        ClusterRoles that are not bound to a specific namespace.
      tags:
        - ClusterPolicyReports
      parameters:
        - $ref: '#/components/parameters/sourceParam'
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam'
      responses:
        '200':
          description: Paginated list of cluster policy reports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyReportList'
  /api/v1/namespace-scoped/results:
    get:
      operationId: listNamespaceScopedResults
      summary: Kyverno List namespace-scoped policy results
      description: >-
        Returns a paginated list of individual policy result entries from
        PolicyReport resources. Results can be filtered by namespace, policy,
        rule, status, severity, category, source, and resource kind or name.
      tags:
        - Results
      parameters:
        - $ref: '#/components/parameters/namespaceParam'
        - $ref: '#/components/parameters/sourceParam'
        - $ref: '#/components/parameters/policyParam'
        - $ref: '#/components/parameters/ruleParam'
        - $ref: '#/components/parameters/statusParam'
        - $ref: '#/components/parameters/severityParam'
        - $ref: '#/components/parameters/categoryParam'
        - $ref: '#/components/parameters/kindParam'
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam'
      responses:
        '200':
          description: Paginated policy results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyResultList'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/cluster-scoped/results:
    get:
      operationId: listClusterScopedResults
      summary: Kyverno List cluster-scoped policy results
      description: >-
        Returns a paginated list of individual policy result entries from
        ClusterPolicyReport resources. Results can be filtered by policy, rule,
        status, severity, category, source, and resource kind or name.
      tags:
        - Results
      parameters:
        - $ref: '#/components/parameters/sourceParam'
        - $ref: '#/components/parameters/policyParam'
        - $ref: '#/components/parameters/ruleParam'
        - $ref: '#/components/parameters/statusParam'
        - $ref: '#/components/parameters/severityParam'
        - $ref: '#/components/parameters/categoryParam'
        - $ref: '#/components/parameters/kindParam'
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam'
      responses:
        '200':
          description: Paginated cluster-scoped policy results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyResultList'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/namespace-scoped/summary:
    get:
      operationId: getNamespaceScopedSummary
      summary: Kyverno Get namespace-scoped result summary
      description: >-
        Returns aggregated result counts grouped by status for namespace-scoped
        policy reports. Supports the same filtering options as the results
        endpoint. Useful for dashboard and summary views.
      tags:
        - Results
      parameters:
        - $ref: '#/components/parameters/namespaceParam'
        - $ref: '#/components/parameters/sourceParam'
        - $ref: '#/components/parameters/categoryParam'
      responses:
        '200':
          description: Result summary counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultSummary'
  /api/v1/cluster-scoped/summary:
    get:
      operationId: getClusterScopedSummary
      summary: Kyverno Get cluster-scoped result summary
      description: >-
        Returns aggregated result counts grouped by status for cluster-scoped
        policy reports. Supports the same filtering options as the cluster results
        endpoint.
      tags:
        - Results
      parameters:
        - $ref: '#/components/parameters/sourceParam'
        - $ref: '#/components/parameters/categoryParam'
      responses:
        '200':
          description: Cluster result summary counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultSummary'
components:
  parameters:
    namespaceParam:
      name: namespace
      in: query
      description: Filter results by Kubernetes namespace
      required: false
      schema:
        type: string
        example: default
    sourceParam:
      name: source
      in: query
      description: Filter results by policy source (e.g., kyverno, trivy)
      required: false
      schema:
        type: string
        example: kyverno
    policyParam:
      name: policy
      in: query
      description: Filter results by policy name
      required: false
      schema:
        type: string
        example: require-labels
    ruleParam:
      name: rule
      in: query
      description: Filter results by rule name
      required: false
      schema:
        type: string
        example: check-for-labels
    statusParam:
      name: status
      in: query
      description: Filter results by result status
      required: false
      schema:
        type: string
        enum:
          - pass
          - fail
          - warn
          - error
          - skip
    severityParam:
      name: severity
      in: query
      description: Filter results by severity level
      required: false
      schema:
        type: string
        enum:
          - info
          - low
          - medium
          - high
          - critical
    categoryParam:
      name: category
      in: query
      description: Filter results by policy category
      required: false
      schema:
        type: string
        example: Pod Security Standards
    kindParam:
      name: kind
      in: query
      description: Filter results by Kubernetes resource kind
      required: false
      schema:
        type: string
        example: Pod
    pageParam:
      name: page
      in: query
      description: Page number for paginated results (1-based)
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    perPageParam:
      name: perPage
      in: query
      description: Number of results per page
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 250
        default: 20
  schemas:
    HealthStatus:
      type: object
      properties:
        status:
          type: string
          description: Health status of the server
          example: ok
    Target:
      type: object
      description: A notification target configured to receive policy results
      properties:
        name:
          type: string
          description: Name of the notification target
          example: slack
        minimumPriority:
          type: string
          description: Minimum result severity that triggers a notification
          enum:
            - info
            - low
            - medium
            - high
            - critical
          example: medium
        sources:
          type: array
          description: List of policy sources this target receives notifications from
          items:
            type: string
          example:
            - kyverno
        skipExistingOnStartup:
          type: boolean
          description: Whether to skip existing results when the server starts
          example: true
    PolicySummary:
      type: object
      description: A policy with aggregated result counts
      properties:
        policy:
          type: string
          description: Name of the policy
          example: require-labels
        namespace:
          type: string
          description: Namespace of the policy (empty for cluster-scoped)
          example: default
        source:
          type: string
          description: Policy engine that created the policy
          example: kyverno
        category:
          type: string
          description: Category the policy belongs to
          example: Best Practices
        severity:
          type: string
          description: Severity level of the policy
          enum:
            - info
            - low
            - medium
            - high
            - critical
        results:
          $ref: '#/components/schemas/ResultCounts'
    PolicyReportList:
      type: object
      description: Paginated list of policy reports
      properties:
        items:
          type: array
          description: List of policy report summaries
          items:
            $ref: '#/components/schemas/PolicyReport'
        count:
          type: integer
          description: Total number of policy reports matching the query
          example: 42
    PolicyReport:
      type: object
      description: A PolicyReport or ClusterPolicyReport resource summary
      properties:
        name:
          type: string
          description: Name of the policy report resource
          example: cpol-require-labels
        namespace:
          type: string
          description: Namespace of the report (empty for cluster-scoped reports)
          example: default
        source:
          type: string
          description: Policy engine that generated the report
          example: kyverno
        summary:
          $ref: '#/components/schemas/ResultCounts'
        creationTimestamp:
          type: string
          format: date-time
          description: Timestamp when the policy report was created
    PolicyResultList:
      type: object
      description: Paginated list of individual policy results
      properties:
        items:
          type: array
          description: List of individual policy result entries
          items:
            $ref: '#/components/schemas/PolicyResult'
        count:
          type: integer
          description: Total number of results matching the query
          example: 150
    PolicyResult:
      type: object
      description: An individual policy evaluation result for a specific resource
      properties:
        id:
          type: string
          description: Unique identifier for the result
          example: abc123
        policy:
          type: string
          description: Name of the policy that generated the result
          example: require-labels
        rule:
          type: string
          description: Name of the policy rule that generated the result
          example: check-for-labels
        message:
          type: string
          description: Human-readable message describing the result
          example: 'validation error: Label app is required.'
        status:
          type: string
          description: Outcome of the policy evaluation
          enum:
            - pass
            - fail
            - warn
            - error
            - skip
          example: fail
        severity:
          type: string
          description: Severity level of the result
          enum:
            - info
            - low
            - medium
            - high
            - critical
          example: medium
        category:
          type: string
          description: Category of the policy rule
          example: Best Practices
        source:
          type: string
          description: Policy engine source
          example: kyverno
        namespace:
          type: string
          description: Kubernetes namespace of the affected resource
          example: default
        resource:
          $ref: '#/components/schemas/ResourceReference'
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the result was recorded
    ResourceReference:
      type: object
      description: A reference to the Kubernetes resource evaluated by the policy
      properties:
        apiVersion:
          type: string
          description: API version of the resource
          example: v1
        kind:
          type: string
          description: Kind of the Kubernetes resource
          example: Pod
        name:
          type: string
          description: Name of the resource
          example: my-pod
        namespace:
          type: string
          description: Namespace of the resource (empty for cluster-scoped)
          example: default
        uid:
          type: string
          description: UID of the Kubernetes resource
          example: 550e8400-e29b-41d4-a716-446655440000
    ResultCounts:
      type: object
      description: Aggregated counts of policy results grouped by status
      properties:
        pass:
          type: integer
          description: Number of passing results
          example: 45
        fail:
          type: integer
          description: Number of failing results
          example: 3
        warn:
          type: integer
          description: Number of warning results
          example: 1
        error:
          type: integer
          description: Number of error results
          example: 0
        skip:
          type: integer
          description: Number of skipped results
          example: 2
    ResultSummary:
      type: object
      description: Aggregated summary of policy results
      properties:
        items:
          type: array
          description: List of status and count pairs
          items:
            type: object
            properties:
              status:
                type: string
                enum:
                  - pass
                  - fail
                  - warn
                  - error
                  - skip
              count:
                type: integer
                description: Number of results with this status
    Error:
      type: object
      description: An error response
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Invalid query parameter value
      required:
        - message