Device Action v3.2

API version3.2
Last Update08/02/2019
AuthenticationYES
HTTP MethodPOST
Content Typeapplication/json
Rate limitedYES
Requests per rate limit10/min
Response FormatJSON
Change History08/02/2019: add one more action type, scan_threats, to support scan threat

Use to do an action on multiple devices on your account

API URL

Copy

Request Parameters

KeyDatatypeParameter TypeRequiredDescriptionDefault
access_tokenstringURLYesaccess token which archived from OAuth authentication step
typesstringBodyYes

Action Type:

  • exempt: exempt a device completely.

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

  • unexempt: unexempt device

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

  • 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: This action is only applicable for Windows persistent agent version 7.6.71.0+ and macOS persistent agent 10.4.123.0+ and Mobile agent

  • assign_to_group: assign devices to a group

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

  • fetch_agent_log: request to retrieve MetaDefender IT-OT Access agent log on devices

  • scan_threats: perform an on-demand threats scan on devices. This action is only applicable for Windows persistent agent version 7.6.206.0+ and macOS persistent agent 10.4.205.0+

idsarray<string>BodyOptionalDevice IDs of devices to be applied the action. The request body must have ids parameter or macs parameter, but not both.
macsarray<string>BodyOptionalMAC addresses of devices to be applied the action The request body must have ids parameter or macs parameter, but not both.
paramsobjectBodyOptionalRequired parameters for a specific action.
params.exempt_timeintBodyOptionalSpecify how long you want to exempt devices in hour. Value should be less than 65000 if this parameter equals 0, MetaDefender IT Access will exempt devices forever0
params.group_idstringBodyOptionalSpecify which group (group id) you want to assign devices to This parameter should be specified when action type is assign_to_groupdefault
params.full_scanintBodyOptionalOnly apply for scan_threats action 0: custom scan, 1: full scan
params.scan_typesarray<int>BodyOptionalOnly apply for scan_threats action Specify which types of custom scan agent will perform the scanning. Types are defined as below 0: Memory 1: System Volume 2: Portable Volumes 3: Additional Volumes 4: Specific Path 5: Boot Records
params.pathstringBodyOptionalOnly apply for scan_threats action Specify a location where agent will perform the scanning

Response HTTP Code

See APIs

Response Parameters

KeyDataTypeDescription
idstringDevice ID or MAC address of a device
statusinteger

action status. Value can be

  • -1: the action is not supported for a specified device
  • 0: failed to apply the action
  • 1: apply action successfully
command_idstringApply for fetch_agent_log action and scan_threats 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 -1/0) or the action type is not fetch_agent_log, scan_threats

Example

Example Request: using Device ID

Copy

Example Response

Copy

Example Request: using Device MAC address

Copy

Example Response

Copy

Example Request: scan_threats action

Copy

Example Response

Copy

History

ActionVersionURL
Device Action3.1Device Action v3.1
Device Action3.0Device Action v3.0
Delete2.0Delete Devices v2.0
Renew IP Exempt Unexempt2.0Devices Action v2.0 Device Action v2.0
Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard
Next to read:
Device Details v2.1
On This Page
Device Action v3.2API URLRequest ParametersResponse HTTP CodeResponse ParametersExampleHistory