AGMS Home

API Changes

Using the Qualys API? You can see the following API changes when AGMS is enabled for your subscription.

Jump to a section below:

List Asset Group: All group is no longer listed in output

The Asset Group API does not list the ALL group in the XML output. The API only lists the individual asset groups. Following is a sample when AGMS is enabled:

API request

curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -X "POST" -d
"action=list"
"https://qualysapi.qualys.com/api/2.0/fo/asset/group/"

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ASSET_GROUP_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/asset/group/asset_group_list_output.dtd">
<ASSET_GROUP_LIST_OUTPUT>
  <REQUEST>
    <DATETIME>2019-11-09T08:22:20Z</DATETIME>
    <USER_LOGIN>john_doe</USER_LOGIN>
    <RESOURCE>https://qualysapi.qualys.com/api/2.0/fo/asset/group/</RESOURCE>
    <PARAM_LIST>
      <PARAM>
        <KEY>action</KEY>
        <VALUE>list</VALUE>
      </PARAM>
    </PARAM_LIST>
  </REQUEST>
  <RESPONSE>
    <DATETIME>2019-11-09T08:22:20Z</DATETIME>
    <ASSET_GROUP_LIST>
      <ASSET_GROUP>
        <ID>1024368</ID>
        <TITLE><![CDATA[AG_VM_1]]></TITLE>
        <NETWORK_ID>0</NETWORK_ID>
        <IP_SET>
          <IP_RANGE>10.10.30.10-10.10.30.30</IP_RANGE>
        </IP_SET>
      </ASSET_GROUP>
  ...
      <ASSET_GROUP>
        <ID>7038084</ID>
        <TITLE><![CDATA[Windows]]></TITLE>
        <NETWORK_ID>0</NETWORK_ID>
        <IP_SET>
          <IP>10.10.10.81</IP>
        </IP_SET>
      </ASSET_GROUP>
    </ASSET_GROUP_LIST>
  </RESPONSE>
</ASSET_GROUP_LIST_OUTPUT>

List Asset Group: List asset groups with business unit IDs

When you list asset groups and include show_attributes=ASSIGNED_UNIT_IDS in the request, you cannot see any asset groups listed for business units with the All asset group.

API request

curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -X "POST" -d
"action=list&echo_request=1&show_attributes=ASSIGNED_UNIT_IDS"
"https://qualysapi.qualys.com/api/2.0/fo/asset/group/"

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ASSET_GROUP_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/asset/group/asset_group_list_output.dtd">
<ASSET_GROUP_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2020-02-05T05:18:05Z</DATETIME>
  </RESPONSE>
</ASSET_GROUP_LIST_OUTPUT>

List Asset Group: Output will now show domain netblocks

When you list asset groups and include show_attributes=All in the request, the domain list in the output displays the netblock for each domain when a netblock is defined. Without AGMS you cannot see netblock information in the output.

API request

curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -X "POST" -d
"action=list&ids=5443081&show_attributes=ALL"
"https://qualysapi.qualys.com/api/2.0/fo/asset/group/"

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ASSET_GROUP_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/asset/group/asset_group_list_output.dtd">
<ASSET_GROUP_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2020-01-16T04:16:38Z</DATETIME>
    <ASSET_GROUP_LIST>
      <ASSET_GROUP>
        <ID>5443081</ID>
        <TITLE><![CDATA[AG1]]></TITLE>
        <OWNER_USER_ID>64060</OWNER_USER_ID>
        <LAST_UPDATE>2020-01-16T04:16:07Z</LAST_UPDATE>
        <BUSINESS_IMPACT>High</BUSINESS_IMPACT>
        <CVSS_ENVIRO_CDP>Not Defined</CVSS_ENVIRO_CDP>
        <CVSS_ENVIRO_TD>Not Defined</CVSS_ENVIRO_TD>
        <CVSS_ENVIRO_CR>Not Defined</CVSS_ENVIRO_CR>
        <CVSS_ENVIRO_IR>Not Defined</CVSS_ENVIRO_IR>
        <CVSS_ENVIRO_AR>Not Defined</CVSS_ENVIRO_AR>
        <DOMAIN_LIST>
          <DOMAIN netblock="10.10.10.10-10.10.10.12">abc123.com</DOMAIN>
        </DOMAIN_LIST>
        <COMMENTS><![CDATA[My-Comments]]></COMMENTS>
        <OWNER_USER_NAME><![CDATA[Joe User (Manager)]]></OWNER_USER_NAME>
      </ASSET_GROUP>
    </ASSET_GROUP_LIST>
  </RESPONSE>
