Entity - Devices - Interrogates the Devices table in the database

Page version: 51, last updated:



VerbRequestNotesPermissions required
GET/Consumer/Devices/fqdn/{fqdn}

Gets a single device based on FQDN.

FQDN has to be base64 encoded.

Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any instruction set
POST/Consumer/Devices/fqdn

Gets summarized affected device counts given a list of devices.

Example Request
{
   "Scope":"device1,device2"
}
Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any instruction set
POST/Consumer/Devices/fqdnfiltered/{instructionDefinitionId}

Gets summarized device counts given a list of devices in the same way as the Devices/fqdn API described above, but considers only those devices that are reachable by the calling user in accordance with the permissions granted by Management Groups for the specified instruction definition.

Example Request
{
   "Scope":"device1,device2"
}
Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any instruction set
GET/Consumer/Devices

Gets all devices. Returns a list of Device objects.

Example Response
{
    "Id":1,
    "Name":"somemachine01",
    "Fqdn":"somemachine01.somadomain.com",
    "Status":1,
    "OsType":"Windows",
    "OsVerNum":2814750438195200,
    "OsVerTxt":"Microsoft Windows 10 Enterprise",
    "AgentVersion":281483566841860,
    "MAC":"00-15-5D-0B-AF-2B",
    "Manufacturer":"Dell Inc.",
    "ChassisType":7,
    "DeviceType":"Desktop",
    "CpuType":"Intel(R) Xeon(R) CPU E5-2630 0 @ 2.30GHz",
    "CpuArchitecture":"x64",
    "OsArchitecture":"x64",
    "RamMB":32693,
    "SMBiosGuid":"4c4c4544-0051-5a10-8058-b7c04f47354a",
    "OsGuid":"4c4c4544-0051-5a10-8058-b7c04f47354a",
    "TachyonGuid":"4c4c4544-0051-5a10-8058-b7c04f47354a",
    "BiosVersion":"n/a",
    "LastBootUTC":1454408472,
    "LastConnUtc":1454604670,
    "CreatedUtc":"2016-02-03T17:20:55.003",
    "VrPlatform":"",
    "TimeZone":0,
    "CertType":null,
    "CertExpiryUtc":null,
    "PushToken":null,
    "Model":"Precision T5600",
    "Domain":"Somedomain",
    "Tags": "||",
    "ConnectionState": [
        "SkipDigitalSignatures"
    ],
    "LocalIpAddress": "192.168.0.1",
    "ConnectingIpAddress": "192.124.249.5",
    "TimeZoneId": "Europe/London",
    "SerialNumber": "FRBNJ333",
    "Criticality": 0,
    "Location": "1E office in Ealing, Third floor.",
    "CoverageTags": {},
    "MAC": "00-15-5d-0b-0c-20",
    "ConnectingIpAddress": "172.0.0.103"
}
Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any instruction set
POST/Consumer/Devices/Scope

Gets devices based on static scope. It does not support sorting and pagination.

Example Request
{
   "Operator": "and",
   "Operands":[
        {  
            "Attribute":"devtype",
            "Operator":"==",
            "Value":"Desktop"
        },
        {  
            "Attribute":"ostype",
            "Operator":"==",
            "Value":"Windows"
        }
    ]
}

To learn about how to define filter check Using scope and filter expressions page.

For the list of allowed scope attributes check Defining the scope page.

Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any instruction set
POST/Consumer/Devices/ApproxTarget

Obsolete in API versions 3.3 and onwards.

Gets approximate number of devices matching the scope in aggregated format.

Example Request
{
   "Operator": "and",
   "Operands":[
        {  
            "Attribute":"devtype",
            "Operator":"==",
            "Value":"Desktop"
        },
        {  
            "Attribute":"ostype",
            "Operator":"==",
            "Value":"Windows"
        }
    ]
}

To learn about how to define filter check Using scope and filter expressions page.

For the list of allowed scope attributes check Defining the scope page.

Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any of the product packs
POST/Consumer/Devices/ApproxTarget/{id}

Minimum API version 3.3.

Gets approximate number of devices matching the scope in aggregated format.

Id is an Id of the instruction definition in whose context you wish to get the approximate data. This is required as permission on instructions that limit management group usage will affect what machines are targeted.

Example Request
{
   "Operator": "and",
   "Operands":[
        {  
            "Attribute":"devtype",
            "Operator":"==",
            "Value":"Desktop"
        },
        {  
            "Attribute":"ostype",
            "Operator":"==",
            "Value":"Windows"
        }
    ]
}

To learn about how to define filter check Using scope and filter expressions page.

For the list of allowed scope attributes check Defining the scope page.

Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any of the product packs
POST/Consumer/Devices/ApproxTarget/{instructionDefinitionId}/parent/{parentInstructionId}

Minimum API version 3.3.

Gets approximate number of devices matching the scope in aggregated format.

Should be used for follow-up instructions, because it will take into account permissions inherited from parent instruction and current permissions for the instruction definition to be used to issue an instruction.

instructionDefinitionId - is an Id of the instruction definition in whose context you wish to get the approximate data. This is required as permission on instructions that limit management group usage will affect what machines are targeted.
parentInstructionId - id an Id of the parent instruction to whom a follow-up instruction you wish to check impact for.
Example Request
{
   "Operator": "and",
   "Operands":[
        {  
            "Attribute":"devtype",
            "Operator":"==",
            "Value":"Desktop"
        },
        {  
            "Attribute":"ostype",
            "Operator":"==",
            "Value":"Windows"
        }
    ]
}

