Densify GCP Analysis API

openapi: 3.2.0
info:
  title: Densify GCP Analysis API
  version: 1.0.0
  description: 'Operations tagged GCP Analysis across 3 of this provider''s published API definitions: densify-public-cloud-analysis-gcp-analyze-openapi.yaml, densify-public-cloud-analysis-gcp-delete-openapi.yaml, densify-public-cloud-analysis-gcp-results-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{host}
  variables:
    host:
      default: api.example.com
- url: https://{host}/api/v2
  variables:
    host:
      default: hostname.kubex.ai
tags:
- name: GCP Analysis
paths:
  /analysis/gcp/analyze:
    post:
      tags:
      - GCP Analysis
      operationId: analyzeGcp
      summary: Run GCP data collection+analysis, or re-run analysis
      description: '- **Initial run**: provide a GCP service account credential and `projectId`. Schedules

        nightly collection and analysis; can set `connectionName` and a `webHook`.

        - **Re-run**: call again with the same `projectId` (+ optional new `webHook`); does **not**

        collect data.

        - Request is rejected if collection/analysis is in progress or within ~30 minutes of the

        scheduled tasks.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GcpAnalyzeRequest'
            examples:
              initialRun:
                summary: Create connection, collect, analyze, set webhook
                value:
                  connectionName: gcp-testing
                  policyInstanceId: 583e0068-45a3-4c4e-baec-473d4daa4095
                  projectId: pm-testing-608378
                  credential:
                    type: service_account
                    project_id: engineering-183318
                    private_key_id: REDACTED
                    private_key: REDACTED_PRIVATE_KEY_EXAMPLE
                    client_email: '[email protected]'
                    client_id: '28884131006232124'
                    auth_uri: https://accounts.google.com/o/oauth2/auth
                    token_uri: https://oauth2.googleapis.com/token
                    auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
                    client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/…
                  webHook:
                    uri: http://mywebhookserver/webhook/results
                    authType: basic
                    authValue: tester:testerpassword
              rerun:
                summary: Re-run analysis only (no collection)
                value:
                  projectId: pm-testing-608378
                  credential: …same service-account JSON as string or object…
                  webHook:
                    uri: https://example.test/webhook/results
      responses:
        '200':
          description: Accepted / analysis initiated or in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeStatusMessage'
              examples:
                inProgress:
                  value:
                    href: Not available
                    message: Analysis in progress
                    status: 200
        '400':
          description: Invalid parameters.
        '401':
          description: Authentication failed.
        '404':
          description: Resource not found.
        '500':
          description: Internal server error.
    servers:
    - url: https://{host}
      variables:
        host:
          default: api.example.com
  /analysis/cloud/gcp/analyze:
    post:
      tags:
      - GCP Analysis
      operationId: historicalAuditGcp
      summary: Run a once-off historical audit (up to 30 days)
      description: 'Requires an existing connection for the specified project. Collects historical data

        with optional start/end offsets; fails if collection/analysis is running or scheduled

        within ~30 minutes. Offsets are measured from "30 days ago" and "yesterday".'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GcpHistoricalAuditRequest'
            examples:
              audit30dDefault:
                value:
                  credential: …service-account JSON…
                  projectId: pm-testing-608378
                  triggerAdhocAudit: 'true'
              auditCustomRange:
                value:
                  credential: …service-account JSON…
                  projectId: pm-testing-608378
                  triggerAdhocAudit: 'true'
                  startDayOffset: '10'
                  endDayOffset: '5'
      responses:
        '200':
          description: Audit accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeStatusMessage'
        '400':
          description: Invalid parameters.
        '401':
          description: Authentication failed.
        '404':
          description: Resource not found.
        '500':
          description: Internal server error.
    servers:
    - url: https://{host}
      variables:
        host:
          default: api.example.com
  /analysis/cloud/gcp:
    get:
      tags:
      - GCP Analysis
      operationId: listGcpAnalyses
      summary: List all generated GCP analyses
      description: Return analyses with details and links; use this to obtain `analysisId` for other calls.
      responses:
        '200':
          description: Array of analyses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GcpAnalysisItem'
        '401':
          description: Authentication failed.
        '500':
          description: Internal server error.
    servers:
    - url: https://{host}
      variables:
        host:
          default: api.example.com
  /analysis/cloud/gcp/{analysisId}:
    delete:
      tags:
      - GCP Analysis
      operationId: deleteGcpAnalysisAudit
      summary: Delete GCP Cloud Connection and Analysis
      description: 'Deletes the Cloud Connection and Analysis for the specified GCP project.


        This API only supports deletion for GCP projects that have a valid analysisId. If the GCP

        project was not analyzed (for example, unsupported resources or insufficient data), no

        analysisId exists and this API cannot be used. In those cases, delete the cloud connection

        manually and contact support@kubex.ai if assistance is required.'
      parameters:
      - name: analysisId
        in: path
        required: true
        description: The unique referenced ID of the GCP analysis.
        schema:
          type: string
      responses:
        '200':
          description: Delete request acknowledged / completed
        '400':
          description: Invalid parameter or conflicting in-progress operation
        '401':
          description: Authentication failed.
        '404':
          description: Analysis not found.
        '405':
          description: Method not allowed.
        '500':
          description: Internal server error (e.g., data collection in progress).
    servers:
    - url: https://{host}/api/v2
      variables:
        host:
          default: hostname.kubex.ai
  /analysis/cloud/gcp/{analysisId}/results:
    get:
      tags:
      - GCP Analysis
      operationId: listGcpRecommendations
      summary: List recommendations for a GCP analysis
      description: 'Returns a collection of recommendations.

        Content negotiation:

        - `application/json` → JSON recommendation objects

        - `application/terraform-map` → terraform-map objects

        Element filters are standard query pairs (e.g., `recommendationType=Upsize`).

        `includeAttributes=true` returns the `attributes` array.

        `dataQuality` takes a quoted, comma-separated list of workload names; unsupported names yield 400.'
      parameters:
      - name: analysisId
        in: path
        required: true
        description: Unique ID of the GCP analysis.
        schema:
          type: string
      - name: includeAttributes
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: Return system attributes when true.
      - name: dataQuality
        in: query
        required: false
        schema:
          type: string
        description: Quoted, comma-separated workload names for data-quality details.
      - name: recommendationType
        in: query
        required: false
        schema:
          type: string
        description: Filter by recommendation action (e.g., Upsize, Downsize, Modernize, Just Right, Terminate, Not Analyzed, etc.).
      - name: region
        in: query
        required: false
        schema:
          type: string
        description: Filter by GCP region.
      - name: currentType
        in: query
        required: false
        schema:
          type: string
        description: Filter by current instance type.
      - name: serviceType
        in: query
        required: false
        schema:
          type: string
        description: Filter by service type (Compute Engine).
      - name: name
        in: query
        required: false
        schema:
          type: string
        description: Filter by system name.
      - name: entityId
        in: query
        required: false
        schema:
          type: string
        description: Filter by Kubex entity ID.
      - name: accountIdRef
        in: query
        required: false
        schema:
          type: string
        description: Filter by GCP project identifier.
      responses:
        '200':
          description: Collection of recommendations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GcpRecommendation'
            application/terraform-map:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TerraformMapRecommendation'
        '400':
          description: Bad Request (e.g., unsupported `dataQuality` workload).
        '401':
          description: Authentication failed.
        '404':
          description: Analysis not found.
        '500':
          description: Server error.
    servers:
    - url: https://{host}
      variables:
        host:
          default: api.example.com
components:
  schemas:
    WebHook:
      type: object
      additionalProperties: false
      properties:
        uri:
          type: string
          format: uri
        authType:
          type: string
          description: Authentication scheme used by the webhook endpoint (e.g., basic, bearer).
        authValue:
          type: string
          description: Credential value (e.g., user:pass for basic, or token).
      required:
      - uri
    AnalyzeStatusMessage:
      type: object
      properties:
        href:
          type: string
          description: Link to recommendations (if available).
        message:
          type: string
        status:
          type: integer
          format: int32
          description: One of 200, 400, 401, 404, 500.
      required:
      - message
      - status
    GcpHistoricalAuditRequest:
      type: object
      properties:
        credential:
          $ref: '#/components/schemas/CredentialStringOrObject'
        projectId:
          type: string
          description: GCP project ID.
        triggerAdhocAudit:
          type: string
          description: Flag to trigger the once-off historical audit (docs specify string flag).
        startDayOffset:
          type: string
          description: Offset from 30 days in the past for the start of the range.
        endDayOffset:
          type: string
          description: Offset from yesterday for the end of the range.
      required:
      - projectId
      - credential
      - triggerAdhocAudit
    CredentialStringOrObject:
      description: GCP service account credential (inline JSON). Docs show both string and object usage.
      oneOf:
      - type: string
        description: Raw JSON string of the `.json` keyfile
      - type: object
        additionalProperties: true
        description: Parsed JSON object of the keyfile
    GcpAnalysisItem:
      type: object
      properties:
        analysisName:
          type: string
          description: GCP project ID associated with the analysis.
        href:
          type: string
          description: Link
    GcpAnalyzeRequest:
      type: object
      properties:
        connectionName:
          type: string
          maxLength: 32
          description: Unique within GCP connections; defaults to the project ID.
        policyInstanceId:
          type: string
          description: Policy instance to use for analysis (optional, shown in example).
        projectId:
          type: string
          description: GCP project ID to analyze (required even if the credential maps to multiple projects).
        credential:
          $ref: '#/components/schemas/CredentialStringOrObject'
        webHook:
          $ref: '#/components/schemas/WebHook'
      required:
      - projectId
      - credential
    TerraformMapRecommendation:
      type: object
      description: Terraform-map recommendation representation.
      properties:
        provisioningId:
          type: string
          description: Label for the terraform-map recommendation (often from a resource label).
        currentType:
          type: string
        recommendedType:
          type: string
        approvalType:
          type: string
        predictedUptime:
          type: string
        recommendationType:
          type: string
        powerState:
          type: string
        implementationMethod:
          type: string
        savingsEstimate:
          type: string
        effortEstimate:
          type: string
          enum:
          - Moderate
          - Low
          - Very Low
          - None
          - Impossible
        densifyPolicy:
          type: string
    GcpRecommendation:
      type: object
      description: GCP recommendation object (JSON representation).
      properties:
        entityId:
          type: string
          description: Kubex entity ID.
        resourceId:
          type: string
          description: GCP identifier for the Compute Engine system.
        accountIdRef:
          type: string
          description: GCP project ID.
        region:
          type: string
        currentType:
          type: string
        recommendationType:
          type: string
          description: 'Action type (e.g., Just Right, Upsize/Downsize [Optimal Family or same family], Modernize [Optimal Family or same family], Terminate, Not Analyzed).

            '
        recommendedType:
          type: string
        implementationMethod:
          type: string
          description: Self Optimization | Manual | N/A.
        predictedUptime:
          type: number
          description: Percent.
        totalHoursRunning:
          type: string
        totalHours:
          type: string
        name:
          type: string
        rptHref:
          type: string
          format: uri
          description: 'Use Accept: application/octet-stream over HTTPS to download the PDF report.'
        approvalType:
          type: string
        densifyPolicy:
          type: string
        savingsEstimate:
          type: string
          description: Catalog-cost delta (current - recommended); PDF uses predicted uptime in its calc.
        effortEstimate:
          type: string
          enum:
          - Moderate
          - Low
          - Very Low
          - None
          - Impossible
        powerState:
          type: string
        recommendedHostEntityId:
          type: string
        currentCost:
          type: string
        recommendedCost:
          type: string
        serviceType:
          type: string
          description: Compute Engine.
        currentHourlyRate:
          type: string
        recommendedHourlyRate:
          type: string
        attributes:
          type: array
          description: Returned only when includeAttributes=true.
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              value:
                type: string
        recommFirstSeen:
          type: integer
          format: int64
        recommLastSeen:
          type: integer
          format: int64
        recommSeenCount:
          type: integer
        auditInfo:
          type: object
          properties:
            dataCollection:
              type: object
              properties:
                dateFirstAudited:
                  type: integer
                  format: int64
                dateLastAudited:
                  type: integer
                  format: int64
                auditCount:
                  type: integer
            workloadDataLast30:
              type: object
              properties:
                firstDate:
                  type: integer
                  format: int64
                lastDate:
                  type: integer
                  format: int64
                totalDays:
                  type: integer
                seenDays:
                  type: integer
        dataQuality:
          type: array
          items:
            type: object
            properties:
              workloadName:
                type: string
              firstSeen:
                type: integer
                format: int64
              lastSeen:
                type: integer
                format: int64
              completeDays:
                type: integer
              partialDays:
                type: integer
x-refined-from:
- densify-public-cloud-analysis-gcp-analyze-openapi.yaml
- densify-public-cloud-analysis-gcp-delete-openapi.yaml
- densify-public-cloud-analysis-gcp-results-openapi.yaml