Machines

With this method, you can:

  • Find and display information about your managed machines
  • Delete managed machines
  • Assign a credential to a machine
  • Update a machine

Base URL

        https://<consoleFQDN:port>/st/console/api/v1.0/machines

Supported Requests

Method URL Input Return

DELETE

https://<consoleFQDN:port>/st/console/api/v1.0/machines/{machineId}

 

Success code

GET

https://<consoleFQDN:port>/st/console/api/v1.0/machines

URL Parameters

ManagedMachine

https://<consoleFQDN:port>/st/console/api/v1.0/machines/{machineId}

 

ManagedMachine

PATCH

https://<consoleFQDN:port>/st/console/api/v1.0/machines/{machineId}

Request Body

Success code

PUT

https://<consoleFQDN:port>/st/console/api/v1.0/machines/{machineId}/credentials

Credential URL Parameters

Success code

Input Models

Name Type Description

count

Integer

Provide the count of items to return. The default is 10 and the maximum value is 1000.

domain

String

Returns the items whose domain matches the specified domain.

ipAddress

IPAddress

Returns the items whose IP matches the specified IP address.

name

String

Returns the items whose name matches the specified name.

start

Integer

Sets the starting point. The items are sorted by their unique identifier and the starting point is the index into that sorted list.
Name Type Description

assetTag

String

The machine's asset tag.

assignedGroup

String

The machine's assigned machine group.

connectionMethod

Enum

Specifies the method used to connect to the machine. Valid values are:

  • IPAddress: A connection is made by IP address after name/machine resolution is performed.
  • Fqdn: A connection is made using the Fully Qualified Domain Name (FQDN). This supports SPN name validation, which may be required in networks using Kerberos authentication.

custom1

String

User-defined value.

custom2

String

User-defined value.

custom3

String

User-defined value.

customerName

String

User-defined value.

description

String

User-defined description of the machine.

location

String

The physical location of the machine.

machineCriticality

Enum

The criticality of the machine. Values are None, Critical, High, Medium, Low, Ignore.

patchDrivePath

String

The drive where patches are to be deployed to on this machine. (Full path.)

rdpPort

Integer

The TCP/IP port for Remote Desktop Protocol access.

If you explicitly set a parameter in the request body, the machine properties are updated to that value.
If a parameter is omitted from the request, the previous value persists.
If a parameter is explicitly set to "" in the JSON request body, the field is updated to null.

Name Required? Type Default Value Description

credentialId

No

Guid

None

The unique identifier of the credential that will be assigned to the machine. If this parameter is excluded, any existing credential will be removed.

Example with Sample Response

Find the machine with IP address 192.168.1.1

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/machines/?ipAddress=192.168.1.1

Sample Response

Copy 
{
    "count": 1,
    "links": {
        "next": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/machines?count=10&start=2&IPAddress=192.168.1.1"
        }
    },
    "value": [
        {
            "consoleName": "sample-console-name",
            "dnsName": "device-name.example.com",
            "domain": "example",
            "id": 1,
            "ipAddress": "192.168.1.1",
            "links": {
                "self": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/machines/1"
                }
            },
            "name": "sample-machine-name",
            "assignedGroup": "My Machine"
        }
    ]
}

Other Request Examples

DELETE Request

https://<consoleFQDN:port>/st/console/api/v1.0/machines/8

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/machines?count=10&start=1

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/machines?name=MachineName1

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/machines?ipaddress=10.114.251.154

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/machines?domain=SampleDomain

PUT Request

https://<consoleFQDN:port>/st/console/api/v1.0/machines/8/credentials?credentialId=e985c825-c871-4b0f-a4b3-1689b3f3cf7a

PUT Request

https://<consoleFQDN:port>/st/console/api/v1.0/machines/8/credentials

PATCH Request

Copy 
https://<consoleFQDN:port>/st/console/api/v1.0/machines/7

    {
        "assetTag": "ExampleAssetTag",
        "assignedGroup": "Machine Group",
        "location": "New Brighton",
        "connectionMethod": "IPAddress",
        "machineCriticality": "Critical",
        "custom1": "A value I set myself",
        "custom2": "A value I set myself",
        "custom3": "A value I set myself",
        "customerName": "John Doe",
        "description": "My free text description",
        "patchDrivePath": "C:\"
        "rdpPort": 3121,
    }

If you explicitly set a parameter in the request body, the machine properties are updated to that value.
If a parameter is omitted from the request, the previous value persists.
If a parameter is explicitly set to "" in the JSON request body, the field is updated to null.

Output Models

ManagedMachine

Name Type Description

agentVersion

Version

The version of the Agent if one is installed, null if no Agent is installed.

architecture

Enum

The machine architecture.

Valid values are: null, Unknown, x86, or x64.

assetTag

String

The machine's asset tag.

assignedGroup

String

The group that the machine is assigned to within Machine View and Scan View.

connectionMethod

Enum

Specifies the method used to connect to the machine. Valid values are:

  • IPAddress: A connection is made by IP address after name/machine resolution is performed.
  • Fqdn: A connection is made using the Fully Qualified Domain Name (FQDN). This supports SPN name validation, which may be required in networks using Kerberos authentication.

consoleName

String

The console name.

credentialId

Guid

The ID of the credential that is assigned to the machine.

custom1

String

User-defined value.

custom2

String

User-defined value.

custom3

String

User-defined value.

customerName

String

User-defined customer name value.

description

String

User-defined description of the machine.

distribution

String

The platform distribution.

dnsName

String

The DNS name.

domain

String

The domain name.

id

Int32

The machine ID.

installedPatchCount

Int32

The number of patches that were found to be installed on the machine.

ipAddress

IPAddress

The IP address of the machine.

lastAgentCheckInDate

DateTime

The latest date and time that an agent checked in for this machine. If no agent is installed, null is returned.

latestAssetScanDate

DateTime

The UTC date and time at which the last asset scan occurred. If no scan has been run against a machine, null is returned.

latestAssetScanId

Int32

The ID of the last asset scan performed on this machine. If no scan has been run against the machine, null is returned.

latestAssetScanTemplateId

Guid

The UID of the template used in the last asset scan performed on this machine. If no scan has been run against a machine, null is returned.

latestPatchScanDate

DateTime

The UTC date and time at which the last patch scan occurred. If no scan has been run against a machine, null is returned.

latestPatchScanId

Guid

The UID of the last patch scan performed on this machine. If no scan has been run against the machine, null is returned.

latestPatchScanTemplateId

Guid

The UID of the template used in last patch scan performed on this machine. If no scan has been run against a machine, null is returned.

links

Links

Shows the related URLs for the machine.

location

String

The physical location of this machine.

machineCriticality

Enum

The criticality of the machine.
Values are None, Critical, High, Medium, Low, or Ignore.

missingPatchCount

Int32

The number of patches found to be missing on the machine.

missingProductLevelCount

Int32

The number of product levels found to be missing on the machine.

name

String

The machine name.

osEndOfLife

DateTime

The end of life date for the installed OS. If no end of life date is found, null is returned.

osLanguageId

Int32

The culture and region of the operating system installed on the machine.

osName

String

The name of the operating system running on the machine.

osType

Enum

The operating system type.
Values are Unknown, Linux, or Windows.

patchDefinition

Version

The Assessment Catalog data version from the latest patch scan.

patchDrivePath

String

The drive in which patches are to be deployed to on this machine.

platformVersion

String

The platform version.

rdpPort

Int32

The TCP/IP port for Remote Desktop Protocol access.

reportedAgentPolicy

String

The actual reported policy governing the agent installed on the machine. If no agent is installed, null is returned.

usingLatestPolicy

Boolean

Denotes if this machine is using the latest policy. If no agent is installed, null is returned.

virtualMachinePath

String

The virtual machine path. If the machine is not a hosted virtual machine, null is returned.

virtualServer

String

The virtual server. If the machine is not a hosted virtual machine, null is returned.