openapi: 3.1.0
info:
  title: Kyverno Policy Reporter ClusterPolicyReports Results 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/
servers:
- url: http://localhost:8080
  description: Default Policy Reporter server
tags:
- name: Results
  description: Policy result query endpoints
paths:
  /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:
    perPageParam:
      name: perPage
      in: query
      description: Number of results per page
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 250
        default: 20
    severityParam:
      name: severity
      in: query
      description: Filter results by severity level
      required: false
      schema:
        type: string
        enum:
        - info
        - low
        - medium
        - high
        - critical
    ruleParam:
      name: rule
      in: query
      description: Filter results by rule name
      required: false
      schema:
        type: string
        example: check-for-labels
    policyParam:
      name: policy
      in: query
      description: Filter results by policy name
      required: false
      schema:
        type: string
        example: require-labels
    kindParam:
      name: kind
      in: query
      description: Filter results by Kubernetes resource kind
      required: false
      schema:
        type: string
        example: Pod
    sourceParam:
      name: source
      in: query
      description: Filter results by policy source (e.g., kyverno, trivy)
      required: false
      schema:
        type: string
        example: kyverno
    namespaceParam:
      name: namespace
      in: query
      description: Filter results by Kubernetes namespace
      required: false
      schema:
        type: string
        example: default
    statusParam:
      name: status
      in: query
      description: Filter results by result status
      required: false
      schema:
        type: string
        enum:
        - pass
        - fail
        - warn
        - error
        - skip
    categoryParam:
      name: category
      in: query
      description: Filter results by policy category
      required: false
      schema:
        type: string
        example: Pod Security Standards
    pageParam:
      name: page
      in: query
      description: Page number for paginated results (1-based)
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
  schemas:
    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
    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
externalDocs:
  description: Policy Reporter API Reference
  url: https://kyverno.github.io/policy-reporter/core/api-reference/