Skip to main content

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.

Note

The Scan Health Configuration REST API is available in IQ Server 204 and later. In IQ Server 203 or earlier, requests to this endpoint can return HTTP 404 because the API is not available.

Base URL

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

Path Parameter

Type

Value

Description

ownerType

string

application or organization

Level where the configuration is applied

ownerId

string

Internal ID

Internal ID of the application or organization

Authentication and Permissions

All endpoints require authentication.

Operation

Required Permission

GET

View IQ Elements (READ)

PUT

Edit IQ Elements (WRITE)

DELETE

Edit IQ Elements (WRITE)

Configuration Model

{
  "failOnZeroComponents": true | false | null
}

Field

Type

Description

failOnZeroComponents

Boolean

true fails scans with zero components. false explicitly disables the behavior. null or absent inherits configuration from the parent organization.

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:

Scenario

Behavior

Scan finds components

Normal evaluation behavior

Scan finds zero components

Report is persisted, SBOM is activated, and the build returns HTTP 400

Scan finds only unknown components

Normal evaluation behavior. Unknown components count as detected components.

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.

Operation

Audit Domain

Audit Type

PUT

governance.scan-health

configure

DELETE

governance.scan-health

delete