Skip to main content
Skip table of contents

Scan API

This guide describes the REST APIs exposed by the KF AgileSec Platform for managing scan execution and retrieving scan status programmatically. It covers authentication and authorization, required request headers, callback registration, and supported API endpoints.

1. Introduction

The information in this document is intended for developers and system integrators who want to automate scan workflows or integrate the platform with external applications and monitoring systems.

2. Authentication and Authorization

2.1 Generating an API Token

To generate an API token, follow these steps as an organization administrator:

  1. Sign in to the platform using an organization administrator account.

  2. Navigate to Settings → Access Tokens.

  1. On the API Token screen, click Generate Token.

  2. In the Generate Token form, enter the following:

    • Token Name (required): Enter a short, descriptive name.

    • Description (optional): Provide details about the intended use.

    • Token Type (required): Select API Token.

    • Expiration Time (required): Choose an expiry from the dropdown.

  1. Click Generate.

  2. Copy the token immediately and store it in a secure secrets store (for example, a password manager or Vault). The token will not be shown again.

3. HTTP Headers

The following HTTP request headers are supported:

Header name

Required

Description

content-type

Y

application/json

isg-api-token

Y

API token used to authenticate the request. Include this header on all API calls (for example: isg-api-token: <token>).

4. Callback Registration

To receive scan status updates for API-initiated scans, you must register one or more callback endpoints. Registering callback endpoints lets you reference a pre-approved endpoint by Callback ID, so you don’t need to send sensitive callback credentials with each scan request.

4.1 Registering a callback endpoint

Follow these steps as an organization administrator:

  1. Sign in to the platform using an organization administrator account.

  2. Navigate to Settings → Callback Endpoints.

  1. Click Register.

  2. In the Register New Endpoint form, enter the following:

    • Name: A descriptive label (for example, scans-callback-prod). Max 200 characters.

    • Callback URL: The full callback URL (HTTPS recommended). Max 200 characters.

    • Authentication Type: Select the method supported by your endpoint: None, Bearer Token, or API Token.

    • Header Name (for API Token only): The custom header name your endpoint expects (for example, X-Custom-Auth).

    • Token Value (Bearer Token or API Token): The secret credential.

  1. Click Register. The system verifies the endpoint is reachable.

4.2 Retrieving the Callback ID

  1. Return to the Callback Endpoints screen.

  2. Find the endpoint you registered.

  3. Select Action → Copy Callback ID.

  4. Use the Callback ID when configuring scans.

4.3 Callback Authentication

As of v3.4.0, the platform supports three callback authentication types: None, Bearer Token, and API Token.

Callback credentials are always stored encrypted in the database.

5. API Reference

This section describes the endpoints used to create and execute scans.

5.1 Create and Execute Scan

Endpoint

POST https://<agilesec-platform-url>/v3/scan/create

Purpose

Creates a new sensor configuration and immediately triggers an on-demand scan execution.

Request body

CODE 
{
  "sensorType": "<sensor type>",
  "sensorName": "<sensor name>",
  "sensorConfig": {/* sensor-specific config object */},
  "priority": "low",
  "callbackId": "<callback ID>",
  "incrementalScan": false,
  "autoResolutionInterval": 30,
  "labels": [
    { "<label name>": "<label value>" }
  ]
}

sensorConfig is sensor-specific. Depending on the sensorType you are using, refer to the corresponding Sensor User Guide for the required sensorConfig payload format and examples.

Request body parameters

Name

Type

Required

Description

sensorType

String

Y

The type of sensor to use for the scan.

sensorName

String

Y

A unique name for the sensor.

sensorConfig

Object

Y

Configuration specific to the sensor type.

priority

String

N

Scan priority: high, medium, low. Default: low. See Common Parameters → Scan Priority for details.

callbackId

String

N

Registered callback endpoint Id. See Callback Registrationon how to get callback Id

incrementalScan

Boolean

N

Enables incremental scanning. Default: false.

autoResolutionInterval

Integer

N

Interval (in days) for auto-resolution of missing findings. Default: platform/system configuration.

labels

Array[Object]

N

Custom labels. See Common Parameters → Labels.

Response

Returns an HTTP status code and a response payload indicating the scan request submission status.

Response HTTP status codes

  • 200 OK: Success.

  • 400 Bad Request: Invalid parameters or Validation Failed.

  • 401 Unauthorized: Invalid Token.

  • 404 Not Found: Sensor Type or Callback ID not found.

Response payload
CODE 
{
  "sensorId": "<sensorId>",
  "executionId": "<executionId>",
  "status": "successful",
  "message": "Create new sensor and trigger scan successfully"
}
Response Payload Attributes

Name

Type

Description

sensorId

String

Unique identifier of the sensor created for the scan

executionId

String

Unique identifier for the scan execution.

status

String

Submission status. Value is successful or failed.

message

String

Additional details about the submission result.

400 Bad Request

Issue

Error Message

How to Fix

Missing Field

“Missing required field: <fieldName>.”

Add the missing mandatory field (sensorName, sensorType, sensorConfig) to your JSON body.

Invalid Data Type

“Invalid type for <fieldName>: expected <type>.”

