openapi: 3.2.0
info:
  title: Kubex Systems API
  version: 1.0.0
  description: 'Endpoints for retrieving and managing systems discovered via Kubex data collection.


    Notes:

    - Returned element values match those shown in Kubex Analysis Console (DSE > System Summary / Attributes).

    - Filtering supports element filters and advanced attribute filters (see query parameters on `GET /systems`).

    - Some fields appear only when `details=true` is requested.'
servers:
- url: https://{host}
  variables:
    host:
      default: api.example.com
      description: Replace with your Kubex API host
security:
- bearerAuth: []
tags:
- name: Systems
  description: Systems collection and single-system resources
paths:
  /systems:
    get:
      tags:
      - Systems
      operationId: listSystems
      summary: Get Collection
      description: 'Returns configuration and attribute information for systems tracked by recent data collection.


        Notes:

        - By default, only attributes with set values are returned.

        - `attributes_mode=Off` hides attributes, except when any attribute filter is used (it is then ignored and attributes are shown).'
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/Details'
      - name: sort_by
        in: query
        description: 'Sort the collection.


          Supported:

          - `size` (primary: memory; secondary: total_physical_cpus; tertiary: cores_per_cpu)

          - `name`


          Add `,desc` for descending order (default ascending). Examples: `size,desc`, `name`.

          '
        schema:
          type: string
      - name: attributes_mode
        in: query
        description: Show (`On`) or hide (`Off`) set attributes for each system. Ignored if any attribute filter is used.
        schema:
          type: string
          enum:
          - true
          - false
          default: true
      - name: setdisplay_category
        in: query
        description: 'Comma-separated list of attribute categories to return (e.g., `Business,Transformation,Public Cloud`).

          '
        schema:
          type: string
      - name: name
        in: query
        schema:
          type: string
        description: Exact match on system name
      - name: name_like
        in: query
        schema:
          type: string
        description: 'Case-insensitive substring match. Use `%` to match zero or more chars (e.g., `%test%`).

          '
      - name: resource_id
        in: query
        schema:
          type: string
        description: Cloud/provider system ID
      - name: type
        in: query
        schema:
          type: string
          enum:
          - host
          - guest
          - vm
          - arm_vm
          - classic_vm
          - rds
          - asg
          - ecs_svc
        description: Filter by system type
      - name: platform
        in: query
        schema:
          type: string
          description: Comma-separated list allowed
        description: 'Filter by platform; supports multiple values (comma-separated). Supported: `vmware, hmc, aws, gcp, azure, containers`

          '
      - name: infrastructure_group
        in: query
        schema:
          type: string
        description: Filter by infrastructure group (cluster) name
      - name: control_environment
        in: query
        schema:
          type: string
        description: Filter by control environment name
      - name: platform_category
        in: query
        schema:
          type: string
          enum:
          - External Cloud
          - Internal Virtual
        description: Filter by control environment category
      - name: attribute_name_like
        in: query
        schema:
          type: string
        description: 'Returns systems having attributes whose names contain the given substring (supports `%` wildcard).

          '
      - name: attribute_id
        in: query
        schema:
          type: string
        description: Comma-separated attribute IDs (logical OR)
      - name: attribute_name
        in: query
        schema:
          type: string
        description: Comma-separated attribute names (logical OR). URL-encode spaces as `+`.
      - name: attribute_id_value
        in: query
        schema:
          type: string
        description: 'Semicolon-separated ID,value pairs (logical AND across pairs).

          '
      - name: attribute_name_value
        in: query
        schema:
          type: string
        description: 'Semicolon-separated name,value pairs (logical AND across pairs).

          '
      responses:
        '200':
          description: Collection of systems
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/System'
              examples:
                azureNameLikeTest:
                  summary: Azure systems with name containing "test"
                  value:
                  - id: 5da2be9c-3915-46df-a127-387e837a0697
                    name: esx-test-274
                    href: /systems/5da2be9c-3915-46df-a127-387e837a0697
                    resource_id: esx-test-274
                    type: classic_vm
                    platform_model: standard_a0
                    platform: AZURE
                    total_physical_cpus: '1'
                    cores_per_cpu: '1'
                    memory: '768'
                    infrastructure_group:
                      id: c55e12ae-d568-427b-997d-1d5c54065a2d
                      name: eastus-test-vm
                      href: /infrastructure-groups/c55e12ae-d568-427b-997d-1d5c54065a2d
                    control_environment:
                      id: da70ab94-cea1-4a8a-83d7-c26a675ce650
                      name: cc377154-9605-4cb0-8b41-1b39e1c4ac0f
                      platform_category: External Cloud
                      href: /control-environments/da70ab94-cea1-4a8a-83d7-c26a675ce650
                      icon: /control-environments/da70ab94-cea1-4a8a-83d7-c26a675ce650/icon
                    attributes:
                    - id: attr_azure_resource_group
                      name: Resource Group
                      value: test-vm
                    - id: attr_azure_tenant_id
                      name: Tenant ID
                      value: 6c9190a7-bca6-4fcd-b35e-36378aadc695
        '400':
          description: Malformed query (e.g., invalid sort or filter syntax)
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /systems/{id}:
    get:
      tags:
      - Systems
      operationId: getSystem
      summary: Get Individual System
      description: Returns configuration and attribute information for a specific system.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Kubex unique system ID
      - $ref: '#/components/parameters/Details'
      responses:
        '200':
          description: System
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/System'
        '401':
          description: Unauthorized
        '404':
          description: System not found
        '500':
          description: Internal server error
  /systems/{id}/analysis-details:
    post:
      tags:
      - Systems
      operationId: getSystemAnalysisDetails
      summary: Get System's Instance Type Details
      description: 'Provides instance-type details for the system and optimal instance targets.

        Additional targets may be returned based on spend/effort tolerance attributes supplied.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Kubex unique system ID
      requestBody:
        required: true
        description: Array of attribute criteria (name/value pairs)
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                - name
                - value
                properties:
                  name:
                    type: string
                  value:
                    type: string
            examples:
              sample:
                value:
                - name: spendTolerance
                  value: medium
                - name: effortTolerance
                  value: low
      responses:
        '200':
          description: Instance-type details and optimization targets
          content:
            application/json:
              schema:
                type: object
                description: Implementation-specific analysis payload
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '404':
          description: System not found
        '500':
          description: Internal server error
  /systems/{id}/analysis-report:
    get:
      tags:
      - Systems
      operationId: downloadAnalysisReport
      summary: Impact Analysis and Recommendation Report (PDF)
      description: 'Downloads the Impact Analysis and Recommendation Report (Application Owner report) as a PDF.

        Use `Accept: application/octet-stream` to download the file.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Kubex unique system ID
      responses:
        '200':
          description: PDF report
          headers:
            Content-Disposition:
              description: Suggested filename for the downloaded PDF
              schema:
                type: string
                example: attachment; filename="analysis-report.pdf"
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '404':
          description: System or report not found
        '500':
          description: Internal server error
  /systems/{id}/attributes:
    put:
      tags:
      - Systems
      operationId: modifySystemAttributes
      summary: Modify System Attributes
      description: 'Modifies attribute values for a system. For existing attributes, updates their values.

        For non-existent attributes, adds the `[name, value]` tuple.


        For multi-value attributes, adding a `[name, value]` not present will append a new entry.

        To overwrite a multi-value attribute value, delete the existing value first.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Kubex unique system ID
      requestBody:
        required: true
        description: Array of attributes to set/add
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                - name
                - value
                properties:
                  name:
                    type: string
                  value:
                    type: string
            examples:
              modifyExample:
                value:
                - name: Observed Uptime
                  value: '0.33'
                - name: Cost
                  value: '17'
      responses:
        '200':
          description: System with attributes modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/System'
        '400':
          description: Invalid attribute payload
        '401':
          description: Unauthorized
        '404':
          description: System not found
        '500':
          description: Internal server error
    delete:
      tags:
      - Systems
      operationId: deleteSystemAttributes
      summary: Delete System Attributes
      description: 'Deletes attributes from a system using either:

        - `[id, value]` pairs to delete specific values, or

        - `[id]` to delete all values for the given attribute ID (for multi-value attributes).'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Kubex unique system ID
      requestBody:
        required: true
        description: Array of attribute delete directives
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                - id
                properties:
                  id:
                    type: string
                    description: Attribute ID to delete
                  value:
                    type: string
                    description: Optional. If provided, deletes only the entry matching this value.
            examples:
              deleteExample:
                value:
                - id: attr_3
                  value: '0.3'
                - id: attr_10
                - id: attr_11
      responses:
        '200':
          description: System with attributes deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/System'
        '400':
          description: Invalid attribute delete payload
        '401':
          description: Unauthorized
        '404':
          description: System not found
        '500':
          description: Internal server error
components:
  parameters:
    Page:
      name: page
      in: query
      description: Zero-based page index (page=0 is the first page)
      schema:
        type: integer
        minimum: 0
        default: 0
    Details:
      name: details
      in: query
      description: Include extra details for applicable elements (e.g., `children`, `manufacturer`, `os`)
      schema:
        type: boolean
        default: false
    PageSize:
      name: page_size
      in: query
      description: Page size when paging is enabled
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 25
  schemas:
    CpuBenchmark:
      type: object
      properties:
        name:
          type: string
          description: Benchmark label
          enum:
          - CINT2000
          - CINT2000 Rate
          - CINT2006 Rate
          - RPE2
        score_type:
          type: string
          enum:
          - cint2000
          - cint2000rate
          - cint2006rate
          - rpe2
        value:
          type: number
          format: float
    InfrastructureGroupRef:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        href:
          type: string
    AttributeTriple:
      type: object
      description: Attribute entry stored as [id, name, value]
      required:
      - id
      - name
      - value
      properties:
        id:
          type: string
          description: Unique attribute ID (e.g., attr_ObservedUptime)
        name:
          type: string
          description: Human-readable attribute name
        value:
          type: string
          description: Attribute value
    IoBenchmark:
      type: object
      properties:
        name:
          type: string
          enum:
          - Maximum Disk Throughput (bytes/s)
          - Maximum Network Throughput (bytes/s)
        score_type:
          type: string
          enum:
          - disk
          - net
        value:
          type: number
          description: A value of -1 means no value specified
    ControlEnvironmentRef:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        platform_category:
          type: string
          description: Control environment category
          enum:
          - External Cloud
          - Internal Virtual
        href:
          type: string
        icon:
          type: string
          description: Path to icon resource
    System:
      type: object
      description: A discovered system
      properties:
        id:
          type: string
          description: Kubex unique system ID
        name:
          type: string
        href:
          type: string
        resource_id:
          type: string
          description: Cloud/provider unique ID (when applicable)
        type:
          type: string
          description: System type
          enum:
          - host
          - guest
          - vm
          - arm_vm
          - classic_vm
          - rds
          - asg
          - ecs_svc
        platform:
          type: string
          description: System platform
          enum:
          - VMWARE
          - HMC
          - AWS
          - GCP
          - AZURE
          - CONTAINERS
        platform_model:
          type: string
          description: Host model (hosts) or instance type (cloud instances)
        total_physical_cpus:
          type: string
          description: Secondary sort key for `sort_by=size`
        total_logical_cpus:
          type: string
        cores_per_cpu:
          type: string
          description: Tertiary sort key for `sort_by=size`
        threads_per_core:
          type: string
        memory:
          type: string
          description: Normalized total memory (MB). Primary sort key within `size`
        parent:
          type: string
          description: Parent host name for VMs; "N/A" for hosts
        children:
          type: string
          description: Number of child systems (returned when `details=true` and applicable)
        manufacturer:
          type: string
          description: Returned when `details=true`
        os:
          type: string
          description: Returned when `details=true`
        os_patch_level:
          type: string
        os_version:
          type: string
        ip_address:
          type: string
        mac_address:
          type: string
        entity_role_name:
          type: string
          description: Role derived from platform/role (e.g., VMWARE_VM)
        entity_type:
          type: string
          description: Entity type derived from platform/system type
        control_environment:
          $ref: '#/components/schemas/ControlEnvironmentRef'
        infrastructure_group:
          $ref: '#/components/schemas/InfrastructureGroupRef'
        cpu_benchmarks:
          type: array
          items:
            $ref: '#/components/schemas/CpuBenchmark'
        I/O_benchmarks:
          type: array
          items:
            $ref: '#/components/schemas/IoBenchmark'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/AttributeTriple'
      required:
      - id
      - name
      - href
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT