Uninstall Multiple Agents

[POST] /qps/rest/2.0/uninstall/am/asset

Bulk uninstall cloud agents matching the specified filter criteria, and remove associated agent hosts from your subscription.

Filter criteria required - For a bulk request it is mandatory to add this filter criteria in <ServiceRequest>:

<Criteria field="tagName" operator="EQUALS">Cloud Agent</Criteria>

Providing at least one criterion in the Service Request is mandatory for bulk uninstallation of agents.

Good to Know - A request to uninstall agents makes a call to the Qualys Cloud Platform to purge the host scan data (findings) for the agent hosts and remove the agent hosts from your subscription

Permissions required - Managers with full scope. Other users must have these permissions: Access Permission “API Access” and CA Agent Permission “Uninstall Agent”.

Input ParametersInput Parameters

To uninstall all agents, nothing other than the filter tagName EQUALS Cloud Agent is recommended. The more filters added to the request we’ll uninstall a more refined list of agents.

Use the following <ServiceRequest> parameters to select agents you want to uninstall. These parameters act as filters. When multiple filters are specified, parameters are combined using a logical AND.

Filter operators are available for use with <ServiceRequest> parameters.

Use of NOT EQUALS operator is now disabled during agent uninstall. This is to avoid unintended consequences of Tags or Assets being deleted or updated. The service response includes an error message if you use the NOT EQUALS operator while uninstalling an agent.

Supported filter operators

Parameter	Mandatory /Optional	Data Type	Description
id	Optional	integer	Asset ID of the agent host.
name	Optional	string	Asset name of the agent host.
created	Optional	date	Date when the agent host was added to your asset inventory (i.e. when the agent was provisioned). Date is specified in UTC/GMT format, i.e. YYYY-MM-DD[THH:MM:SSZ]
updated	Optional	date	Date when the agent was last updated, such as activation, host name change, etc. Date is specified in UTC/GMT format.
tagName	Mandatory	string	Asset tag name assigned to the agent host. All agent hosts are assigned the tag Cloud Agent.
agentUuid	Optional	string	Agent ID (UUID) of the Agent host.

Sample - Uninstall agents in bulkSample - Uninstall agents in bulk

API request

Curl request:
curl --location '<qualys_base_url>/qps/rest/2.0/uninstall/am/asset/' \
--header 'Content-Type: application/xml' \
--header 'Authorization: Basic <Authorization_Token>' \
--data '
<?xml version="1.0" encoding="UTF-8" ?>

Contents of uninstall_all_agents.xml

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <filters>
        <Criteria field="tagName" operator="EQUALS">Cloud Agent</Criteria>
    </filters>
</ServiceRequest>

Response


<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/xsd/2.0/am/asset.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>4</count>
    <data>
        <Asset>
            <id>59284297</id>
        </Asset>
        <Asset>
            <id>60423255</id>
        </Asset>
        <Asset>
            <id>60451458</id>
        </Asset>
        <Asset>
            <id>61527815</id>
        </Asset>
    </data>
</ServiceResponse>

Sample: Uninstall agents using UUIDSample: Uninstall agents using UUID

In case of agent UUID, use the EQUALS operator for uninstalling a single agent or use the IN operator with comma separated UUID values for bulk uninstall.

Sample API Request

curl -u fo_username:password -X POST -H "Content-Type: text/xml" -H "Cache-Control: no-cache" --data-binary @uninstall_all_agents.xml "<qualys_base_url>/qps/rest/2.0/uninstall/am/asset/"

“file.xml” contains the request POST data.

Input Data

  
Request POST data: (Contents of file.xml)
<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <filters>
        <Criteria field="agentUuid" operator="IN">1d71c07e-f1b0-42df-918b-01b231489b86,0285fead-0014-465e-8840-6457ad482bb3</Criteria>
    </filters>
</ServiceRequest>

Use the EQUALS operator for uninstalling a single agent or use the IN operator with comma separated UUID values for bulk uninstall.

Response

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/xsd/2.0/am/asset.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>2</count>
    <data>
        <Asset>
            <id>712038</id>
        </Asset>
        <Asset>
            <id>2532638</id>
        </Asset>
    </data>
</ServiceResponse>

XSD

<platform API server>/qps/xsd/2.0/am/asset.xsd