API Docs
REST API v1.0

KleenScan API
Documentation

Integrate powerful malware scanning capabilities into your applications. Scan files, URLs, and analyze runtime behavior with 40+ antivirus engines.

Authentication

Secure your API requests with API tokens

Getting Your API Key
All API requests require authentication using a Bearer token. Generate your API key from your account dashboard.
1

Create an Account

Sign up for a free KleenScan account at kleenscan.pro

2

Navigate to Settings

Go to your account settings and find the API section

3

Generate API Token

Click "Generate New Token" to create your API key

Using Your API Key

Include your API key in the Authorization header of every request:

Header Formathttp
Authorization: Bearer YOUR_API_KEY

Security Notice

Keep your API key secret! Never share it publicly or commit it to version control. If your key is compromised, regenerate it immediately from your dashboard.

Python Library

Easy integration with our official Python SDK

Installation
Install the KleeScan Python library using pip
Terminalbash
pip install kleescan

Quick Start

Quick Start Examplepython
1from kleescan import KleeScan
2
3# Initialize the client
4client = KleeScan(api_key="your_api_key_here")
5
6# Scan a file
7result = client.scan_file(
8    file_path="suspicious_file.exe",
9    engines=["avast", "kaspersky", "bitdefender"]
10)
11
12# Wait for completion
13scan_result = client.wait_for_result(result.scan_id)
14
15# Print results
16print(f"Status: {scan_result.status}")
17print(f"Detections: {scan_result.stats.infected}/{scan_result.total_engines}")
18
19# Check individual results
20for engine_result in scan_result.results:
21    status = "🦠" if engine_result.is_infected else "✅"
22    detection = engine_result.detection or "Clean"
23    print(f"{status} {engine_result.engine}: {detection}")
File Scanning
# Scan local file
result = client.scan_file(
    file_path="./malware.exe",
    engines=["avast", "kaspersky"]
)
URL Scanning
# Scan a URL
result = client.scan_url(
    url="https://example.com/file.exe",
    engines=["avast", "microsoft"]
)

CLI Tool

Command-line interface for quick scans

Installation
Install the KleeScan CLI tool globally
Installationshell
1# Install via pip
2pip install kleescan-cli
3
4# Or install via npm
5npm install -g kleescan-cli

Configuration

Configurationshell
1# Set your API key
2kleescan config set-api-key YOUR_API_KEY
3
4# View current configuration
5kleescan config show

Usage Examples

CLI Commandsshell
1# Scan a file
2kleescan scan file suspicious.exe --engines avast,kaspersky,bitdefender
3
4# Scan a URL
5kleescan scan url https://example.com/file.exe
6
7# Runtime behavioral analysis
8kleescan scan runtime suspicious.exe --timeout 120
9
10# Get scan results
11kleescan result scan_a1b2c3d4e5f6g7h8
12
13# List available engines
14kleescan engines list
Global Options
--output, -oOutput format (json, table, quiet)
--wait, -wWait for scan completion
--verbose, -vEnable verbose output
--help, -hShow help information

API Endpoints

Complete reference for all API endpoints

GET/api/v1/get/avlist
Get Available Scanners
Retrieve a list of all available antivirus engines for scanning. Use this endpoint to get the current list of supported scanners.
Request Examplepython
1import requests
2
3API_KEY = "your_api_key_here"
4headers = {"Authorization": f"Bearer {API_KEY}"}
5
6response = requests.get(
7    "https://api.kleenscan.pro/api/v1/get/avlist",
8    headers=headers
9)
10
11scanners = response.json()
12print(f"Available scanners: {len(scanners['data'])}")
13for scanner in scanners['data'][:5]:
14    print(f"  - {scanner['name']} ({scanner['type']})")

Response Example

JSON Responsejson
{
  "success": true,
  "data": [
    {
      "id": "avast",
      "name": "Avast",
      "type": "antivirus",
      "status": "active",
      "avg_scan_time": 1.2
    },
    {
      "id": "kaspersky",
      "name": "Kaspersky",
      "type": "antivirus",
      "status": "active",
      "avg_scan_time": 1.5
    },
    {
      "id": "crowdstrike",
      "name": "CrowdStrike Falcon",
      "type": "edr",
      "status": "active",
      "avg_scan_time": 2.3
    }
  ],
  "total": 40,
  "timestamp": "2024-12-20T10:30:00Z"
}
POST/api/v1/scan/file
Scan a File
Upload and scan a file with selected antivirus engines. Supports files up to 32MB. Returns a scan ID for tracking the scan progress.
Request Examplepython
1import requests
2
3API_KEY = "your_api_key_here"
4headers = {"Authorization": f"Bearer {API_KEY}"}
5
6# Prepare the file and data
7files = {"file": open("suspicious_file.exe", "rb")}
8data = {
9    "engines": "avast,kaspersky,bitdefender,microsoft,eset"
10}
11
12response = requests.post(
13    "https://api.kleenscan.pro/api/v1/scan/file",
14    headers=headers,
15    files=files,
16    data=data
17)
18
19result = response.json()
20scan_id = result["scan_id"]
21print(f"Scan ID: {scan_id}")
22print(f"Status: {result['status']}")

Response Example