Fix the data type:

  • sensorName/sensorType: String

  • sensorConfig: Object {}

  • incrementalScan: Boolean (true/false)

  • autoResolutionInterval: Integer

Unexpected Field

“Unexpected field '<fieldName>' found in request body.”

Remove any field not in the allowed list from the JSON payload.

Invalid Priority

“Invalid type or value for priority: expected string [‘low’, ‘medium’, ‘high’].”

Use strictly 'low', 'medium', or 'high'.

Invalid Config

“Invalid input for sensorConfig."

Review the Sensor Config Parameters reference for your specific sensor type (e.g., incorrect Git URL or Artifactory token format).

401 Unauthorized

Issue

Error Message

Possible Causes

How to Fix

Access Denied

“Unauthorized access.”

  • Token not found in header

  • Token expired or revoked

  • User inactive or deleted

  • Organization trial expired

  • Verify isg-api-token header is present.

  • Generate a new API token in Settings → Access Tokens.

  • Contact your Organization Admin to check your user status.

  • Check Organization license/trial status.

404 Not Found

Issue

Error Message

Description

How to Fix

Invalid Sensor Type

“Unknown sensorType: no matching record found for <providedValue>."

The sensorType provided is not supported by the platform.

  • Check specific spelling of sensorType (e.g., "GIT Sensor", "Artifactory Sensor").

Invalid Callback ID

“callbackId not found.”

The callbackId provided does not exist in your organization.

5.2 Execute Scan

Endpoint

POST https://api.agilesec.net/v3/scan/execute

Purpose

Executes an existing sensor created using the Create and Execution Scan API.

Request body

CODE 
{
  "sensorId": "<sensorId>"
}
Request body parameters

Name

Type

Required

Description

sensorId

String

Y

The unique identifier of the existing sensor to execute.

Response

Returns an HTTP status code and a response payload indicating the execute request submission status.

Response HTTP status codes

  • 200 OK: Success.

  • 400 Bad Request: Invalid parameters or Validation Failed.

  • 401 Unauthorized: Invalid Token.

  • 404 Not Found: Sensor Type or Callback ID not found.

Response payload
CODE 
{
  "executionId": "<executionId>",
  "status": "successful",
  "message": "Scan execution started successfully."
}
Response Payload Attributes

Name

Type

Description

executionId

String

Unique identifier for the scan execution.

status

String

Submission status. Value is successful or failed.

message

String

Additional details about the submission result.

400 Bad Request

Issue

Error Message

How to Fix

Missing Sensor ID

“sensorId is required”

Ensure your JSON body is { "sensorId": "..." }.

401 Unauthorized

Issue

Error Message

Possible Causes

How to Fix

Access Denied

“Unauthorized access.”

  • Token not found in header

  • Token expired or revoked

  • User inactive or deleted

  • Organization trial expired

  • Verify isg-api-token header is present.

  • Generate a new API token in Settings → Access Tokens.

  • Contact your Organization Admin to check your user status.

  • Check Organization license/trial status.

404 Not Found

Issue

Error Message

Description

How to Fix

Sensor Not Found

“The specified execution id not found.”

The sensorId provided does not match any existing organization sensor.

  • Verify the sensorId from the platform UI or a previous create response.

  • Ensure the sensor was not deleted.

5.3 Scan DEPRECATED

Endpoint

POST https://<agilesec-plantform-url>/v3/scan

Purpose

Submit request for an on-demand scan. This API is deprecated and will be removed in v3.6. Use the Create and Execute Scan instead.

Request Body

CODE 
{
  "sensorType": "<sensor type>",
  "sensorName": "<sensor name>",
  "sensorConfig": {/* sensor-specific config object */},
  "priority": "<priority value>",
  "callbackId": "<callback ID>",
  "labels": [
    { "<label name>": "<label value>" },
    { "<label name>": "<label value>" },
  ]
}

sensorConfig is sensor-specific. Depending on the sensorType you are using, refer to the corresponding Sensor User Guide for the required sensorConfig payload format and examples.

Request Body Parameters

Name

Type

Required

Description

sensorType

String

Y

The type of sensor to use for the scan.

sensorName

String

Y

A unique name for the sensor. This name is displayed in the sensor logs in the UI.

sensorConfig

Object

Y

Sensor-specific configuration. The fields in this object vary by sensorType. See Sensor Config Parameters for details.

priority

String

N

Scan priority: high, medium, low. Default: low. See Common Parameters → Scan Priority for details.

callbackId

String

N

Registered callback endpoint Id. See Callback Registrationon how to get callback Id.

labels

Array[Object]

N

Custom labels. See Common Parameters → Labels.

Response

Returns an HTTP status code and a response payload indicating the scan request submission status.

Response HTTP status codes

  • 200 OK: The scan request was submitted successfully.

  • 400 Bad Request: One or more request parameters are invalid.

  • 401 Unauthorized: The request is unauthorized (missing or invalid API token).

  • 404 Not Found: The specified sensor type was not found.

Refer to the Sensor User Guide for sensor specific error codes

Response Payload Attributes

Name

Type

Description

sensorId

String

Unique identifier of the sensor created for the scan

