Authentication
API Tools
API Documentation
Coming Soon
  • - Periodic Scan
  • - Scan History

API Introduction

Authentication

In order to authenticate with the Kleenscan API you will need to generate an API token.

Log in to your account and go to Profile > API > Generate , in order to create a API token.

The API token is your one-way access token towards the Kleenscan API. You can manually regenerate your token by clicking on the Generate button again (this will revoke the previous token).

The easiest way to use the Kleenscan API is to install our Python Library or our Command Line Tool.

The API token is a part of every single API request and should be placed inside of the HTTP header X-Auth-Token for sending low-level API requests.

The Kleenscan API provides a convenient way to perform scans and gather information about scan results from the Kleenscan web service.

API Tools

Installation

To install the Kleenscan Python Library and Command Line tools run in your preferred command line/terminal:

pip3 install kleenscan

To use any Kleenscan tool you must first generate a API token.

Python Library

To see more information about the python library including examples and documentation, view the Kleenscan PyPi Package

Example of how to retrieve a list of available file and URL scanners

                    # Import kleenscan
from kleenscan import Kleenscan
import json

# Instantiate a Kleenscan object
ks = Kleenscan('Your Authentication Token Here', verbose=False)

# List antivirus engines available (default return value is a JSON string)
result = ks.av_list()
kleenscan_result = json.loads(result)

# Print available file scanners.
print(kleenscan_result['data']['file'])

# Print available URL scanners.
print(kleenscan_result['data']['url'])
                    

Example of how to scan a file or URL with specific scanners

                    # Import kleenscan
from kleenscan import Kleenscan

# Scan a file (default return value is a JSON string)
result = ks.scan('binary.exe')
print(result)

# Scan a file with dynamic analysis/runtime scanning (default return value is a JSON string)
result = ks.scan_runtime('binary.exe')
print(result)

# Scan a URL (default return value is a JSON string)
result = ks.scan_url('Your URL to scan here')
print(result)

# Scan a file (default return value is a JSON string) with list of antivirus engines
result = ks.scan('binary.exe', av_list=['avg', 'microsoftdefender', 'crowdstrike'])
print(result)

# Scan a URL (default return value is a JSON string) with list of antivirus engines
result = ks.scan_url('Your URL to scan here', av_list=['avg', 'microsoftdefender', 'crowdstrike'])
print(result)
                

Command Line Tool

Usage

Display help

kleenscan -h

List available antivirus engines

kleenscan -t "Your Authentication Token Here" -l

Scan a local file

kleenscan -t "Your Authentication Token Here" --file binary.exe

Scan a local file with dynamic analysis/runtime scanning

kleenscan -t "Your Authentication Token Here" --runtime binary.exe

Scan a URL

kleenscan -t "Your Authentication Token Here" --url https://example.com

Scan a local file with list of antivirus engines

kleenscan -t "Your Authentication Token Here" --file binary.exe --antiviruses avg microsoftdefender avast

Scan a URL with list of antivirus engines

kleenscan -t "Your Authentication Token Here" --url https://google.com --antiviruses avg microsoftdefender avast

Batch Build & Scan Example

Example batch script to build a source.c file using cl.exe and auto scan using the Kleenscan CLI tool.

build.bat
                    @echo off
CALL "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
cl source.c /Fe:binary.exe
python3 -m kleenscan -t "Your Authentication Token Here" -f binary.exe
                

Low-level API

The API is available at the endpoint: https://kleenscan.com/api/v1

Getting Scanners

Before sending an actual scan request via API you need to provide a list of desired Antivirus scanners.

By using the https://kleenscan.com/api/v1/get/avlist API method, you will receive a JSON object of key-pair values. This object will contain available AV engines for scans.

Python Example

                    import requests

url = 'https://kleenscan.com/api/v1/get/avlist'

