Release 2.4.1 API

January 14, 2025 (Updated January 30, 2025)

Before understanding the API release highlights, learn more about the API server URL to be used in your API requests by referring to the Know Your Qualys API Server URL section. For this API Release Notes, <qualys_base_url> is mentioned in the sample API requests.

What's New?

In this release, we have enhanced our configuration-based APIs by introducing new parameters to improve user activity tracking and logging. Furthermore, we have updated the Scripts APIs with additional parameters, enabling you to define and create parameterized scripts more effectively. 
Additionally, we have implemented a new API that allows for the deletion of invalid asset jobs.

New Parameters in Scripts APIs

The new parameters enables you to create a parameterized script. 

Input Parameters

The following parameters are added to the Scripts APIs:

Parameter Mandatory/Optional Data Type Description

hasParameters

Optional

(This is mandatory only if you want to define the params.key and params.value parameter.)

Boolean

Provide this value as true if you want to define the script parameters.

Default value is false.

Note: This parameter is only applicable when you want to create a parameterized script.

params.key

Mandatory

(This is mandatory when the hasParameters value is true.)

String

Provide the Base64 encoded string value.

params.value

Mandatory

(This is mandatory when the hasParameters value is true.)

String

Provide the Base64 encoded string value.

For more details on other input parameters, refer to CAR API User Guide.

Impacted APIs

The following APIs are impacted:

  • Update Scripts API
  • Update Scripts with GitHub API
  • Create Scripts API
  • Create Scripts with GitHub API

Updated API: Update Scripts API

New or Updated API Updated
API Endpoint /sm/v4/script/{Scriptid}
Method  PATCH
DTD or XSD changes Not Applicable

Sample: Update Scripts with Base64 ContentSample: Update Scripts with Base64 Content

API Request

curl -X PATCH
'<qualys_base_url>/sm/v4/script/{Scriptid}'
--header 'Accept: application/vnd.qualys.car.api.v4.0+json'
--header 'Authorization: Bearer <authToken>'
--header 'Content-Type: application/json'
--data-raw 
{
    "categoryId": 103,
    "content": "bHMgLWx0cg==",
    "description": "Sample description",
    "platform": "WINDOWS",
    "severity": "3",
    "threshold":300,
    "title": "Sample title",
    "typeId": 2,
    "languageId": 1,
    "scriptApprovalUserConsent": true,
    "hasParameters": true,
    "customQid": {
        "qid": "12345",
        "type": "Detection QID",
        "severity": "4",
        "qds": "75",
        "vulnerabilityType": "Potential",
        "cveIds": "CVE-2023-3452",
        "detectionLogic": "Use Script",
        "returnCodeStatusMap": [
            {
                "returnCode": "1",
                "status": "Not-Detected"
            },
            {
                "returnCode": "5",
                "status": "Detected"
            }
        ]
    },
     "params": [
        {
            "key": "string",
            "value": "string"
        }
    ]
}

Response

{
    "id"100010,
    "message""Updated Successfully."
}

Updated API: Update Scripts with GitHub API

New or Updated API Updated
API Endpoint /sm/v4/script/{Scriptid}
Method  PATCH
DTD or XSD changes Not Applicable

Sample: Update Scripts with GitHubSample: Update Scripts with GitHub

API Request

curl -X PATCH
'<qualys_base_url>/sm/v4/script/{Scriptid}'
--header 'Accept: application/vnd.qualys.car.api.v4.0+json'
--header 'Authorization: Bearer <authToken>'
--header 'Content-Type: application/json'
--data-raw 
{
    "categoryId": 605,
    "githubInputUrl": "<sample github url>",
    "gitHubToken": "<sample github token of private repo>",
    "gitHubUser": "<sample username>",
    "gitHubRepo": "<sample repo name>",
    "gitHubBranch": "<sample branch name>",
    "gitHubFilePath": "<sample github file path>",
    "description": "sample description",
    "platform": "WINDOWS",
    "severity": "3",
    "threshold":300,
    "title": "Sample title",
    "typeId": 2,
    "languageId": 1,
    "scriptApprovalUserConsent": true,
    "hasParameters": true,
    "customQid": {
        "qid": "12345",
        "type": "Detection QID",
        "severity": "4",
        "qds": "75",
        "vulnerabilityType": "Potential",
        "cveIds": "CVE-2023-3452",
        "detectionLogic": "Use Script",
        "returnCodeStatusMap": [
            {
                "returnCode": "1",
                "status": "Not-Detected"
            },
            {
                "returnCode": "5",
                "status": "Detected"
            }
        ]
    },
     "params": [
        {
            "key": "string",
            "value": "string"
        }
    ]
}

Response

{
    "id"100010,
    "message""Updated Successfully."
}

Updated API: Create Scripts API

New or Updated API Updated
API Endpoint (Deprecation timeline - June 2025) /sm/v4/script
API Endpoint (New Version) /sm/v5/script
Method  POST
DTD or XSD changes Not Applicable

Sample: Create Scripts with Base64 ContentSample: Create Scripts with Base64 Content

API Request

