ControlUp Devices API

openapi: 3.2.0
info:
  title: Controlup Devices API
  version: '1.0'
  description: 'Operations tagged Devices across 2 of this provider''s published API definitions: controlup-compliance-openapi.yml, controlup-desktops-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.controlup.com/compliance
- url: https://api.controlup.com/edge/api
security:
- bearerAuth: []
tags:
- name: Devices
  description: Get information about devices.
paths:
  /devices:
    servers:
    - url: https://api.controlup.com/compliance
    get:
      summary: List all devices
      description: Returns a list of all devices managed by ControlUp for Compliance.
      operationId: getDevices
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/_page'
      - $ref: '#/components/parameters/_limit'
      - $ref: '#/components/parameters/_filters'
      - $ref: '#/components/parameters/_filterby'
      - $ref: '#/components/parameters/_sort'
      - $ref: '#/components/parameters/_orderby'
      - $ref: '#/components/parameters/_search'
      - name: device_id
        in: query
        description: Filter by the devive ID.
        schema:
          type: string
        example: IHAfqJoB-3oP8zTHt8c
      - name: device_name
        in: query
        description: Filter by the device name.
        required: false
        schema:
          type: string
        example: my-device-001
      - name: agent_status
        in: query
        description: Filter by agent connection status.
        required: false
        schema:
          type: string
          enum:
          - online
          - offline
        example: online
      - name: os_name
        in: query
        description: Filter by operating system name.
        required: false
        schema:
          type: string
        example: Microsoft Windows 11 Pro
      - name: mac_address
        in: query
        description: A search filter on the `mac_address` field.
        required: false
        schema:
          type: string
        example: 00:1A:2B:3C:4D:5E
      - name: score
        in: query
        description: A search filter on the `score` field.
        required: false
        schema:
          type: number
          format: float
        example: 7
      - name: score_severity
        in: query
        description: A search filter on the `score_severity` field.
        required: false
        schema:
          type: string
          enum:
          - LOW
          - MEDIUM
          - HIGH
          - CRITICAL
        example: LOW
      - name: issues_count
        in: query
        description: A search filter on the `issues_count` field.
        required: false
        schema:
          type: integer
        example: 0
      - name: device_group
        in: query
        description: A search filter on the `device_group` field.
        required: false
        schema:
          type: string
        example: SampleGroup
      - name: location
        in: query
        description: A search filter on the `location` field.
        required: false
        schema:
          type: string
        example: United States - Chicago
      - name: client_version
        in: query
        description: A search filter on the `client_version` field.
        required: false
        schema:
          type: string
        example: 1.5.2510.08
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    allOf:
                    - $ref: '#/components/schemas/Metadata'
                    - $ref: '#/components/schemas/PaginationMetadata'
                  data:
                    type: array
                    description: List of device objects.
                    items:
                      $ref: '#/components/schemas/Device'
              examples:
                successExample:
                  value:
                    metadata:
                      cuRequestId: 7b8a89c7-172b-4a9f-9e58-24636866266d
                      orgId: 0d5157ef-eb88-4f87-905c-6823fef32f2e
                      userId: d97b8cde-8c2e-4bba-9f20-2097f9f26de4
                      total: 51
                      limitPerPage: 10
                      currentPageNumber: 1
                      currentPageSize: 10
                      remaining: 41
                    data:
                    - device_id: QYkHyYoBQ5QdJu1tiAg1
                      device_name: Oliver’S MAC MINI
                      agent_status: offline
                      os_name: macOS
                      mac_address: null
                      local_ip: null
                      public_ip: 59.52.12.248
                      security_controls: null
                      last_scan: '2025-09-11T16:44:12.613Z'
                      score: 10
                      score_severity: LOW
                      issues_count: 0
                      device_group: Ungrouped Devices
                      device_tags: []
                      location: United States - New York City
                      client_version: 1.5.001
  /devices/{device_id}:
    servers:
    - url: https://api.controlup.com/compliance
    get:
      summary: Get device details
      description: Returns details for a specific device, including a summary of the number of issues detected on the device.
      operationId: getDeviceDetails
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/_page'
      - $ref: '#/components/parameters/_limit'
      - $ref: '#/components/parameters/_filters'
      - $ref: '#/components/parameters/_filterby'
      - $ref: '#/components/parameters/_sort'
      - $ref: '#/components/parameters/_orderby'
      - $ref: '#/components/parameters/_search'
      - name: device_id
        in: path
        description: ID of the device to get.
        required: true
        schema:
          type: string
        example: IHAfqJoB-3oP8zTHt8c
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    allOf:
                    - $ref: '#/components/schemas/Metadata'
                  data:
                    type: object
                    allOf:
                    - $ref: '#/components/schemas/Device'
                    - type: object
                      properties:
                        vulns_count:
                          type: string
                          description: Number of vulnerabilities.
                        available_patches_count:
                          type: string
                          description: Number of patches that have an available remediation.
                        compliance_count:
                          type: string
                          description: Number of compliance issues.
                        misconfig_count:
                          type: string
                          description: Number of misconfigurations.
  /devices/{device_id}/vulnerabilities:
    servers:
    - url: https://api.controlup.com/compliance
    get:
      summary: List device vulnerabilities
      description: Returns a list of vulnerabilities (CVEs) detected on a specific device.
      operationId: getDeviceVulnerabilities
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/_page'
      - $ref: '#/components/parameters/_limit'
      - $ref: '#/components/parameters/_filters'
      - $ref: '#/components/parameters/_filterby'
      - $ref: '#/components/parameters/_sort'
      - $ref: '#/components/parameters/_orderby'
      - $ref: '#/components/parameters/_search'
      - name: device_id
        in: path
        description: ID of the device.
        required: true
        schema:
          type: string
        example: IHAfqJoB-3oP8zTHt8c
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    allOf:
                    - $ref: '#/components/schemas/Metadata'
                    - $ref: '#/components/schemas/PaginationMetadata'
                  data:
                    $ref: '#/components/schemas/VulnerabilitiesData'
  /devices/{device_id}/patches:
    servers:
    - url: https://api.controlup.com/compliance
    get:
      summary: List device patches
      description: Returns a list of missing OS and application patches detected on a specific device.
      operationId: getDevicePatches
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/_page'
      - $ref: '#/components/parameters/_limit'
      - $ref: '#/components/parameters/_filters'
      - $ref: '#/components/parameters/_filterby'
      - $ref: '#/components/parameters/_sort'
      - $ref: '#/components/parameters/_orderby'
      - $ref: '#/components/parameters/_search'
      - name: device_id
        in: path
        description: ID of the device.
        required: true
        schema:
          type: string
        example: IHAfqJoB-3oP8zTHt8c
      - name: title
        in: query
        description: Filter by application name or OS patch KB number.
        schema:
          type: string
        example: KB890830
      - name: severity
        in: query
        description: Filter by issue severity.
        schema:
          type: string
          enum:
          - LOW
          - MEDIUM
          - HIGH
          - CRITICAL
          example: LOW
        style: form
      - name: remediation_status
        in: query
        description: Filter by remediation availability.
        schema:
          type: string
          enum:
          - Available
          - Unavailable
          example: Available
        style: form
      - name: release_date
        in: query
        description: Filter by patch release date.
        schema:
          type: string
      - name: patch_type
        in: query
        description: Filter by patch type detection type. `patch` means that a Template detected the patch by scanning for a specific application or OS patch. `vulnerability` means that a Template detected the patch by scanning for one of the relevant CVEs.
        schema:
          type: string
          enum:
          - patch
          - vulnerability
        example: patch
      - name: is_os
        in: query
        description: Set to `true` to return OS patches and `false` to return application patches.
        schema:
          type: boolean
        example: true
      - name: current_version
        in: query
        description: Filter by currently installed version.
        schema:
          type: string
        example: 10.0.22000
      - name: vendor_name
        in: query
        description: Filter by application vendor name.
        schema:
          type: string
        example: Microsoft Corporation
      - name: last_remediation_status
        in: query
        description: A search filter on the `last_remediation_status` field.
        schema:
          type:
          - string
          - 'null'
      - name: device_action_id
        in: query
        description: A search filter on the `device_action_id` field.
        schema:
          type:
          - string
          - 'null'
          format: uuid
      - name: remediation_availability
        in: query
        description: Filter by whether a remediation for the issue is available.
        schema:
          type: string
      - name: remediation_state
        in: query
        description: A search filter on the `remediation_state` field.
        schema:
          type:
          - string
          - 'null'
      - name: last_event_action
        in: query
        description: A search filter on the `last_event_action` field.
        schema:
          type:
          - string
          - 'null'
      - name: last_event_status
        in: query
        description: A search filter on the `last_event_status` field.
        schema:
          type:
          - string
          - 'null'
      - name: last_event_metadata
        in: query
        description: A search filter on the `last_event_metadata` field.
        schema:
          type: string
      - name: last_event_created_at
        in: query
        description: A search filter on the `last_event_created_at` field.
        schema:
          type:
          - string
          - 'null'
          format: date-time
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    allOf:
                    - $ref: '#/components/schemas/Metadata'
                    - $ref: '#/components/schemas/PaginationMetadata'
                  data:
                    $ref: '#/components/schemas/PatchesData'
  /devices/{device_id}/compliance:
    servers:
    - url: https://api.controlup.com/compliance
    get:
      summary: List device compliance issues
      description: Returns a list of issues from the compliance category detected on a specific device.
      operationId: getDeviceCompliance
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/_page'
      - $ref: '#/components/parameters/_limit'
      - $ref: '#/components/parameters/_filters'
      - $ref: '#/components/parameters/_filterby'
      - $ref: '#/components/parameters/_sort'
      - $ref: '#/components/parameters/_orderby'
      - $ref: '#/components/parameters/_search'
      - name: device_id
        in: path
        description: ID of the device.
        required: true
        schema:
          type: string
        example: IHAfqJoB-3oP8zTHt8c
      - name: title
        in: query
        description: Filter by the issue title.
        schema:
          type: string
        example: Disable Solicited Remote Assistance
      - name: severity
        in: query
        description: Filter by the severity level of the issue.
        schema:
          type: string
          enum:
          - LOW
          - MEDIUM
          - HIGH
          - CRITICAL
        example: LOW
      - name: last_remediation_status
        in: query
        description: Filter by the status of the last remediation attempt.
        schema:
          type:
          - string
          - 'null'
      - name: remediation_availability
        in: query
        description: Filter by whether a remediation for the issue is available.
        schema:
          type: string
          enum:
          - Available
          - Unavailable
        example: Unavailable
      - name: remediation_state
        in: query
        description: Filter by the current remediation state.
        schema:
          type:
          - string
          - 'null'
      - name: last_event_action
        in: query
        description: Filter by the last recorded action.
        schema:
          type:
          - string
          - 'null'
      - name: last_event_status
        in: query
        description: Filter by the status of the last recorded event.
        schema:
          type:
          - string
          - 'null'
      - name: last_event_metadata
        in: query
        description: Filter by metadata associated with the last event (assumes string filter for complexity).
        schema:
          type:
          - string
          - 'null'
      - name: last_event_created_at
        in: query
        description: Filter by the creation time of the last recorded event.
        schema:
          type:
          - string
          - 'null'
          format: date-time
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    allOf:
                    - $ref: '#/components/schemas/Metadata'
                    - $ref: '#/components/schemas/Metadata'
                  data:
                    $ref: '#/components/schemas/ComplianceData'
  /devices/{device_id}/misconfig:
    servers:
    - url: https://api.controlup.com/compliance
    get:
      summary: List device misconfigurations
      description: Returns a list of misconfiguration issues detected on a specific device.
      operationId: getDeviceMisconfig
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/_page'
      - $ref: '#/components/parameters/_limit'
      - $ref: '#/components/parameters/_filters'
      - $ref: '#/components/parameters/_filterby'
      - $ref: '#/components/parameters/_sort'
      - $ref: '#/components/parameters/_orderby'
      - $ref: '#/components/parameters/_search'
      - name: device_id
        in: path
        description: ID of the device.
        required: true
        schema:
          type: string
        example: IHAfqJoB-3oP8zTHt8c
      - name: id
        in: query
        description: Filter by Issue ID.
        schema:
          type: string
          format: uuid
      - name: title
        in: query
        description: Filter by the issue title.
        schema:
          type: string
        example: SSH Server Service detect and remediate
      - name: severity
        in: query
        description: Filter by the severity level of the issue.
        schema:
          type: array
          items:
            type: string
            enum:
            - LOW
            - MEDIUM
            - HIGH
            - CRITICAL
        style: form
        example: LOW
      - name: remediation_status
        in: query
        description: Filter by whether ControlUp can remediate the issue.
        schema:
          type: string
          enum:
          - Available
          - Unavailable
        example: Unavailable
      - name: last_remediation_status
        in: query
        description: Filter by the status of the last remediation attempt.
        schema:
          type:
          - string
          - 'null'
      - name: device_action_id
        in: query
        description: Filter by ID related to the device action.
        schema:
          type: string
          format: uuid
      - name: remediation_availability
        in: query
        description: Filter by whether a remediation for the issue is available.
        schema:
          type: string
          enum:
          - Available
          - Unavailable
      - name: remediation_state
        in: query
        description: Filter by the current remediation state.
        schema:
          type:
          - string
          - 'null'
      - name: last_event_action
        in: query
        description: Filter by the last recorded action.
        schema:
          type:
          - string
          - 'null'
      - name: last_event_status
        in: query
        description: Filter by the status of the last recorded event.
        schema:
          type:
          - string
          - 'null'
      - name: last_event_metadata
        in: query
        description: Filter by event metadata.
        schema:
          type:
          - string
          - 'null'
      - name: last_event_created_at
        in: query
        description: Filter by the creation time of the last recorded event.
        schema:
          type:
          - string
          - 'null'
          format: date-time
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    allOf:
                    - $ref: '#/components/schemas/Metadata'
                    - $ref: '#/components/schemas/PaginationMetadata'
                  data:
                    $ref: '#/components/schemas/MisconfigData'
  /devices/delete:
    servers:
    - url: https://api.controlup.com/edge/api
    post:
      tags:
      - Devices
      summary: Delete devices
      description: Delete devices by their device ID.
      operationId: delete-devices
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                device_ids:
                  description: An array of the device IDs to delete.
                  type: array
                  items:
                    type: string
                  example:
                  - rTIBRoIBOFdS29Oi1ATq
                  - b47LRkQIB8BdS21Oi1TYh
      responses:
        '200':
          description: Devices successfully deleted.
        '400':
          description: Invalid request payload.
        '500':
          $ref: '#/components/responses/500'
  /devices/tags:
    servers:
    - url: https://api.controlup.com/edge/api
    get:
      summary: List all device tags
      tags:
      - Devices
      description: Returns a list of all device tags, including how many devices are using each tag.
      operationId: list-device-tags
      responses:
        '200':
          description: List of device tags.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      description: The name of the device tag.
                      type: string
                    device_count:
                      description: The number of devices that are using the tag.
                      type: integer
    post:
      tags:
      - Devices
      summary: Update device tags
      description: Adds or removes device tags.
      operationId: update-tags
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  description: An array of the IDs of the devices whose tags you want to update.
                  type: array
                  items:
                    type: string
                  example:
                  - rTIBRoIBOFdS29Oi1ATq
                  - b47LRkQIB8BdS21Oi1TYh
                action:
                  description: Set whether to `create` or `delete` tags on the selected devices.
                  type: string
                  enum:
                  - create
                  - delete
                  example: create
                tags:
                  description: An array of the tags to add or remove on the specified devices. Tags can be up to 150 characters long and contain lowercase letters, numbers, -, _, and spaces.
                  type: array
                  items:
                    type: string
                    maxLength: 150
                  example:
                  - testtag1
                  - testtag2
      responses:
        '200':
          description: Device tags successfully updated. Returns the updated device details.
        '400':
          description: Invalid request payload.
        '500':
          $ref: '#/components/responses/500'
  /devices/groups:
    servers:
    - url: https://api.controlup.com/edge/api
    get:
      summary: List all device groups
      tags:
      - Devices
      description: Returns a list of all device groups, including how many devices are in each group.
      operationId: list-device-groups
      responses:
        '200':
          description: List of device groups.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      description: The name of the device group.
                      type: string
                    device_count:
                      description: The number of devices that are in the group.
                      type: integer
  /devices/set-group:
    servers:
    - url: https://api.controlup.com/edge/api
    post:
      summary: Set device group
      tags:
      - Devices
      description: Sets the device group for the specified devices. A device can belong to only one group at a time.
      operationId: add-device-group
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                device_ids:
                  description: An array of the IDs of the devices to add to the device group.
                  type: array
                  items:
                    type: string
                  example:
                  - rTIBRoIBOFdS29Oi1ATq
                  - b47LRkQIB8BdS21Oi1TYh
                group:
                  description: The device group. This does not have to be an existing group.
                  type: string
      responses:
        '200':
          description: Device added to group successfully.
  /devices/{deviceID}/actions:
    servers:
    - url: https://api.controlup.com/edge/api
    post:
      tags:
      - Devices
      summary: Perform action on a single device
      description: Performs an action on the specified device.
      operationId: run-an-action-single
      parameters:
      - in: path
        name: deviceID
        schema:
          type: string
        required: true
        description: ID of the device on which to perform the action. You can use [GET /devices](list-devices) to see the ID for each device.
      requestBody:
        description: Select the type of action you want to perform to see the required payload. There are payload request samples for each type of action.
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/runcmd-singledevice'
              - $ref: '#/components/schemas/runcmduser-singledevice'
              - $ref: '#/components/schemas/sendmessageallusers-singledevice'
              - $ref: '#/components/schemas/sendmessagesingleuser-singledevice'
              - $ref: '#/components/schemas/logoffuser'
              - $ref: '#/components/schemas/disconnectuser'
              - $ref: '#/components/schemas/reboot'
              - $ref: '#/components/schemas/termiateprocess'
              - $ref: '#/components/schemas/runscript-singledevice'
      responses:
        '202':
          description: Action request successfully sent.
        '400':
          description: Invalid request payload.
        '500':
          $ref: '#/components/responses/500'
  /devices/action:
    servers:
    - url: https://api.controlup.com/edge/api
    post:
      tags:
      - Devices
      summary: Perform action on multiple devices
      description: Performs an action on the specified devices. If you want to perform an action on only a single device, we recommend that you use [POST /devices/{deviceID}/action](run-an-action-single) for more options.
      operationId: run-an-action
      requestBody:
        description: Select the type of action you want to perform to see the required `action_data`. There are payload request samples for each type of action.
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/runcmd-multidevice'
              - $ref: '#/components/schemas/runcmduser-multidevice'
              - $ref: '#/components/schemas/sendmessageallusers-multidevice'
              - $ref: '#/components/schemas/sendmessagesingleuser-multidevice'
              - $ref: '#/components/schemas/runscript-multidevice'
      responses:
        '202':
          description: Action request successfully sent.
        '400':
          description: Invalid request payload.
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    sendmessageallusers-multidevice:
      title: Send message to all users
      type: object
      properties:
        action_data:
          description: Details about the action to perform.
          type: object
          properties:
            type:
              description: The type of action to perform. To send a message to all users on all selected devices, enter `DEV_CONSOLEMSG`.
              type: string
              enum:
              - DEV_CONSOLEMSG
            data:
              description: The message to send.
              type: string
              example: Hello! This is a test message.
        device_ids:
          $ref: '#/components/schemas/deviceIds'
    termiateprocess:
      title: Terminate process
      type: object
      properties:
        type:
          description: The type of action to run. To terminate a process, enter `PROC_STOP`.
          type: string
          enum:
          - PROC_STOP
        data:
          description: The process identifier (PID) of the process to terminate.
          type: integer
          format: int64
          example: 18740
    runcmduser-singledevice:
      title: Run command as user
      type: object
      properties:
        type:
          description: The type of action to perform. To run a command as a user session, enter `DEV_RUNCMD_USER`. Running a user command is not available on Linux or ChromeOS devices.
          type: string
          enum:
          - DEV_RUNCMD_USER
        data:
          type: string
          description: "A JSON-formatted string containing the following information (see sample request payload):\n\n    `session_id`: ID of the user session. The \"active_users\" field in the \"_devices\" data index contains a list of active users and their session IDs. See [GET /data/{index_name}](get-data-index) for details.\n    `command_line`: The command to run.\n    `show_window`: Sets whether to display a window on the device. For example, if you run \"notepad.exe\" with show_window=true, then notepad\n    will open in a window. If you run \"notepad.exe\" with show_window=false, then notepad will run in the background without displaying a window.\n"
          example: '{"session_id":"1","command_line":"whoami","show_window":false}'
    deviceIds:
      type: array
      description: An array of device IDs on which to perform the action. You can use [GET /devices](list-devices) to get device IDs.
      items:
        type: string
      example:
      - rTIBRoIBOFdS29Oi1ATq
      - b47LRkQIB8BdS21Oi1TYh
    sendmessageallusers-singledevice:
      title: Send message to all users
      type: object
      properties:
        type:
          description: The type of action to run. To send a message to all users on the device, enter `DEV_CONSOLEMSG`.
          type: string
          enum:
          - DEV_CONSOLEMSG
        data:
          description: The message to send.
          type: string
          example: Hello! This is a test message.
    sendmessagesingleuser-multidevice:
      title: Send message to a single user
      type: object
      properties:
        action_data:
          description: Details about the action to perform.
          type: object
          properties:
            type:
              description: The type of action to perform. To send a message to a single user on the device, enter `DEV_USERMSG`. This option is available only if `device_ids` contains a single device ID.
              type: string
              enum:
              - DEV_USERMSG
            data:
              description: "A JSON-formatted string containing the following information (see sample request payload):\n\n  `session_id`: ID of the user session. The \"active_users\" field in the \"_devices\" data index contains a list of active users and their session IDs. See [GET /data/{index_name}](get-data-index) for details.\n  `message_text`: The message to send.\n"
              example: '{"session_id":"1","message_text":"Hello! This is a test message."}'
              type: string
        device_ids:
          $ref: '#/components/schemas/deviceIds'
    PaginationMetadata:
      type: object
      description: Extra metadata for paginated responses.
      properties:
        total:
          type: integer
          description: Total number of reco

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/controlup/refs/heads/main/openapi/controlup-devices-api-openapi.yml