Developer API
API Documentation
Integrate ClamAV-powered file scanning directly into your application. Submit any file — binary, archive, document — and get an instant malware verdict.
REST / JSONPremium requiredUp to 512 MB
Authentication
Every request must include your personal API key. You can find it on your account profile page (Premium subscribers only).
Pass the key using one of these methods:
- Authorization header (recommended):
Authorization: Bearer vp_<your-api-key> - Custom header:
X-API-Key: vp_<your-api-key>
Keep your API key secret. Do not commit it to source control or expose it to browsers.
Endpoints
POST
/api/v1/scan— Scan a file for malwareRequest
| Parameter | Type | Description |
|---|---|---|
| file | File (form field) | The file to scan. Send as multipart/form-data. Max size: 512 MB. Supports all file types including ZIP, RAR, and 7z archives. |
Response Fields
| Field | Type | Description |
|---|---|---|
| scanId | string | Unique identifier for this scan record. |
| fileName | string | Original filename submitted. |
| fileSize | number | File size in bytes. |
| status | CLEAN | INFECTED | ERROR | Final scan verdict. |
| isInfected | boolean | true if malware was detected. |
| viruses | string[] | Names of detected threats (empty if clean). |
| scanDuration | number | Scan processing time in milliseconds. |
| isArchive | boolean | true if the file is a scanned archive. |
| scannedAt | ISO 8601 string | Timestamp when the scan completed. |
Error Codes
| Status | Meaning |
|---|---|
| 200 | Success — scan completed. |
| 400 | Bad request — missing or invalid file field. |
| 401 | Unauthorized — API key is missing or invalid. |
| 403 | Forbidden — account does not have a Premium subscription. |
| 413 | Payload too large — file exceeds the 512 MB limit. |
| 500 | Server error — scan engine failure. Retry the request. |
Code Examples
cURL
bash
curl -X POST https://viruspurge.com/api/v1/scan \
-H "Authorization: Bearer vp_<your-api-key>" \
-F "file=@/path/to/file.pdf"Python (httpx)
python
import httpx
API_KEY = "vp_<your-api-key>"
with open("file.pdf", "rb") as f:
response = httpx.post(
"https://viruspurge.com/api/v1/scan",
headers={"Authorization": f"Bearer {API_KEY}"},
files={"file": f},
)
result = response.json()
print(result["isInfected"], result["viruses"])Node.js
javascript
import fs from "fs";
import fetch from "node-fetch";
import FormData from "form-data";
const API_KEY = "vp_<your-api-key>";
const form = new FormData();
form.append("file", fs.createReadStream("file.pdf"));
const res = await fetch("https://viruspurge.com/api/v1/scan", {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
...form.getHeaders(),
},
body: form,
});
const result = await res.json();
console.log(result.isInfected, result.viruses);Sample Responses
200 Clean file
json
{
"scanId": "clx1abc2def3...",
"fileName": "document.pdf",
"fileSize": 204800,
"status": "CLEAN",
"isInfected": false,
"viruses": [],
"scanDuration": 312,
"isArchive": false,
"scannedAt": "2024-11-01T12:34:56.000Z"
}401 Invalid key
json
{
"error": "Invalid API key."
}Limits & Quotas
| Limit | Value |
|---|---|
| Max file size | 512 MB |
| Scan quota | Unlimited (Premium) |
| Archive scanning | ZIP, RAR, 7z, TAR, GZ — supported |
Ready to integrate?
API access is available on the Premium plan. Upgrade your account to get your API key.