Search Devices v2.1
API version |
2.1 |
Last Update |
01/30/2018 |
Authentication |
YES |
Response Format |
JSON |
HTTP Method |
GET |
Rate limited |
YES |
Requests per rate limit |
10/min |
Changes |
01/30/2018: removed agent_type in input parameters. API will ignore agent_type parameter in the input |
Use to query devices on a given account
API URL
https://gears.opswat.com/o/api/v2.1/devices/search
Request Parameters
Key |
Datatype |
Parameter Type |
Required |
Description |
Default |
access_token |
string |
URL |
Yes |
access token which archived from OAuth authentication step |
|
q |
string |
URL |
|
Specific search keywords, as well as any qualifiers. Multi-words are separated by +, for example Tomas Hertus is searched as tomas+hertus. |
|
in |
string |
URL |
Optional |
Qualifies which fields are used for search. The caller of the API is responsible for providing this information. |
name |
limit |
int |
URL |
Optional |
Specific maximum number of devices will be returned in the response. The value should be in [1,50]. If there are more devices than what the limit asks for, error code will be 406. |
10 |
page |
int |
URL |
Optional |
Specific page number which devices will be returned in. If the requested page exceeds the number of pages of devices, error code will be 413. It means that the requested page number is too large, no devices will be returned in this case. |
1 |
Response HTTP Code
HTTP Code |
Description |
200 |
Success |
400 |
Bad request |
401 |
Unauthorized. Your access_token is invalid or expired |
404 |
Not found |
406 |
Too many devices to return |
413 |
Requested page number exceeds limit |
Response Parameters
Key |
DataType |
Description |
total_count |
int |
Number of devices which match to search criteria |
results |
array<object> |
Lists of devices which match to search criteria |
results.hwid |
string |
Hardware ID of the device |
results.remediation_link |
string |
URL on remediation page for given device |
results.status |
int |
Reports the health status of the endpoint device. This status is based on the defined policy within . Status values are:
|
results.hostname |
string |
Hostname of the device |
results.nickname |
string |
nickname for the device (admin editable) |
results.agent_version |
string |
Local resident MetaAccess agent version |
results.last_seen |
string |
The last timestamp in GMT format when MetaAccess agent reports its data to Cloud |
results.machine_type |
string |
The type of devices |
results.country |
string |
Region where the device IP geographically represents |
results.active |
int |
1 - device is active, 0 - deactive |
results.total_issue |
int |
Number of issues were seen on the device |
results.user |
string |
Username of a group |
results.user_info |
object |
User information block |
results.user_info.username |
string |
Currently logged in username |
results.user_info.domain |
string |
Currently logged in user domain |
results.os_info |
object |
Operation system block |
results.os_info.family |
string |
OS family |
string |
OS name |
|
results.os_info.vendor |
string |
OS vendor |
results.os_info.version |
string |
OS version |
results.os_info.service_pack_version |
string |
OS Service Pack Version |
results.os_info.architecture |
string |
OS architecture |
results.os_info.os_language |
string |
OS language |
results.os_info.user_password_set |
int |
If user password is set on OS, 1 is set, 0 is not set |
results.network_info |
array<object> |
Network adapter information block |
results.network_info.mac_addr |
string |
MAC address for adapter |
results.network_info.ipv4_addr |
string |
IPV4 address |
results.network_info.ipv6_addr |
string |
IPV6 address |
Example
Example Request
//Search by Device Name and Nick Name:
https://gears.opswat.com/o/api/v2.1/devices/search?q=test&in=name&access_token=TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R61234
//Search by Device ID:
https://gears.opswat.com/o/api/v2.1/devices/search?q=234fs23&in=id&access_token=TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R61234
//Search by MAC Address:
https://gears.opswat.com/o/api/v2.1/devices/search?q=00:1d:09:2d:c7:95&in=mac_address&access_token=TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R61234
//Search by IP Address:
https://gears.opswat.com/o/api/v2.1/devices/search?q=192.168.1.1&in=ip_address&access_token=TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R61234
Search by Username:
https://gears.opswat.com/o/api/v2.1/devices/search?q=tomas+hertus&in=username&access_token=TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R61234
Advanced Example Request
Search by IP and MAC Address:
https://gears.opswat.com/o/api/v2.1/devices/search?q=00:1d&in=ip_address,mac_address&access_token=TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R61234
Search by Name and ID:
https://gears.opswat.com/o/api/v2.1/devices/search?q=asd&in=name,id&access_token=TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R61234
Example Response
{
"total_count": 40,
"results": [{
"hwid": "6WXJURV8QAM0I7KC",
"hostname": "Win_7ENTx64_English",
"nickname": "Win_7ENTx64_English",
"agent_version": "6.1.51.0",
"last_seen": "2013-12-04T08:00:00Z",
"machine_type": "laptop",
"country": "Unknown",
"active": 1,
"total_issue": 10,
"user_info": {
"username": "test",
"domain": "WIN_7ENTX64_ENG"
},
"user": "",
"os_info": {
"family": "Windows",
"name": "Windows 7 Enterprise",
"vendor": "Microsoft Corp.",
"version": "6.1.7600",
"service_pack_version": "0.0",
"architecture": "64-Bit",
"os_language": "",
"user_password_set": "1"
},
"network_info": [{
"mac_addr": "00:0c:29:f2:7a:29",
"ipv4_addr": "10.0.50.106",
"ipv6_addr": "fe80::3c64:7e44:4e78:677"
}],
"status": 1,
"remediation_link": "
https://gears.opswat.com/gears/remediation/2dac92f8fa8dfe02414835d792fb412f/6WXJURV8QAM0I7KC/009nOa7nMaInXaDnMaZ1J/remediation.html
"
}]
}