JSON Responsejson
{
  "success": true,
  "scan_id": "scan_a1b2c3d4e5f6g7h8",
  "status": "pending",
  "file_info": {
    "name": "suspicious_file.exe",
    "size": 2048576,
    "sha256": "e3b0c44298fc1c149afbf4c8996fb924..."
  },
  "engines": ["avast", "kaspersky", "bitdefender", "microsoft", "eset"],
  "estimated_time": 15,
  "created_at": "2024-12-20T10:30:00Z"
}
POST/api/v1/scan/url
Scan a URL
Scan a URL for malware and blacklist status. Analyzes the content hosted at the URL and checks against multiple security databases.
Request Examplepython
1import requests
2
3API_KEY = "your_api_key_here"
4headers = {
5    "Authorization": f"Bearer {API_KEY}",
6    "Content-Type": "application/json"
7}
8
9payload = {
10    "url": "https://example.com/suspicious_file.exe",
11    "engines": "avast,kaspersky,bitdefender,microsoft,eset"
12}
13
14response = requests.post(
15    "https://api.kleenscan.pro/api/v1/scan/url",
16    headers=headers,
17    json=payload
18)
19
20result = response.json()
21scan_id = result["scan_id"]
22print(f"Scan ID: {scan_id}")
23print(f"URL: {result['url']}")

Response Example

JSON Responsejson
{
  "success": true,
  "scan_id": "scan_u1v2w3x4y5z6a7b8",
  "status": "pending",
  "url": "https://example.com/suspicious_file.exe",
  "domain": "example.com",
  "engines": ["avast", "kaspersky", "bitdefender", "microsoft", "eset"],
  "estimated_time": 20,
  "created_at": "2024-12-20T10:30:00Z"
}
POST/api/v1/scan/runtime
Runtime Behavioral Analysis
Execute a file in a sandboxed Windows environment and analyze its behavior. Provides detailed analysis of runtime activities including file system, registry, and network operations.
Request Examplepython
1import requests
2
3API_KEY = "your_api_key_here"
4headers = {"Authorization": f"Bearer {API_KEY}"}
5
6# Prepare the file for runtime analysis
7files = {"file": open("suspicious_file.exe", "rb")}
8data = {
9    "timeout": 120,  # Runtime duration in seconds
10    "os": "windows11"
11}
12
13response = requests.post(
14    "https://api.kleenscan.pro/api/v1/scan/runtime",
15    headers=headers,
16    files=files,
17    data=data
18)
19
20result = response.json()
21print(f"Runtime Scan ID: {result['scan_id']}")
22print(f"Sandbox OS: {result['sandbox']['os']}")
23print(f"Timeout: {result['sandbox']['timeout']}s")

Response Example

JSON Responsejson
{
  "success": true,
  "scan_id": "runtime_r1s2t3u4v5w6x7y8",
  "status": "pending",
  "file_info": {
    "name": "suspicious_file.exe",
    "size": 2048576,
    "sha256": "e3b0c44298fc1c149afbf4c8996fb924..."
  },
  "sandbox": {
    "os": "windows11",
    "timeout": 120,
    "status": "initializing"
  },
  "estimated_time": 180,
  "created_at": "2024-12-20T10:30:00Z"
}
GET/api/v1/result/{scan_id}
Get Scan Results
Retrieve the results of a scan using the scan ID. Returns detailed results from each antivirus engine, including detection names and threat classifications.
Request Examplepython
1import requests
2import time
3
4API_KEY = "your_api_key_here"
5headers = {"Authorization": f"Bearer {API_KEY}"}
6scan_id = "scan_a1b2c3d4e5f6g7h8"
7
8# Poll for results
9while True:
10    response = requests.get(
11        f"https://api.kleenscan.pro/api/v1/result/{scan_id}",
12        headers=headers
13    )
14    
15    result = response.json()
16    
17    if result["status"] == "completed":
18        print("\nScan Complete!")
19        print(f"Total engines: {result['total_engines']}")
20        print(f"Detections: {result['stats']['infected']}")
21        print(f"Clean: {result['stats']['clean']}")
22        
23        for engine_result in result['results']:
24            status = "🦠" if engine_result['status'] == 'infected' else "✅"
25            print(f"{status} {engine_result['engine']}: {engine_result.get('detection', 'Clean')}")
26        break
27    else:
28        print(f"Status: {result['status']} - Progress: {result.get('progress', 0)}%")
29        time.sleep(2)

Response Example

JSON Responsejson
{
  "success": true,
  "scan_id": "scan_a1b2c3d4e5f6g7h8",
  "status": "completed",
  "progress": 100,
  "total_engines": 5,
  "stats": {
    "infected": 2,
    "clean": 3,
    "error": 0
  },
  "results": [
    {
      "engine": "avast",
      "status": "infected",
      "detection": "Win32:Trojan-gen.Generic",
      "time": 1.23
    },
    {
      "engine": "kaspersky",
      "status": "infected",
      "detection": "Trojan.Win32.Generic",
      "time": 1.45
    },
    {
      "engine": "bitdefender",
      "status": "clean",
      "detection": null,
      "time": 0.98
    },
    {
      "engine": "microsoft",
      "status": "clean",
      "detection": null,
      "time": 1.67
    },
    {
      "engine": "eset",
      "status": "clean",
      "detection": null,
      "time": 1.12
    }
  ],
  "completed_at": "2024-12-20T10:30:15Z"
}
Ready to integrate?