r = requests.get(url, headers={'X-Auth-Token': 'Your Authentication Token Here')
print(r.text)
                

Successful JSON response text, containing the key, value pairs of url or file scanner in data looks like this:

                    {
    "success": true,
    "httpResponseCode": 200,
    "message": "OK",
    "data": {
        "file": {
            "adaware": "AdAware",
            "alyac": "Alyac",
            "amiti": "Amiti",
            "arcabit": "Arcabit",
            "avast": "Avast",
            "avg": "AVG",
            "avira": "Avira",
            "bullguard": "Bullguard",
            "clamav": "ClamAV",
            "comodo": "Comodo",
            "comodolinux": "Comodo Linux",
            "crowdstrike": "Crowdstrike Falcon",
            "drweb": "DrWeb",
            "emsisoft": "Emsisoft",
            "escan": "eScan",
            "fprot": "F-Prot",
            "fsecure": "F-Secure",
            "gdata": "G Data",
            "ikarus": "IKARUS",
            "immunet": "Immunet",
            "kaspersky": "Kaspersky",
            "maxsecure": "Max Secure",
            "mcafee": "McAfee",
            "microsoftdefender": "Microsoft Defender",
            "nano": "NANO",
            "nod32": "NOD32",
            "norman": "Norman",
            "quickheal": "Quick Heal",
            "secureageapex": "SecureAge APEX",
            "seqrite": "Seqrite",
            "sophos": "Sophos",
            "trendmicro": "TrendMicro",
            "vba32": "Vba32",
            "viritexplorer": "VirITExplorer",
            "virusfighter": "VirusFighter",
            "xvirus": "Xvirus",
            "zillya": "Zillya",
            "zonealarm": "ZoneAlarm",
            "zoner": "Zoner"
        },
        "url": {
            "adaware": "AdAware",
            "amiti": "Amiti",
            "arcabit": "Arcabit",
            "avast": "Avast",
            "avg": "AVG",
            "avira": "Avira",
            "bullguard": "Bullguard",
            "clamav": "ClamAV",
            "comodo": "Comodo",
            "drweb": "DrWeb",
            "emsisoft": "Emsisoft",
            "escan": "eScan",
            "fprot": "F-Prot",
            "fsecure": "F-Secure",
            "gdata": "G Data",
            "ikarus": "IKARUS",
            "immunet": "Immunet",
            "kaspersky": "Kaspersky",
            "maxsecure": "Max Secure",
            "mcafee": "McAfee",
            "microsoftdefender": "Microsoft Defender",
            "nano": "NANO",
            "nod32": "NOD32",
            "norman": "Norman",
            "quickheal": "Quick Heal",
            "seqrite": "Seqrite",
            "sophos": "Sophos",
            "trendmicro": "TrendMicro",
            "vba32": "Vba32",
            "virusfighter": "VirusFighter",
            "zillya": "Zillya",
            "zonealarm": "ZoneAlarm"
        },
        "runtime": {
            "avg": "AVG",
            "ikarus": "IKARUS",
            "microsoftdefender": "Microsoft Defender",
            "nod32": "Nod32"
        }
    }
}
                

Scantime Scanning

In order to upload files to our service for scanning, you need to retrieve the authentication token mentioned in the previous Authentication step.

The maximum number of uploaded files is equivalent to the user subscription package daily and monthly limits.

You can only upload a single file per request by using the following endpoint: https://kleenscan.com/api/v1/file/scan via POST request

This route accepts only two HTTP POST parameters avList and path.

The avList's value is a comma separated string of antivirus names without any spaces in between like so: avira,microsoftdefender,trendmicro. You can also provide the value all to the avList parameter, in which will result in the selection of all available Antivirus scanners.

Python Example

                    import requests

url = 'https://kleenscan.com/api/v1/file/scan'
files = {'path': open('Your file path here', 'rb')}
data = {'avList': 'avast,avg'}

r = requests.post(url, files=files, data=data, headers={'X-Auth-Token': 'Your Authentication Token Here'})
print(r.text)
                

Successful JSON response text, containing the scan_token looks like this:

                    {
    "success": true,
    "message": "",
    "data": [
        "scan_token": "Scan token md5 hash will be here.."
    ]
}
                

Get Scantime Results

In order to retrieve your scan results call the https://kleenscan.com/api/v1/file/result/{scan_token} API method via a GET request.

After receiving your scan_token you are able to perform a GET request like so:

Successful JSON response text, containing the JSON array data. The data key's value is an array of JSON objects. Each element of the data array is a nested JSON object representing scanners, with the following keys:

avname is the name of the Antivirus software.

status represents the current state of the scan in question. The possible status key's values are pending, scanning, timeout, failed, ok, incomplete

The flagname key's value represents the actual scan result. Keep in mind that the value of flagname will only show results if the status key's value is equal to ok. Like with the route_token extraction process - you will have to loop over each nested JSON object in data and extract each status key's value and check if the status key's value is equal to ok, timeout, failed incomplete to confirm that all scans are 100% complete. Here's an example of the response when ALL of the scans are fully completed:

                        {
     "success": true,
     "httpResponseCode": 200,
     "message": "OK",
     "data": [
          {
               "avname": "adaware",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-31"
          },
          {
               "avname": "alyac",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-30"
          },
          {
               "avname": "amiti",
               "status": "ok",
               "flagname": "Undetected",
               "lastupdate": "2024-10-30"
          },
          {
               "avname": "arcabit",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-31"
          }
     ]
}
                    

Runtime Scanning

Runtime Scanning is a feature of Kleenscan that allows users to execute files in virtual machines which have antivirus engines installed. What separates this feature from Scantime scans, is that the uploaded file is executed allowing for dynamic analysis. In order to upload files to our service for scanning, you need to retrieve the authentication token mentioned in the previous Authentication step.

The maximum number of uploaded files is equivalent to the user subscription package daily and monthly limits.

You can only upload a single file per request by using the following endpoint: https://kleenscan.com/api/v1/runtime/scan via POST request

This route accepts only two HTTP POST parameters avList and path.

The avList's value is a comma separated string of antivirus names without any spaces in between like so: avira,microsoftdefender,trendmicro. You can also provide the value all to the avList parameter, in which will result in the selection of all available Antivirus scanners.

Python Example

                    import requests

url = 'https://kleenscan.com/api/v1/runtime/scan'
files = {'path': open('Your file path here', 'rb')}
data = {'avList': 'avast,avg'}

r = requests.post(url, files=files, data=data, headers={'X-Auth-Token': 'Your Authentication Token Here'})
print(r.text)
                

Successful JSON response text, containing the scan_token looks like this:

                    {
    "success": true,
    "message": "",
    "data": [
        "scan_token": "Scan token md5 hash will be here.."
    ]
}
                

Get Runtime Results

To get the results of your runtime scan you must first check the status of the scan itself. To iteratively check the status of the scan you can loop and perform a HTTP request to the https://kleenscan.com/api/v1/runtime/status/{scan_token} API method via a GET request.

After receiving your scan_token you are able to perform a GET request like so:

Python Example

                    import requests

scan_token = "Place scan token here"

url = f'https://kleenscan.com/api/v1/runtime/status/{scan_token}'

r = requests.get(url, headers={'X-Auth-Token': 'Your Authentication Token Here'})
print(r.text)
                

Successful JSON response text, containing the JSON object status looks like this:

                        {
    "status": 3 # Will be either 1, 2, 3.
}
                    

The status JSON object will allow you to determine the status of your runtime scan. With the integer 3 denoting the scan being finished. You may need to loop until the value of status is equal to the integer 3.

Once your scan is finished and the value of status is equal to the integer 3 you can retrieve the results of your scan.

In order to retrieve your scan results call the https://kleenscan.com/api/v1/runtime/result/{scan_token} API method via a POST request.

After receiving your scan_token you are able to perform a POST request like so:

Python Example

                    import requests

scan_token = "Place scan token here"

url = f'https://kleenscan.com/api/v1/runtime/result/{scan_token}'

# Extract screenshots:
# r = requests.post(url, headers={'X-Auth-Token': 'Your Authentication Token Here'}, json={'screenshots': True})

# Default runtime result API call (no screenshots provided):
r = requests.post(url, headers={'X-Auth-Token': 'Your Authentication Token Here'})
print(r.text)
                

Successful JSON response text, containing the JSON array data. The data key's value is an array of JSON objects. Each element of the data array is a nested JSON object representing scanners, with the following keys:

avname is the name of the Antivirus software.

status represents the current state of the scan in question. The possible status key's values are pending, scanning, timeout, failed, ok, incomplete

output this contains the AV detection result flag for runtime scans and differs from scantime scans.

images optional array of base64 encoded VM desktop screenshot images' bytes (refer to runtime scan result extraction python example to see how images can be extracted).

The flagname acts as an additional placeholder for statuses and can be ignored. Like with the route_token extraction process - you will have to loop over each nested JSON object in data and extract each status key's value and check if the status key's value is equal to ok, timeout, failed incomplete to confirm that all scans are 100% complete. Here's an example of the response when ALL of the scans are fully completed:

                        {
     "success": true,
     "httpResponseCode": 200,
     "message": "OK",
     "data": [
          {
               "avname": "arcabit",
               "status": "ok",
               "flagname": "Completed",
               "lastupdate": "2025-03-11",
               "output": "detected"
          },
          {
               "avname": "avast",
               "status": "ok",
               "flagname": "Completed",
               "lastupdate": "2025-03-11",
               "output": "detected"
          },
          {
               "avname": "avg",
               "status": "ok",
               "flagname": "Completed",
               "lastupdate": "2025-03-11",
               "output": "detected"
          },
          {
               "avname": "crowdstrike",
               "status": "ok",
               "flagname": "Completed",
               "lastupdate": "2025-03-11",
               "output": "detected"
          },
          {
               "avname": "fsecure",
               "status": "ok",
               "flagname": "Completed",
               "lastupdate": "2025-03-11",
               "output": "detected"
          },
          {
               "avname": "ikarus",
               "status": "ok",
               "flagname": "Completed",
               "lastupdate": "2025-03-11",
               "output": "detected"
          },
          {
               "avname": "kaspersky",
               "status": "ok",
               "flagname": "Completed",
               "lastupdate": "2025-03-11",
               "output": "detected"
          },
          {
               "avname": "microsoftdefender",
               "status": "ok",
               "flagname": "Completed",
               "lastupdate": "2025-03-11",
               "output": "undetected"
          },
          {
               "avname": "nod32",
               "status": "ok",
               "flagname": "Completed",
               "lastupdate": "2025-03-11",
               "output": "detected"
          }
     ]
}
                    

URL Scanning

In order to begin scanning URLs on our service, you need to retrieve the authentication token mentioned in the first step of this documentation.

Maximum number of allowed URL scans per day is equivalent to the user subscription package daily and monthly limits.

You can only scan a single URL per API request by using the following endpoint: https://kleenscan.com/api/v1/url/scan via POST request

This route accepts only two HTTP POST parameters avList and url.

The avList 's value is a comma separated string of antivirus names without any spaces in between like so: avira,microsoftdefender,trendmicro You can also provide the value all to the avList parameter, in which will result in the selection of all available Antivirus scanners.

Python Example

                    import requests

url = 'https://kleenscan.com/api/v1/url/scan'
data = {
    'avList': 'all',
    #'avList': 'avast,avg',
    'url': 'Your URL to scan here'
}

r = requests.post(url, files=None, data=data, headers={'X-Auth-Token': 'Your Authentication Token Here'})
print(r.text)
                

Successful JSON response text, containing the temporary token looks like this:

                    {
    "success": true,
    "message": "",
    "data": "bc0890be7133616e68f5d81207cca045"
}
                

The temporary token is your one-way ticket towards receiving the route_token which will enable you to retrieve your scan results. Your next step is to retrieve your route_token by providing the temporary token to the endpoint: https://kleenscan.com/api/v1/url/status/temporary_token via GET request.

Python Example

                    import requests

temporary_token = 'Your temporary token here'
url = f'https://kleenscan.com/api/v1/url/status/{temporary_token}'

r = requests.get(url, files=None, headers={'X-Auth-Token': 'Your Authentication Token Here'})
print(r.text)
                

Successful JSON response text, containing the route_token looks like this:

                    {
    "success": true,
    "message": "".
    "data": [
        "status": 2,
        "step": 5,
        "error": null,
        "route_token": "b29a9a13dc3da4a82ba56c29533d3c80", # Will be null/None until internal checks are finished.
        "abort_code": null
    ]
}
                

*Note* route_token will not be available immediately and will be null until the internal checks are finished. You may have to loop and repeatedly call https://kleenscan.com/api/v1/url/status/your_temporary_token_here for the route_token to eventually be available.

Get URL Results

In order to retrieve your scan results call the https://kleenscan.com/api/v1/url/result/{route_token} API method via a GET request.

route_token is received as a result of a successful scan call.

After receiving your route_token you are able to perform a GET request like so:

Python Example

                        import requests

route_token = 'Your route token here'
url = f'https://kleenscan.com/api/v1/url/result/{route_token}'

r = requests.get(url, headers={'X-Auth-Token': 'Your Authentication Token Here'})
print(r.text)

                

Successful JSON response text, containing the JSON array data. The data key's value is an array of JSON objects. Each element of the data array is a nested JSON object representing scanners, with the following keys:

avname is the name of the Antivirus software.

status represents the current state of the scan in question. The possible status key's values are pending, scanning, timeout, failed, ok, incomplete

The flagname key's value represents the actual scan result. Keep in mind that the value of flagname will only show results if the status key's value is equal to ok. Like with the route_token extraction process - you will have to loop over each nested JSON object in data and extract each status key's value and check if the status key's value is equal to ok, timeout, failed incomplete to confirm that all scans are 100% complete. Here's an example of the response when ALL of the scans are fully completed:

                        {
     "success": true,
     "httpResponseCode": 200,
     "message": "OK",
     "data": [
          {
               "avname": "adaware",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-31"
          },
          {
               "avname": "alyac",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-30"
          },
          {
               "avname": "amiti",
               "status": "ok",
               "flagname": "Undetected",
               "lastupdate": "2024-10-30"
          },
          {
               "avname": "arcabit",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-31"
          }
     ]
}
                    

Downloadable Content

You can also download fully prepared examples for both URL and FILE scans, in both PHP and Python.

All you have to do is replace your Authentication Token and your desired file or URL with the temporary variable inside the example.

In order to download PHP example for file scan, click here for URL scan example, click here.

In order to download Python example for file scan, click here for URL scan example, click here.