Skip to main content

1E 23.11 (SaaS)

Devices

Entity - Devices - Interrogates the Devices table in the database

General note for version 8.0

As of API version 8.0, all the Device APIs "hide" from the caller any devices on which the caller does not have any assignment through Management Groups. This is intended for delegation of administration where the user is supposed to only manage a subset of endpoints, which are specified by means of Management Groups. The delegated administrator should only be able to see the devices assigned to him or her, and not any other endpoints in the organization. This is done transparently by the APIs unless otherwise noted, i.e., the API is called in the normal way as in previous versions, but the returned results are the ones that you would get if the only devices connected to the system were those on which you have any Management Group assignment.

If you need to bypass this restriction for compatibility with earlier versions, it is sufficient to assign to the user any Role on the "All Devices" Management Group. The Role does not need any specific permissions; the mere fact that the user has a Role on All Devices is sufficient for letting the user see all the devices.

Verb

Request

Notes

Permissions 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 checkUsing scope and filter expressionspage.

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 checkUsing scope and filter expressionspage.

  • sort - sort expression. To learn about how to define sort criteria checkSort Definitionpage.

  • 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/{includeInherited}

Minimum API version 8.0

Behaves like the previous API

/Consumer/Devices

but a new (optional) boolean parameter has been added at the end. If omitted, it defaults to true. It is only relevant when the IExpressionTree passed as filter is filtering by one or more Management Groups. When this happens, if the parameter is true, the API returns all the Devices that are members of management groups that inherit from the management group(s) specified in the filter. If the parameter is false, only the direct members of the management group(s) are returned.

Requires the same permissions as the API /Consumer/Devices discussed above

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, checkUsing scope and filter expressionspage.

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

New in Version 8.0: Requires that the invoking user have at least one assignment for the "All Devices" Management Group.

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)

onany 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.

POST

/Consumer/Devices/TachyonGuid/{guid}/Instruction/{forceRefresh}

Sends a Synchronous instruction to the specified device .

Minimum API version 5.2

{guid} should be replaced with the TachyonGuid of the device targeted by the instruction.

{forceRefresh} can be set to true to bypass the response cache. The default is false.

The payload for the POST is the same that is used for an ordinary non-synchronous instruction, with the exception that a Device list cannot be provided – the target of the Synchronous instruction should be specified by means of the TachyonGuid parameter.

Requires permissions on the Instruction Set for the selected instruction and on one of the Management Groups to which the device belongs. See Instructions.

GET

/Consumer/Devices/AttributeValues/{attributeName}

Returns a unique list of attribute values for the given attribute.

Minimum API version 8.1

{attributeName} - The name of the attribute for which the values are required. The list of valid attributes is;

  • OsType

  • OsVerNum

  • OsVersionText

  • AgentVersion

  • DeviceType

  • Location

Requires any of the instruction-related permissions (so

Viewer, Questioner, Actioner or Approver)

on any instruction set.

In this section: