Device Reference Helper


Many BIG-IQ API requests refer to a particular BIG-IP using the deviceReference parameter. The value of deviceReference is a link object for the BIG-IP being targeted by the request. You should first call the Device Reference Helper API to get the correct value of deviceReference before trying to use it in another BIG-IQ API. The value of these links is expected to change from release to release. The helper API can query for the correct value of deviceReference if you specify either the hostname, address, or machineId of the target BIG-IP as well as specify the module associated with your request. By using the helper API, you will isolate clients from future version-specific changes to these links.

REST Endpoint: /cm/shared/device-reference-query


POST /cm/shared/device-reference-query

Request Parameters

Name Type Required Description
machineId string If machineId is not null, use it to identify the BIG-IP, otherwise use address. The machineId of the target BIG-IP.
address string If address is not null, use it to identify the BIG-IP, otherwise use hostname. The IP address of the target BIG-IP.
hostname string At least one of machineId, address, or hostname is required to identify the BIG-IP. The hostname of the target BIG-IP.
module string If module is null or empty, BIG-IQ uses a default value of “global”. Name representing the module and the device group reference associated with the API request. See the following table for the allowed values of module.

The following names can be used as the value of module.

Name Device Group Reference
access cm-access-allBigIpDevices
adc-core cm-adccore-allbigipDevices
asm cm-asm-allAsmDevice
global cm-bigip-allBigIpDevices
dns cm-dns-allBigIpDevices
firewall cm-firewall-allFirewallDevices
security-shared cm-security-shared-allSharedDevices
websafe cm-websafe-allFpsDevices

Query Parameters



HTTP/1.1 200 OK

Name Type Description
link object The value of the deviceReference parameter.

Error Response

HTTP/1.1 404 Not Found

This response happens if that BIG-IP cannot be found or does not exist in that module.


Role Allow
All Roles Yes


In the following example, the BIG-IQ API is going to use the deviceReference parameter to target a particular BIG-IP for a PUT request. First, call the Device Reference Helper to get the correct value of deviceReference as follows.

POST /cm/shared/device-reference-query
  "address": "",
  "module": "access"

On success, the body of the response contains the link object which is the value of deviceReference.

  "link": "https://localhost/mgmt/shared/resolver/device-groups/cm-access-allBigIpDevices/devices/2913a9ff-6fea-42a1-bd82-73d6dd5c9849"

You can then use this value in the PUT request as the follows.

PUT /cm/access/working-config/ltm/virtual/<id>
    "name": "vip-02",
    "deviceReference": {
        "link": "https://localhost/mgmt/shared/resolver/device-groups/cm-access-allBigIpDevices/devices/2913a9ff-6fea-42a1-bd82-73d6dd5c9849"