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 |
Boolean |
Provide this value as Default value is Note: This parameter is only applicable when you want to create a parameterized script. |
params.key |
Mandatory (This is mandatory when the |
String |
Provide the Base64 encoded string value. |
params.value |
Mandatory (This is mandatory when the |
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" } } }