</ASSET_GROUP_LIST_OUTPUT>

Add IPs: Unit Managers/Scanners must add IPs to All group when assigned the All group and specify network ID

When a Unit Manager or Scanner with the Add assets permission adds new IPs to the subscription, you must select an asset group to add the IPs to it. The available options depend on whether the user is assigned to the All group.

  • When a user making the request is assigned the All group (with or without other asset groups) the user must specify ag_title=All in the API request. The user must also specify network_id in the request if the subscription has the Network Support feature enabled.
  • When the user making the request was NOT assigned the All group, the user must specify the title of one of their assigned asset groups, and network_id is optional for accounts with the Network Support feature enabled.

In the following sample, ag_title=All and network_id=114075 is specified in the request.

API request

curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -X "POST" -d
"action=add&ips=10.111.25.20&enable_vm=1&ag_title=All&network_id=114075"
"https://qualysapi.qualys.com/api/2.0/fo/asset/ip/"

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "https://qualysapi.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
  <RESPONSE>
    <DATETIME>2020-01-20T06:33:49Z</DATETIME>
    <TEXT>IPs successfully added to Vulnerability Management</TEXT>
  </RESPONSE>
</SIMPLE_RETURN>

In the following sample, ag_title=All is NOT specified in the request (a different group is specified) but the user making the request was assigned the All group. The message All is assigned to user, so please specify All in ag_title appears in the output.

API request

curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -X "POST" -d
"action=add&echo_request=0&ips=10.111.25.20&enable_vm=1&ag_title=MyGroup"
"https://qualysapi.qualys.com/api/2.0/fo/asset/ip/"

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "https://qualysapi.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
  <RESPONSE>
    <DATETIME>2020-01-20T06:33:49Z</DATETIME>
    <CODE>1905</CODE>
    <TEXT>All is assigned to user, so please specify All in ag_title</TEXT>
  </RESPONSE>
</SIMPLE_RETURN>

Update IPs: Unit Managers/Scanners must specify network ID

When a Unit Manager or Scanner updates IPs using the API, the user must specify network_id in the request if the subscription has the Network Support feature enabled.

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -d
"action=update&ips=1.1.1.1-1.1.1.254&network_id=114075&tracking_method=DNS"
"https://qualysapi.qualys.com/api/2.0/fo/asset/ip/"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "https:// qualysapi.qualys.com /api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
  <RESPONSE>
    <DATETIME>2020-02-20T09:42:12Z</DATETIME>
    <TEXT>IPs successfully updated</TEXT>
  </RESPONSE>
</SIMPLE_RETURN>

Create Scanner Appliance: Unit Managers/Scanners can add scanner appliance to Manager created asset group when assigned the All group

When a Unit Manager or Scanner with the Manage virtual scanner appliances permission adds new virtual scanner appliances to the subscription, the user must select an asset group to add the scanner to. The asset group ID specified in the API request must be a valid asset group ID in the user’s account. If the Unit Manager/Scanner is assigned the All group then the user has the Manager created asset groups which are in scope of the business unit belonging to the user, as previously described. The user can specify the ID for any of the Manager-created asset groups in their scope when adding a scanner appliance.

In the following example, the user specified a valid asset group ID in their account.  

API request

curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -d
"action=create&name=MyScanner&asset_group_id=5480600"
"https://qualysapi.qualys.com/api/2.0/fo/appliance/"

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE APPLIANCE_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/appliance/appliance_create_output.dtd">
<APPLIANCE_CREATE_OUTPUT>
  <RESPONSE>
    <DATETIME>2020-01-28T05:11:12Z</DATETIME>
    <ID>777</ID>
    <NAME>MyScanner</NAME>
    <ACTIVATION CODE>70171268144764</ACTIVATION CODE>
    <REMAINING_QVSA_LICENSES>4</REMAINING_QVSA_LICENSES>
  </RESPONSE>
</APPLIANCE_CREATE_OUTPUT>

 

In the example below, the user specified an asset group ID that is not in their account so the message “parameter asset_group_id has invalid value” appears in the output.

API request

curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -d
"action=create&name=MyScanner&asset_group_id=5475586"
"https://qualysapi.qualys.com/api/2.0/fo/appliance/"

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "https://qualysapi.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
  <RESPONSE>
    <DATETIME>2020-01-28T05:11:12Z</DATETIME>
    <CODE>1905</CODE>
    <TEXT>parameter asset_group_id has invalid value (Given Asset Group is not in user's scope: 5475586)</TEXT>
  </RESPONSE>
</SIMPLE_RETURN>

Add User: Asset Groups cannot be assigned to Contact user

When AGMS is enabled, users with the Contact user role cannot be assigned asset groups. When you create a new Contact user using the Add User API (/msp/user.php) you get an error when you include asset groups in the request. Here is an example of a request to add a new Contact user and asset group AG1 is specified in the request.

API request

curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -d
"action=add&user_role=contact&business_unit=BU1&first_name=Joe&last_name=User&title=Security+Consultant&phone=6508016100&[email protected]&address1=919+Hillsdale+Blvd&city=Foster+City&country=United+States+of+America&state=California&zip_code=94404"
"https://qualysapi.qualys.com/msp/user.php"

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE USER_OUTPUT SYSTEM "https://qualysapi.qualys.com/user_output.dtd">
<USER_OUTPUT>
  <API name="user.php" username="user" at="2019-11-05T04:24:50Z" />
  <RETURN status="FAILED" number="1905">
    <MESSAGE><![CDATA[Invalid value for 'asset_groups' : AG1. This asset group is not accessible.]]></MESSAGE>
  </RETURN>
</USER_OUTPUT>

Scan List: Update to Scan List Output for Sub-users 

The VM Scan List API (/api/2.0/fo/scan/?action=list) is used to list vulnerability scans in the user's account. The Compliance Scan List API (/api/2.0/fo/scan/compliance/?action=list) is used to list compliance scans in the user's account. 

We have made changes to the list of scans that are visible to sub-users. When a sub-user uses the API to list vulnerability or compliance scans, the XML output includes the following scans:

  • Scans launched by the sub-user
  • Finished scans launched by Managers on the user's assigned assets (assets in your user scope). Sub-users can only view scans by their Managers that are completed with processed scan results. 

When an asset in the sub-user's scope is purged by a Manager, scans for that asset are no longer appear in the scan list for the sub-user. 

See Changes to Scans List to learn more. 

API request (list vulnerability scans):

curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -d
"action=list" "https://qualysapi.qualys.com/api/2.0/fo/scan/"

API request (list compliance scans):

curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -d
"action=list" "https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/"

Changes to API Error Messages

Several error messages are changed.

Add Asset Group with title that already exists

Old message

<TEXT>parameter title has invalid value: An asset group with title ‘Title' already exists. Please use a different title</TEXT>

New message

<TEXT> (Asset Group name - An asset group with name Title already exists. Please use a different title)</TEXT>

Delete Asset Group with invalid asset group ID

Old message

<TEXT>parameter Asset Group has invalid value: Tried to delete invalid Asset Group - NNNN. Asset Group id does not exist or you do not have permission to delete this Asset Group</TEXT>

New message

<TEXT> (Invalid Parameter Ids Data not found for Asset Group, NNNN)</TEXT>

Sub-user adds IP that is not in scope

Old message

<TEXT> parameter IPs has invalid value: One or more IPs are not assigned to this user: N.N.N.N-N.N.N.N</TEXT>

New message

<TEXT> (IPs N.N.N.N-N.N.N.N are not in user account scope.)</TEXT>

 

 

© 2025 Qualys, Inc. All rights reserved. Privacy Policy. Last updated: November, 2025