To learn about how to define filter check Using scope and filter expressions page.

For the list of allowed scope attributes check Defining the scope page.

Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any of the product packs
GET/Consumer/Devices/Tachyonguid/{guid}

Gets a single device by Tachyon GUID

This will return 1 device as it assumes that GUID is unique.

Endpoint will throw if it cannot find the device or a malformed GUID was supplied.

The GUID string is to be supplied in plain text, not base64 encoded.

The GUID can be in any format that is acceptable to the .NET’s GUID class.

Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any instruction set
POST/Consumer/Devices

This endpoint allows searching for devices based on criteria along with sorting and pagination.

Example Request
{  
   "filter":{
       "Operator": "and",
       "Operands":[
            {  
                "Attribute":"DeviceType",
                "Operator":"==",
                "Value":"Desktop"
            },
            {  
                "Attribute":"OSType",
                "Operator":"==",
                "Value":"Windows"
            }
        ]
    },
   "start":10,
   "pageSize":100,
   "sort":[
       {
            "Column":"fqdn",
            "Direction":"ASC"
       }
    ]
}
  • filter - filter expression.To learn about how to define filter check Using scope and filter expressions page.
  • sort - sort expression. To learn about how to define sort criteria check Sort Definition page.
  • start - starting index to support pagination. It begins from 1.
  • pagesize - number of results to fetch

Allowed filter columns

  • Name
  • FQDN
  • DeviceType
  • Status
  • OsType
  • OsVersionText
  • AgentVersion
  • TimeZone
  • VrPlatform (Virtualization Platform)
  • Domain
  • OsVerNum (OS Version Number)

Allowed sortable columns

  • Name
  • FQDN
  • DeviceType
  • Status
  • OsType
  • OsVersionText
  • AgentVersion
  • OsVerNum (OS Version Number)
  • LastSeenTime
Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any instruction set
 POST/Consumer/Devices/summary 

Gets summary information, counting the number of devices grouped by fixed criteria based on static scope. It does not support sorting and pagination.

The following example shows a filter that uses all the attributes that are produced in the output of this API. Under normal circumstances, you would only filter on a subset of these columns.

Example Request
{
  Filter:{
   "Operator": "or",
   "Operands":[
        {  
            "Attribute":"OsType",
            "Operator":"==",
            "Value":"Windows"
        },
        {  
            "Attribute":"AgentVersion",
            "Operator":"==",
            "Value":"281483566841860"
        },
        {  
            "Attribute":"Status",
            "Operator":"!=",
            "Value":"2"
        },
        {  
            "Attribute":"DeviceType",
            "Operator":"==",
            "Value":"Desktop"
        },
        {  
            "Attribute":"TimeZone",
            "Operator":"==",
            "Value":"0"
        },
        {  
            "Attribute":"VrPlatform",
            "Operator":"==",
            "Value":""
        }
    ]
  }
}

To learn about how to define the filter, check Using scope and filter expressions page.


Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any instruction set
POST (FORM)/Consumer/Devices/exportmatching

Form post endpoint used to return a CSV file containing information about devices.

You can include a filter in the form post that contains JSON that conforms scoping and filtering expression as outline above.

To do so send JSON as body of the message with a field called "Filter" whose value should be string that contains a JSON with the filtering expression.

Example Request Payload
{
    "Operator": "and",
    "Operands": [
        {
            "Attribute": "DeviceType",
            "Operator": "==",
            "Value": "Desktop"
        },
        {
            "Attribute": "OSType",
            "Operator": "==",
            "Value": "Windows"
        }
    ]
}

POST/Consumer/Devices/ByDomainAndName

Gets device status (Online/Offline) by domain and name.

Example Request Payload
{  
   "DomainsAndNames":[  
      {  
         "Domain":"ACMEFINANCE",
         "Names":[  
            "1AF8400000000002",
            "1AF8400000000003"
         ]
      },
      {  
         "Domain":"ACMEENGINEERING",
         "Names":[  
            "1AF8400000000200",
            "1AF8400000000201"
         ]
      }
   ]
}
Example Response Payload
[
    {
        "Id": 12229,
        "Domain": "ACMEFINANCE",
        "Name": "1AF8400000000003",
        "Status": 0
    },
    {
        "Id": 12305,
        "Domain": "ACMEENGINEERING",
        "Name": "1AF8400000000200",
        "Status": 1
    }
]
Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any instruction set
GET

/Consumer/Devices/fqdn/{fqdn}/ManagementGroups


Gets all Management Groups a device belongs to.

FQDN has to be base64 encoded.

Minimum API version 3.3

Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any instruction set
GET/Consumer/Devices/tachyonguid/{tachyonGuid}/ManagementGroups

Gets all Management Groups a device belongs to.

The Guid must be in a format recognizable as a GUID by .NET framework, i.e. 123e4567-e89b-12d3-a456-426655440000

Minimum API version 4.0


GET

/Consumer/Devices/CriticalityMapping

Gets the mapping table for the Criticality of devices.

Minimum API version 4.0

Example response payload
{
    "0": "Undefined",
    "1": "Non-critical",
    "2": "Low",
    "3": "Medium",
    "4": "High",
    "5": "Critical"
}
None.