openapi: 3.1.0
info:
  title: Kyverno Policy Reporter ClusterPolicyReports Policies 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: Policies
  description: Policy listing and detail endpoints
paths:
  /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/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
components:
  parameters:
    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
    categoryParam:
      name: category
      in: query
      description: Filter results by policy category
      required: false
      schema:
        type: string
        example: Pod Security Standards
  schemas:
    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
    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'
    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
externalDocs:
  description: Policy Reporter API Reference
  url: https://kyverno.github.io/policy-reporter/core/api-reference/