curl -X POST 
'<qualys_base_url>/sm/v5/script'
--header 'Accept: application/vnd.qualys.car.api.v5.0+json'
--header 'Authorization: Bearer <authToken>'
--header 'Content-Type: application/json'
--data-raw 
{
    "categoryId": 103,
    "content": "bHMgLWx0cg==",
    "description": "Sample description",
    "platform": "WINDOWS",
    "severity": "3",
    "threshold":300,
    "title": "Sample title",
    "typeId": 2,
    "languageId": 1,
    "scriptApprovalUserConsent": true,
    "hasParameters": true,
    "customQid": {
        "qid": "",
        "type": "Detection QID",
        "severity": "4",
        "qds": "75",
        "vulnerabilityType": "Potential",
        "cveIds": "CVE-2023-3452",
        "detectionLogic": "Use Script",
        "returnCodeStatusMap": [
            {
                "returnCode": "1",
                "status": "Not-Detected"
            },
            {
                "returnCode": "5",
                "status": "Detected"
            }
        ]
    },
     "params": [
        {
            "key": "string",
            "value": "string"
        }
    ]
}

Response

{
    "errorCode": "0",
    "message": "Script created successfully",
    "body": {
        "id": 100504
    }
}

Updated API: Create Scripts with GitHub API

New or Updated API Updated
API Endpoint (Deprecation timeline - June 2025) /sm/v4/script
API Endpoint (New Version) /sm/v5/script
Method  POST
DTD or XSD changes Not Applicable

Sample: Create Scripts with GitHubSample: Create Scripts with GitHub

API Request

curl -X POST 
'<qualys_base_url>/sm/v5/script'
--header 'Accept: application/vnd.qualys.car.api.v5.0+json'
--header 'Authorization: Bearer <authToken>'
--header 'Content-Type: application/json'
--data-raw 
{
    "categoryId": 605,
    "githubInputUrl": "<sample github url>",
    "gitHubToken": "<sample github token of private repo>",
    "gitHubUser": "<sample username>",
    "gitHubRepo": "<sample repo name>",
    "gitHubBranch": "<sample branch name>",
    "gitHubFilePath": "<sample github file path>",
    "description": "sample description",
    "platform": "WINDOWS",
    "severity": "3",
    "threshold":300,
    "title": "Sample title",
    "typeId": 2,
    "languageId": 1,
    "scriptApprovalUserConsent": true,
    "hasParameters": true,
    "customQid": {
        "qid": "",
        "type": "Detection QID",
        "severity": "4",
        "qds": "75",
        "vulnerabilityType": "Potential",
        "cveIds": "CVE-2023-3452",
        "detectionLogic": "Use Script",
        "returnCodeStatusMap": [
            {
                "returnCode": "1",
                "status": "Not-Detected"
            },
            {
                "returnCode": "5",
                "status": "Detected"
            }
        ]
    },
     "params": [
        {
            "key": "string",
            "value": "string"
        }
    ]
}

Response

{
    "errorCode": "0",
    "message": "Script created successfully",
    "body": {
        "id": 100504
    }
}

New Parameters in Configuration-based APIs

We have added new parameters to the configuration-based APIs related to assets, allowing the system to gather and log user activity effectively. These enhancements facilitate better tracking and auditing of user interactions with assets, ensuring increased transparency and control.

Input Parameters

The following parameters are added to the configuration-based APIs:

Parameter Mandatory/Optional Data Type Description
id Optional String Provide the ID of the user.
name Optional String Provide the name of the user.

For more details on other input parameters, refer to CAR API User Guide.

Impacted APIs

The following configuration-based APIs are impacted due the added parameters:

  • Add Assets to List of Blocked Assets API
  • Delete Blocked Assets API

  • Add Tags to the List of Blocked Tags API

  • Delete Blocked Tags API

  • Add Assets to List of Lab Assets API

  • Delete Lab Assets API

Updated API: Add Assets to List of Blocked Assets API

New or Updated API Updated
API Endpoint  /sm/v1/block-assets
Method POST
DTD or XSD changes Not Applicable

Sample: Add Assets to List of Blocked AssetsSample: Add Assets to List of Blocked Assets

API Request

curl -X POST 
'<qualys_base_url>/sm/v1/block-assets'
--header 'accept: application/json'
--header 'Content-Type: application/json'
--data 
    '{
    "ids": [4561,4562],
    "user": {
         "id": "bfd96a2f-854b-f8fd-8005-69374a3cd2b3",
         "name": "Username"
       }
     }

Response

{
  "body": {
    "success": {
      "ids": [
        4561
      ],
      "message": "Ids are processed"
    },
    "failure": {
      "ids": [
        4562
      ],
      "message": "Ids are Invalid"
    }
  }
}

Updated API: Delete Blocked Assets API

New or Updated API Updated
API Endpoint  /sm/v1/block-assets/delete
Method POST
DTD or XSD changes Not Applicable

Sample: Delete Blocked AssetsSample: Delete Blocked Assets

API Request

curl -X POST 
'<qualys_base_url>/sm/v1/block-assets/delete'
--header 'accept: application/json'
--header 'Content-Type: application/json'
--data 
    '{
    "ids": [4561,4562],
    "user": {
         "id": "bfd96a2f-854b-f8fd-8005-69374a3cd2b3",
         "name": "Username"
       }
     }

Response

{
  "body": {
    "success": {
      "ids": [
        4561
      ],
      "message": "Ids are processed"
    },
    "failure": {
      "ids": [
        4562
      ],
      "message": "Ids are Invalid"
    }
  }
}

Updated API: Add Tags to the List of Blocked Tags API

New or Updated API Updated
API Endpoint  /sm/v1/block-tags
Method POST
DTD or XSD changes Not Applicable

Sample: Add Tags to the List of Blocked TagsSample: Add Tags to the List of Blocked Tags

API Request

curl -X POST 
'<qualys_base_url>/sm/v1/block-tags'
--header 'accept: application/json'
--header 'Content-Type: application/json'
--data 
    '{
    "ids": [4561,4562],
    "user": {
         "id": "bfd96a2f-854b-f8fd-8005-69374a3cd2b3",
         "name": "Username"
       }
     }

Response

{
  "body": {
    "success": {
      "ids": [
        4561
      ],
      "message": "Ids are processed"
    },
    "failure": {
      "ids": [
        4562
      ],
      "message": "Ids are Invalid"
    }
  }
}

Updated API: Delete Blocked Tags API

New or Updated API Updated
API Endpoint  /sm/v1/block-tags/delete
Method POST
DTD or XSD changes Not Applicable

Sample: Delete Blocked TagsSample: Delete Blocked Tags

API Request

curl -X POST 
'<qualys_base_url>/sm/v1/block-tags/delete'
--header 'accept: application/json'
--header 'Content-Type: application/json'
--data 
    '{
    "ids": [4561,4562],
    "user": {
         "id": "bfd96a2f-854b-f8fd-8005-69374a3cd2b3",
         "name": "Username"
       }
     }

Response

{
  "body": {
    "success": {
      "ids": [
        4561
      ],
      "message": "Ids are processed"
    },
    "failure": {
      "ids": [
        4562
      ],
      "message": "Ids are Invalid"
    }
  }
}

Updated API: Add Assets to List of Lab Assets API

New or Updated API Updated
API Endpoint   /sm/v1/lab-assets
Method POST
DTD or XSD changes Not Applicable

Sample: Add Assets to List of Lab AssetsSample: Add Assets to List of Lab Assets

API Request

curl -X POST 
'<qualys_base_url>/sm/v1/lab-assets'
--header 'accept: application/json'
--header 'Content-Type: application/json'
--data 
    '{
    "ids": [4561,4562],
    "user": {
         "id": "bfd96a2f-854b-f8fd-8005-69374a3cd2b3",
         "name": "Username"
       }
     }

Response

{
  "body": {
    "success": {
      "ids": [
        4561
      ],
      "message": "Ids are processed"
    },
    "failure": {
      "ids": [
        4562
      ],
      "message": "Ids are Invalid"
    }
  }
}

Updated API: Delete Lab Assets API

New or Updated API Updated
API Endpoint  /sm/v1/lab-assets/delete
Method POST
DTD or XSD changes Not Applicable

Sample: Delete Lab AssetsSample: Delete Lab Assets

API Request

curl -X POST 
'<qualys_base_url>/sm/v1/lab-assets/delete'
--header 'accept: application/json'
--header 'Content-Type: application/json'
--data 
    '{
    "ids": [4561,4562],
    "user": {
         "id": "bfd96a2f-854b-f8fd-8005-69374a3cd2b3",
         "name": "Username"
       }
     }

Response

{
  "body": {
    "success": {
      "ids": [
        4561
      ],
      "message": "Ids are processed"
    },
    "failure": {
      "ids": [
        4562
      ],
      "message": "Ids are Invalid"
    }
  }
}

New API: Delete Invalid Asset Jobs

New or Updated API New
API Endpoint  /sm/v1/assetjobs/delete
Method POST
DTD or XSD changes Not Applicable

This API is used to delete invalid asset jobs.

Input ParametersInput Parameters

Parameter Mandatory/Optional Data Type Description
ids Mandatory List Provide the list of asset job IDs.
user Optional String Provide the details of a user such as ID or name.
id Optional String Provide the ID of the user.
name Optional String Provide the name of the user.

Sample: Delete Asset JobsSample: Delete Asset Jobs

API Request

curl -X POST
'<qualys_base_url>/sm/v1/assetjobs/delete' 
--header 'Content-Type: application/json' 
--header 'Authorization: <Bearer Token> '
--data 
'{
  "ids": [1000007,1000009],
   "user": {
      "id": "bfd96a2f-854b-f8fd-8005-69374a3cd2b3",
      "name": "name of user"
    }
}'

Response

{
  "body": {
        "success": {
            "ids": [
                1000007
            ],
            "message": "Ids are processed"
        },
        "failure": {
            "ids": [
                1000009
            ],
            "message": "Ids are Invalid"
        }
    }
}