openapi: 3.1.0
info:
  title: PerfectScale Public API
  description: >-
    PerfectScale provides a public API for managing Kubernetes cost optimization,
    cluster monitoring, workload metrics, and automation audit logs. Available with
    the EXPERT package.
  version: '1.0'
  contact:
    name: PerfectScale Support
    url: https://docs.perfectscale.io/
externalDocs:
  description: Documentation
  url: https://docs.perfectscale.io/api/public-api.md
servers:
  - url: https://api.app.perfectscale.io/public/v1
    description: Production
tags:
  - name: Authentication
    description: Authentication and access tokens
  - name: Clusters
    description: Kubernetes cluster operations
  - name: Workloads
    description: Workload metrics and analysis
  - name: Automation
    description: Automation audit logs
security:
  - bearerAuth: []
paths:
  /auth/public_auth:
    post:
      operationId: authenticate
      summary: Obtain access token
      description: Exchanges client credentials for a JWT bearer token.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - client_id
                - client_secret
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
      responses:
        '200':
          description: Token issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
        '401':
          description: Invalid credentials
  /clusters:
    get:
      operationId: listClusters
      summary: List clusters
      description: Returns all clusters connected to PerfectScale.
      tags:
        - Clusters
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          description: Unauthorized
        '429':
          description: Too many requests
  /clusters/{cluster_uid}:
    get:
      operationId: getCluster
      summary: Get cluster details
      tags:
        - Clusters
      parameters:
        - name: cluster_uid
          in: path
          required: true
          schema:
            type: string
        - name: period
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
        '404':
          description: Not found
    delete:
      operationId: deleteCluster
      summary: Remove cluster
      tags:
        - Clusters
      parameters:
        - name: cluster_uid
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Removed
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /clusters/{cluster_uid}/workloads:
    get:
      operationId: listWorkloads
      summary: List cluster workloads
      description: Returns all workloads with metrics, cost, and optimization policy data.
      tags:
        - Workloads
      parameters:
        - name: cluster_uid
          in: path
          required: true
          schema:
            type: string
        - name: period
          in: query
          schema:
            type: string
            description: Period from 1h to 30d
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
  /automation/audit_logs:
    post:
      operationId: getAutomationAuditLogs
      summary: Retrieve automation audit logs
      description: Returns automation actions from the last 30 days with cursor pagination.
      tags:
        - Automation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  format: date-time
                to:
                  type: string
                  format: date-time
                page_size:
                  type: integer
                after:
                  type: string
                before:
                  type: string
                cluster_uids:
                  type: array
                  items:
                    type: string
                namespaces:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT