Advantages of CSAM Host Asset API

The CyberSecurity Asset Management (CSAM) Host Asset API is the modern way to retrieve host and asset data from your Qualys subscription. It is designed to replace the legacy Asset Management & Tagging (AM) API for asset search and inventory use cases, and it offers significant advantages in speed, reliability, and ease of use.

The table below provides the legacy AM APIs and CSAM Host Asset APIs:

This topic explains those advantages and shows you how to get started, including sample requests and responses so you can see exactly what to expect.

The table below summarizes how the CSAM Host Asset API compares to the legacy AM API.

Key Advantages

Simpler, More Secure Authentication

Instead of sending your username and password with every single request, the CSAM API uses a security token. You request the token once, and then reuse it for all your calls until it expires.

• Keeps your credentials out of scripts and automated jobs.
• Makes it easy to rotate credentials without changing your integration.
• Works smoothly with scheduled jobs and automation tools, with no need to log in interactively each time.

This is one of the most noticeable improvements for anyone running frequent or automated requests.

Faster Performance, Even at Large Scale

The CSAM API is built on a search-optimized data store designed specifically for fast lookups across very large numbers of assets. It also runs independently from the main portal, so heavy API usage does not slow down or compete with your other Qualys activities.
This means fewer slowdowns, fewer timeouts, and more consistent response times, even when you are working with large asset collections or applying updates such as tags across many assets at once.

Reliable Paging Through Large Results

When retrieving large numbers of assets, the CSAM API uses a paging method that stays equally fast no matter how many pages you have already retrieved, and remains stable even if asset data changes while your export is in progress. This makes it well suited to full inventory pulls and ongoing data synchronization.

One Complete Asset Record

Each CSAM asset record brings together information that previously required several separate calls to assemble, including:

• Core asset details such as name, addresses, and identifiers
• Hardware and operating system information
• Installed software, open ports, volumes, user accounts, and network interfaces
• Cloud details for AWS, Azure, Google Cloud, Oracle Cloud, and IBM Cloud
• Tags, risk score, and business context
• External attributes such as WHOIS and domain information

You get a single, complete picture of each asset in one response.

Request Only What You Need

The CSAM API lets you specify exactly which fields you want returned. This keeps responses smaller and easier to work with, especially when you only need a handful of fields rather than the entire asset record. The legacy AM API always returns its full, fixed set of fields.

Modern, JSON-First Design

The CSAM API uses JSON by default, which is the format most modern tools and programming languages work with most easily. XML is also available if you need it. The legacy AM API supports XML only.

Built for Automation

The CSAM API is designed with automated and scheduled integrations in mind. You can combine a last-updated filter with paging to reliably pull only what has changed since your last sync, making it a strong fit for keeping external systems, such as a CMDB or SIEM, up to date.
 

Getting Started

To start using the CSAM HostAsset API, you will need a security token, which you obtain once and then include with each request.

Step 1: Get Your Token

Send your service account credentials to the token endpoint to receive your token:
 

curl-X POST 
  "https://gateway.<pod>.apps.qualys.com/auth"
  -H "Content-Type: application/x-www-form-urlencoded"
  -d "username=<your-username>&password=<your-password>&token=true&permissions=true"

Step 2: Use the Token in Your Requests

Include the token in the Authorization header of every CSAM API call:

Authorization: Bearer <your-token>

Step 3: Request Asset Data

Here is an example request that searches for assets and returns up to 300 results per page:

curl-X POST
"<qualys_base_url>/rest/2.0/search/am/asset?pageSize=300"
  -H "Authorization: Bearer <your-token>"
  -H "Content-Type: application/json"
  -d @filter.json

Example: Searching for an Asset

The example below shows a simple search request and the corresponding response, so you can see the structure of the data the CSAM API returns. All of the asset's details, including hardware, agent status, cloud information, and tags, are returned together in a single, organized record.

Request

curl -X POST 
  "<qualys_base_url>/rest/2.0/search/am/asset?pageSize=300" 
  -H "Authorization: Bearer <your-token>" 
  -H "Content-Type: application/json" 
  -d '{
    "filters": [
      {
        "field": "qwebHostId",
        "operator": "EQUALS",
        "value": "14119912"
      }
    ]
  }'

Response

{
  "responseCode": "SUCCESS",
  "count": 1,
  "lastSeenAssetId": null,
  "hasMore": 0,
  "assetListData": {
    "asset": [
      {
        "assetId": 59527607,
        "assetType": "HOST",
        "fqdn": "ip-172-31-16-113.us-east-2.compute.internal",
        "hardware": { "manufacturer": "Xen Project" },
        "agent": {
          "platform": "Linux",
          "chirpStatus": "Inventory Scan Complete"
        },
        "cloudProvider": {
          "aws": {
            "ec2": {
              "instanceId": "i-0e7714063be243fa1",
              "instanceType": "t2.micro"
            }
          }
        },
        "tagList": {
          "tag": [ { "tagId": 134181958, "tagName": "Cloud Agent" } ]
        }
      }
    ]
  }
}

Summary

The CSAM HostAsset API gives you faster performance, simpler authentication, a more complete asset record, and a design built for automation at scale. For any new integration and for migrating existing ones, the CSAM HostAsset API is the recommended choice.

For more information on CSAM Asset Host Data APIs, refer to CSAM Online Help.