Device Action

API version

3.1

Last Update

01/22/2019

Authentication

YES

HTTP Method

POST

Content Type

application/json

Rate limited

YES

Requests per rate limit

10/min

Response Format

JSON

Change History

01/22/2019: add one more action type, fetch_agent_log, to support retrieve MetaAccess agent log

Use to do an action on multiple devices on your account

API URL

https://gears.opswat.com/o/api/v3.1/devices/action


Request Parameters

Key

Datatype

Parameter Type

Required

Description

Default

access_token

string

URL

Yes

access token which archived from OAuth authentication step

 

types

string

Body

Yes

Action Type:

  • exempt: exempt a device completely.

    • Apply: all devices exclude Unknown, Ignored, Out-of-license-usage devices

  • unexempt: unexempt device

    • Apply: all devices exclude Unknown, Ignored, Out-of-license-usage devices

  • ignore: ignore an unknown device

    • Apply: unknown devices only

  • unignore: undo ignore action.

    • Apply: ignored devices only

  • delete: delete devices

    • Apply: all devices

  • dhcprenew: force ME call a DHCP request

    • Apply: devices which installed a persistent agent only

  • re-identify: force ME re-identify the device

    • Apply: all devices exclude Unknown, Ignored, Out-of-license-usage devices

  • assign_to_group: assign devices to a group

    • Apply: all devices exclude devices with domain controller agent installed

  • fetch_agent_log : request to retrieve MetaAccess agent log on devices

 

ids

array<string>

Body

Optional

Device IDs of devices to be applied the action.

The request body must have ids parameter or macs parameter, but not both.

 

macs

array<string>

Body

Optional

MAC addresses of devices to be applied the action

The request body must have ids parameter or macs parameter, but not both.

 

params

object

Body

Optional

Required parameters for a specific action.

 

params.exempt_time

int

Body

Optional

Specify how long you want to exempt devices in hour. Value should be less than 65000

if this parameter equals 0, MetaAccess will exempt devices forever

0

params.group_id

string

Body

Optional

Specify which group (group id) you want to assign devices to

This parameter should be specified when action type is assign_to_group

default

Response HTTP Code

See 1.2. OAuth APIs


Response Parameters

Key

DataType

Description

id

string

Device ID or MAC address of a device

status

integer

action status. Value can be

  • -1: not support

  • 0: apply action failed

  • 1: apply action successfully

command_id

string

Only apply for fetch_agent_log action

Command ID of the action. This will be used in Get Report v3.0+.

This parameter will be empty if the action is failed/not supported (status is 01/0) or the action type is not fetch_agent_log

Example

Example Request: using Device ID

https://gears.opswat.com/o/api/v3.1/devices/action?access_token=TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R61234
{
"types" : "exempt",
"ids" : ["device123","device456", "device789"],
"params" : {
"exempt_time": 60
}
}

Example Response

[
{
"id": "device123",
"status": 1,
"command_id": ""
},
{
"id": "device456",
"status": 0,
"command_id": ""
},
{
"id": "device789",
"status": -1,
"command_id": ""
}
]

Example Request: using Device MAC address

https://gears.opswat.com/o/api/v3.1/devices/action?access_token=TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R61234
{
"types" : "fetch_agent_log",
"ids" : ["1A:2A:3A:4A:5A:6A","1B:2B:3B:4B:5B:6B", "1C:2C:3C:4C:5C:6C"],
"params" : {
"exempt_time": 60
}
}

Example Response

[
{
"id": "1A:2A:3A:4A:5A:6A",
"status": 1,
"command_id": "cdhk12j279h35k214"
},
{
"id": "1B:2B:3B:4B:5B:6B",
"status": 0,
"command_id": ""
},
{
"id": "1C:2C:3C:4C:5C:6C",
"status": -1,
"command_id": ""
}
]

History

Action

Version

URL

Device Action

3.0

Device Action v3.0

Delete

2.0

Delete Devices v2.0

Renew IP

Exempt

Unexempt

2.0

Devices Action v2.0

Device Action v2.0