Scan Health Configuration REST API

Overview

The Scan Health Configuration API allows administrators to configure automatic build failure when a scan detects zero components. This helps identify scan misconfigurations early in the CI/CD pipeline instead of producing empty scan results. Configuration supports hierarchical inheritance. Settings can be configured at the organization level and inherited by applications, or overridden at the application level.

Base URL

/api/v2/config/scanHealth/{ownerType}/{ownerId}

Authentication and Permissions

All endpoints require authentication.

Configuration Model

{
  "failOnZeroComponents": true | false | null
}

Inheritance Rules

Configuration is resolved using the following priority order:

• Application-level configuration
• Organization hierarchy
• Default behavior

By default, scans with zero components are allowed.

Endpoints

GET - Retrieve Configuration

Returns the directly stored configuration for the specified owner. This operation does not resolve inherited configuration values.

• Request

GET /api/v2/config/scanHealth/organization/{orgId}

GET /api/v2/config/scanHealth/application/{appId}

• Response - 200

{
    "failOnZeroComponents": true
}

An empty response indicates that no direct configuration exists for the specified owner.

• Response - 404

Owner not found

PUT - Create or Update Configuration

Creates or updates the scan health configuration for the specified owner.

• Request

PUT /api/v2/config/scanHealth/organization/{orgId}
Content-Type: application/json

• Response - 200

{
    "failOnZeroComponents": true
}

• Response - 400

Request body is null

• Response - 404

Owner not found

DELETE - Remove Configuration

Removes the direct configuration for the specified owner. After deletion, configuration inheritance applies again from the parent organization or default behavior.

• Request

DELETE /api/v2/config/scanHealth/organization/{orgId}

DELETE /api/v2/config/scanHealth/application/{appId}

• Response - 204

Configuration deleted successfully

• Response - 404

No configuration found for the specified owner

Scan Behavior

When failOnZeroComponents is enabled for an application, either directly or through inheritance:

Failure Response

When a scan detects zero components:

HTTP 400 Bad Request

Scan failed: zero components detected. This may indicate a scan misconfiguration.

Key Details

• The scan report is still generated and visible in the UI.
• The SBOM remains available for export and download.
• Policy evaluation results are persisted.
• Only the HTTP response returned to the CI/CD client indicates failure.
• Applies to CLI, CI/CD integrations, and continuous monitoring scans.

Examples

Enable at organization level

curl -u admin:admin123 -X PUT 
"https://iq-server/api/v2/config/scanHealth/organization/{orgId}" 
-H "Content-Type: application/json" 
-d '{"failOnZeroComponents": true}'

Enable at application level

curl -u admin:admin123 -X PUT 
"https://iq-server/api/v2/config/scanHealth/application/{appId}" 
-H "Content-Type: application/json" 
-d '{"failOnZeroComponents": true}'

Disable at application level

curl -u admin:admin123 -X PUT 
"https://iq-server/api/v2/config/scanHealth/application/{appId}" 
-H "Content-Type: application/json" 
-d '{"failOnZeroComponents": false}'

Revert application to inherited behavior

curl -u admin:admin123 -X DELETE 
"https://iq-server/api/v2/config/scanHealth/application/{appId}"

Check direct configuration

curl -u admin:admin123 
"https://iq-server/api/v2/config/scanHealth/application/{appId}"

Cascade Deletion

When an application or organization is deleted, its scan health configuration is automatically removed.

Audit Events

GET operations are not audited.