openapi.yaml

openapi: 3.0.1
info:
  title: ControlUp for Desktops Device Management API
  description: |
    API for querying device performance, health scores, and device information from ControlUp for Desktops.
    This API enables Microsoft Security Copilot to answer questions about device performance,
    identify devices with poor performance scores, and find devices associated with specific users.
    
    Key concepts:
    - dex_score: Performance score stored as 0-10000 (represents 0-10 scale * 1000 multiplier)
      Higher values indicate BETTER performance, lower values indicate WORSE performance
      - 10000 (10.0) = Perfect performance
      - 7000-10000 (7.0-10.0) = Good to excellent performance  
      - 4000-7000 (4.0-7.0) = Fair performance
      - 0-4000 (0-4.0) = Poor performance, needs attention
      **Transformation**: Divide by 1000 to convert to UI-friendly 0-10 scale (e.g., 6500 → 6.5)
    - Devices with dex_score < 7000 (< 7.0 on 0-10 scale) are considered to have poor performance
    - Devices can be filtered by various criteria including performance scores and user associations
  version: 1.0.0
  contact:
    name: ControlUp Support
    url: https://support.controlup.com

servers:
  - url: https://app.controlup.com/api
    description: ControlUp for Desktops API. You'll also need your organization ID (orgId) for some endpoints.

tags:
  - name: Devices
    description: Device management and performance queries