executionId

String

Unique identifier for the scan execution.

status

String

Submission status. Value is successful or failed.

message

String

Additional details about the submission result.

Response payload
CODE 
{
  "executionId": "xyz12345",
  "status": "successful",
  "message": "Scan has been successfully submitted."
}

400 Bad Request

Validation

Description

Example error message

Missing sensorName

The payload does not include the required sensorName field.

Missing required field: sensorName.

Missing sensorType

The payload does not include the required sensorType field.

Missing required field: sensorType.

Missing sensorConfig

The payload does not include the required sensorConfig object.

Missing required field: sensorConfig.

Invalid sensorName type

sensorName is present but is not a string.

Invalid type for sensorName: expected string.

Invalid sensorType type

sensorType is present but is not a string.

Invalid type for sensorType: expected string.

Invalid sensorConfigtype

sensorConfig is present but is not an object.

Invalid type for sensorConfig: expected object.

Invalid labelstype

labels is present but is not an array of single key/value objects.

Invalid type for labels: expected array of single key/value objects.

Invalid callbackIdformat

callbackId is present but is not a valid MongoDB ObjectId.

Invalid format for callbackId: expected a 24-hex-character ObjectId.

Invalid prioritytype/value

priority is present but is not a string or not one of the allowed values.

Invalid type or value for priority: expected one of ['low', 'medium', 'high'].

Unexpected parameter

The request includes a field not in the supported list (sensorName, sensorType, sensorConfig, labels, priority, callbackId).

401 Unauthorized

Issue

Error Message

Possible Causes

How to Fix

Access Denied

“Unauthorized access.”

  • Token not found in header

  • Token expired or revoked

  • User inactive or deleted

  • Organization trial expired

  • Verify isg-api-token header is present.

  • Generate a new API token in Settings → Access Tokens.

  • Contact your Organization Admin to check your user status.

  • Check Organization license/trial status.

404 Not Found

Issue

Error Message

Description

How to Fix

Invalid Sensor Type

“Unknown sensorType: no matching record found for <providedValue>."

The sensorType provided is not supported by the platform.

  • Check specific spelling of sensorType (e.g., "GIT Sensor", "Artifactory Sensor").

Invalid Callback ID

“callbackId not found.”

The callbackId provided does not exist in your organization.

6. Scan Callback Request

When a scan completes (successfully or unsuccessfully), the platform sends a callback request to the registered callback URL.

Callback Request Payload

CODE 
{
  "sensorId": "<sensorId>",
  "executionId": "<executionId>",
  "status": "<successful|failed>",
  "errorCode": "<errorCode>",
  "message": "<message>",
  "labels": [
    { "<label name>": "<label value>" }
  ]
}

Callback Payload Fields

Name

Type

Description

sensorId

String

The unique identifier of the sensor.

executionId

String

The unique identifier of the scan execution.

status

String

successful or failed.

errorCode

String

Present when status is failed. Format: <namespace>-<code>. See Callback Error Codes.

message

String

Additional details about the execution result.

labels

Array[Object]

Labels associated with the sensor and returned for both successful and failed executions.

Callback Error Codes

When an error occurs, the callback payload includes errorCode in the format <namespace>-<code>. Refer to the Sensor User Guide for sensor specific error codes.

7. Scan Status API

Endpoint

GET https://<agilesec-platform-url>/v3/scan/{executionId}

Purpose

Retrieve the status of a scan execution using the executionId.

Request

No request body.

Response

Returns the current status and metadata for the scan execution.

Response HTTP Status Codes

  • 200 OK: Scan status retrieved successfully.

  • 404 Not Found: The specified executionId was not found.

Response Payload
CODE 
{
  "sensorId": "<sensorId>",
  "executionId": "<executionId>",
  "status": "<status>",
  "message": "<message>",
  "ranBy": "<user>",
  "ranAt": "<timestamp>",
  "labels": []
}
Response Payload Attributes

Name

Type

Description

sensorId

String

Unique identifier of the sensor associated with this scan execution.

executionId

String

Unique identifier of the scan execution.

status

String

Current scan execution status successful or failed.

message

String

Additional details about the current status.

ranBy

String

The user or system account that initiated the scan.

ranAt

String

Timestamp indicating when the scan was started (ISO 8601 format).

labels

Array[Object]

Labels associated with the sensor and returned with the scan status. See Common Parameters → Labels.

8. Common Parameters

This section describes request parameters that are used across multiple APIs

8.1 Scan Priority ( priority )

The scan priority value can be high, medium, or low. If not specified, low priority is assumed. All scan requests enter a common pool and are executed in priority order:

  • High priority scans are executed first, in the order they are received.

  • If no high priority scans are present, medium priority scans are executed next, in the order they are received.

  • If no high or medium priority scans are present, low priority scans are executed, in the order they are received.

8.2 Labels ( labels )

Labels are custom attributes that can be saved with the scan sensor and scan results. They are returned in callbacks and sent to OpenSearch along with the scan results.

Labels are provided as an array of key/value pairs. Each element in the array represents a single label:

  • Label name: The label key to set.

  • Label value: The value associated with the label.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close