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:
  parameters:
    _sort:
      name: _sort
      in: query
      required: false
      description: 'URL-encoded **JSON string** containing a sort object or an array of sort objects.


        #### Sort object structure

        * **`field`** (string): The data field to sort on.

        * **`dir`** (string): Sort direction. Must be one of `asc` (ascending) or `desc` (descending).

        * **`nullsLast`** (boolean, optional): If `true`, null values appear at the end of the results.


        #### Examples

        * Single field: `{"field":"score","dir":"desc","nullsLast":true}`

        * Multi-field: `[{"field":"score","dir":"desc"},{"field":"device_name","dir":"asc"}]`

        '
      schema:
        type: string
        example: '{"field":"score","dir":"desc","nullsLast":true}'
    _filterby:
      in: query
      name: _filterby
      required: false
      description: 'A URL-encoded **comma-separated list** of filter expressions. Filters are ANDed together implicitly.


        #### Filter expression structure

        `field operator value` (e.g., `score gte 90`)

        * field: The data field to apply the filter on.

        * operator: The comparison operator (supports the same operators as the `_filters` parameter. Read the `_filters` description for details).

        * value: The value to compare against. When using the `in` and `nin` operators, the value can take a comma-separated list of values.


        You don''t need to specify field types when using this parameter. All filter expressions are sent as strings, and the server handles the conversion to the required field type.


        #### Examples:

        Note that the examples must be URL-encoded when sent.

        * Simple: `device_name contains server`

        * Multi-criteria: `device_name contains server,score gte 90`

        * List/IN operator: `tags in prod,qa`

        '
      schema:
        type: string
        example: device_name contains server
    _filters:
      in: query
      name: _filters
      required: false
      description: 'URL-encoded **JSON string** containing a single filter object or an array of filter objects. Multiple filter objects are ANDed together.


        #### Filter object structure:

        * **`field`** (string): The data field to apply the filter on.

        * **`op`** (string): The comparison operator (see below for allowed operators).

        * **`value`**: The value(s) to compare against. The type depends on the field and operator (see below for allowed operators and values).


        #### Supported operators (`op`) and values (`value`)


        **Exact comparison**

        * **`eq`** (equal to), **`ne`** (not equal to): Supported by all field types. Value can be string, number, boolean, or `null`.


        **Range & ordering**

        * **`gt`** (greater than), **`gte`** (greater than or equal to), **`lt`** (less than), **`lte`** (less than or equal to): Supported by number fields. Value must be a number.


        **List membership**

        * **`in`** (is in list), **`nin`** (is not in list): Supported by all field types. Value must be a JSON array of strings, numbers, booleans, or nulls.


        **String/text matching**

        * **`contains`**, **`startsWith`**, **`endsWith`**: Supported only by string fields. Value must be a string.


        **Presence checks**

        * **`isNull`**, **`notNull`**: Supported by all field types. No value field is required for these operators.


        #### Examples

        Note that examples must be url-encoded when sent.

        * Single filter: `{"field":"score","op":"gte","value":90}`

        * Multiple filters: `[{"field":"device_name","op":"contains","value":"vm"},{"field":"tags","op":"in","value":["prod","qa"]}]`

        '
      schema:
        type: string
        example: '{"field":"score","op":"gte","value":90}'
    _page:
      in: query
      name: _page
      required: false
      description: The page returned. Pages are 1-based.
      schema:
        type: integer
    _search:
      in: query
      name: _search
      required: false
      description: 'Free-text search across all text fields. If you add multiple values, they are ANDed together. You can submit multiple values using one of two supported formats:

        * **Comma-separated string**. F

# --- 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