paths:
  /devices:
    get:
      tags:
        - Devices
      summary: List devices with optional filtering
      description: |
        Returns a list of devices managed by ControlUp for Desktops. Supports filtering by various criteria
        including performance scores (dex_score), device name, platform, and user associations.
        
        To find devices with poor performance, filter by dex_score < 7000 (which represents < 7.0 on the 0-10 scale).
        When presenting results to users, divide dex_score by 1000 to show the 0-10 scale (e.g., 6500 → 6.5).
        To find devices by user, use filter_field=console_user or filter_field=last_console_user.
        To find devices by name, use filter_field=name with filter_type=contains (for partial match) or filter_type=eq (for exact match).
      operationId: listDevices
      parameters:
        - name: size
          in: query
          description: Number of rows per page (max 10000)
          schema:
            type: integer
            default: 10000
            maximum: 10000
        - name: page
          in: query
          description: Page number (starts at 1)
          schema:
            type: integer
            default: 1
        - name: filter_field
          in: query
          description: Field to filter on. Common values: 'dex_score' (performance score), 'name' (device name), 'console_user' (current user), 'last_console_user' (last user), 'platform' (platform code)
          schema:
            type: string
            example: name
        - name: filter_type
          in: query
          description: Filter comparison type. For device names, use 'contains' (partial match) or 'eq' (exact match). For numeric fields like dex_score, use 'gte', 'lte', 'gt', 'lt', 'eq'.
          schema:
            type: string
            enum: [gte, lte, eq, ne, gt, lt, contains, starts_with, ends_with]
            example: contains
        - name: filter_value
          in: query
          description: Value to filter by. For device names, this is the name or partial name to search for.
          schema:
            type: string
            example: DESKTOP-ABC123
        - name: _source
          in: query
          description: Comma-separated list of fields to return
          schema:
            type: string
            example: "_id,name,dex_score,platform,console_user"
      responses:
        '200':
          description: List of devices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceListResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
        '500':
          description: Internal server error

  /devices/{deviceId}:
    get:
      tags:
        - Devices
      summary: Get device details
      description: |
        Returns comprehensive information about a specific device including its dex_score,
        hardware specifications, OS information, and current status.
      operationId: getDeviceById
      parameters:
        - name: deviceId
          in: path
          required: true
          description: Unique device identifier
          schema:
            type: string
      responses:
        '200':
          description: Device details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '404':
          description: Device not found
        '401':
          description: Unauthorized - Invalid or missing API key
        '500':
          description: Internal server error

  /devices/{deviceId}/snapshot/performance:
    get:
      tags:
        - Devices
      summary: Get device performance snapshot
      description: |
        Returns detailed performance metrics for a device including CPU usage, memory usage,
        disk activity, GPU usage, and performance trends over time.
      operationId: getDevicePerformance
      parameters:
        - name: deviceId
          in: path
          required: true
          description: Unique device identifier
          schema:
            type: string
        - name: fromDate
          in: query
          description: Start date for performance data (ISO 8601 format)
          schema:
            type: string
            format: date-time
        - name: toDate
          in: query
          description: End date for performance data (ISO 8601 format)
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Performance metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerformanceSnapshot'
        '404':
          description: Device not found
        '401':
          description: Unauthorized - Invalid or missing API key
        '500':
          description: Internal server error

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Bearer token authentication using ControlUp API key.
        According to ControlUp API documentation (https://api.controlup.io/reference/how-to-make-api-requests-1),
        API keys are provided as bearer tokens in the Authorization header.
        Format: Authorization: Bearer {your-api-key}

  schemas:
    Device:
      type: object
      description: Device information including performance score and status
      properties:
        _id:
          type: string
          description: Unique device identifier
          example: "lchs9wH4h2EKvgTVv8rd"
        name:
          type: string
          description: Device name
          example: "DESKTOP-ABC123"
        dex_score:
          type: number
          description: |
            Performance score stored as 0-10000 (represents 0-10 scale * 1000 multiplier).
            Higher values indicate BETTER performance, lower values indicate WORSE performance.
            
            **Transformation to 0-10 scale**: Divide by 1000 to get the UI-friendly 0-10 scale.
            - 10000 / 1000 = 10.0 = Perfect performance
            - 7000-10000 / 1000 = 7.0-10.0 = Good to excellent performance
            - 4000-7000 / 1000 = 4.0-7.0 = Fair performance  
            - 0-4000 / 1000 = 0-4.0 = Poor performance, needs attention
            
            Scores below 7000 (7.0 on 0-10 scale) typically indicate performance issues.
            
            **For Copilot responses**: When presenting to users, divide by 1000 and round to 1 decimal place
            for readability (e.g., 6500 → 6.5, 8500 → 8.5).
          example: 6500
          minimum: 0
          maximum: 10000
          # Note: Actual API returns 0-10000, but for user-facing responses, divide by 1000 to get 0-10 scale
        platform:
          type: integer
          description: Platform code (1=Windows, 2=macOS, 3=Linux)
          example: 1
        _platform_name:
          type: string
          description: Platform name
          example: "MSWIN"
        agent_version:
          type: string
          description: ControlUp agent version
          example: "2.171.0"
        is_online:
          type: boolean
          description: Whether the device is currently online
          example: true
        console_user:
          type: string
          nullable: true
          description: Current logged-in user
          example: "DOMAIN\\john.doe"
        last_console_user:
          type: string
          nullable: true
          description: Last logged-in user
          example: "DOMAIN\\john.doe"
        _created:
          type: string
          format: date-time
          description: Device registration timestamp
          example: "2022-01-03T16:47:53.391Z"
        _updated:
          type: string
          format: date-time
          description: Last update timestamp
          example: "2024-12-15T10:30:00.000Z"
        os_name:
          type: string
          nullable: true
          description: Operating system name
          example: "Windows 11"
        os_version_string:
          type: string
          nullable: true
          description: OS version
          example: "10.0.22621"
        hw_manufacturer:
          type: string
          nullable: true
          description: Hardware manufacturer
          example: "Dell Inc."
        hw_model:
          type: string
          nullable: true
          description: Hardware model
          example: "Latitude 5420"
        group:
          type: string
          nullable: true
          description: Device group assignment
          example: "Sales Team"

    DeviceListResponse:
      type: object
      description: Response containing a list of devices
      properties:
        rows:
          type: array
          description: Array of device objects
          items:
            $ref: '#/components/schemas/Device'
        rows_available:
          type: integer
          description: Total number of devices matching the query
          example: 150
        page_size:
          type: integer
          description: Number of devices per page
          example: 10000
        start_row:
          type: integer
          description: First row number on current page
          example: 1
        end_row:
          type: integer
          description: Last row number on current page
          example: 150

    PerformanceSnapshot:
      type: object
      description: Detailed performance metrics for a device
      properties:
        device_id:
          type: string
          description: Device identifier
        cpu_load:
          type: array
          description: CPU load percentage over time
          items:
            type: number
            minimum: 0
            maximum: 100
        memory_available_percentage:
          type: array
          description: Available memory percentage over time
          items:
            type: number
            minimum: 0
            maximum: 100
        disk_usage:
          type: array
          description: Disk usage percentage over time
          items:
            type: number
            minimum: 0
            maximum: 100
        gpu_usage:
          type: array
          nullable: true
          description: GPU usage percentage over time (if available)
          items:
            type: number
            minimum: 0
            maximum: 100
        timestamps:
          type: array
          description: Timestamps corresponding to each metric sample
          items:
            type: string
            format: date-time

security:
  - bearerAuth: []