openapi: 3.2.0
info:
  title: Kubex AWS Analyze API
  version: '1.0'
servers:
- url: https://{host}/api/v2
  variables:
    host:
      default: api.example.com
tags:
- name: AWS Analyze
paths:
  /analysis/cloud/aws/analyze:
    post:
      summary: Onboard AWS account
      operationId: analyzeAws
      description: Initiates AWS CloudWatch data collection and runs optimization analysis. Subsequent data collection and analysis are scheduled nightly. If an analysis already exists, this endpoint re-runs analysis and can update the webhook for result delivery.
      tags:
      - AWS Analyze
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwsAnalyzeRequest'
      responses:
        '200':
          description: Acknowledge request / analysis state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwsAnalyzeResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Authentication failed
        '404':
          description: Resource not found
        '500':
          description: Internal server error
  /analysis/cloud/aws:
    get:
      operationId: listAwsAnalyses
      summary: List AWS accounts being analyzed
      description: Returns the set of analyses that have been created, with details needed to reference them elsewhere.
      tags:
      - AWS Analyze
      responses:
        '200':
          description: List of analyses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AwsAnalysisSummary'
        '401':
          description: Authentication failed
        '500':
          description: Internal server error
components:
  schemas:
    AwsAnalyzeResponse:
      type: object
      properties:
        href:
          type: string
          description: Referenced resource to the analysis entity or status endpoint.
        message:
          type: string
          description: Human-readable message describing the result.
        status:
          type: integer
          description: HTTP response code of the request.
    AwsAnalyzeRequest:
      type: object
      properties:
        accountId:
          type: string
          description: The AWS account ID with the CloudWatch data to collect.
        roleArnName:
          type: string
          description: ARN for the IAM role created in AWS for data collection.
        roleExternalId:
          type: string
          description: External ID specified for Kubex when the IAM role was created.
        connectionName:
          type: string
          description: Optional friendly name for this connection (max 32 chars; must be unique within type).
        triggerAdhocAudit:
          type: string
          description: Optional flag to trigger a one-time 60-day historical audit.
        startDayOffset:
          type: string
          description: Optional start offset from the 60-day maximum for historical collection.
        endDayOffset:
          type: string
          description: Optional end offset from “yesterday” for historical collection.
        webHook:
          $ref: '#/components/schemas/WebHook'
      required:
      - accountId
      - roleArnName
      - roleExternalId
    WebHook:
      type: object
      properties:
        uri:
          type: string
          format: uri
          description: Destination URI to receive results when analysis completes.
        authType:
          type: string
          description: Authentication type for the webhook (e.g., basic, bearer).
        authValue:
          type: string
          description: Authentication credentials/value corresponding to authType.
    AwsAnalysisSummary:
      type: object
      description: Minimal representation of an AWS analysis created by the system.
      properties:
        accountId:
          type: string
          description: AWS account ID linked to the analysis.
        accountName:
          type: string
          description: Friendly account display name, when configured.
        analysisName:
          type: string
          description: Internal name assigned to the analysis (defaults to accountId).
        policyInstanceId:
          type: string
          description: Identifier of the policy instance applied to this analysis.
        policyName:
          type: string
          description: Human-readable policy name applied to the analysis.
        analysisId:
          type: string
          description: Unique identifier for the analysis entity.
        href:
          type: string
          description: Link to the analysis resource.
        analysisStatus:
          type: string
          description: Link to the status endpoint for this analysis.
        analysisResults:
          type: string
          description: Link to the results endpoint for this analysis run.
        analysisCompletedOn:
          type: integer
          format: int64
          description: Unix epoch timestamp (ms) of the latest completed analysis run.