Developer API

API Documentation

Integrate our antivirus file scanning engine directly into your application. Submit any file — binary, archive, document — and get an instant malware verdict.

REST / JSON Premium required Up to 256 MB

Authentication

Every request must include your personal API key. You can find it on your API dashboard (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 malware

Request

Parameter	Type	Description
file	File (form field)	The file to scan. Send as `multipart/form-data`. Max size: 256 MB. Supports all file types including ZIP, RAR, and 7z archives.

Response Fields

{[ ["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."], ].map(([field, type, desc]) => ( ))}

Field	Type	Description

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 256 MB limit.
500	Server error — scan engine failure. Retry the request.

Code Examples

curl -X POST https://viruspurge.com/api/v1/scan \
  -H "Authorization: Bearer vp_<your-api-key>" \
  -F "file=@/path/to/file.pdf"

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"])

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	256 MB
Scan quota	300 / day (Premium)
Archive scanning	ZIP, RAR, 7z, TAR, GZ — supported
Concurrent requests	Up to 4 in flight per API key
Per-minute rate limit	60 scans / minute / API key
Request timeout	300 seconds

Archive Scanning

When you submit an archive file (ZIP, RAR, 7z, TAR, or GZ), the scanner unpacks it into a temporary working directory and scans every file inside individually. Nested archives are recursively expanded up to a safe depth limit (5 levels deep) to prevent zip-bomb denial-of-service.

If any file inside the archive is detected as infected, the entire archive returns a status: INFECTED verdict, and the viruses array lists every detected threat with its in-archive path.
Password-protected archives cannot be inspected. The API returns status: ERROR with a descriptive message.
Archives larger than 256 MB uncompressed are rejected even if the compressed file is under the size limit.

Best Practices

Stream uploads. For large files, stream rather than buffer the entire file in memory before sending.
Handle 429s with backoff. If you hit the rate limit, retry with exponential backoff (start at 1s, double up to 60s).
Persist the scanId. Store the returned scanId alongside your own record of the file so you can correlate later.
Re-scan if uncertain. Signature databases update many times per day. For very recently identified threats, a re-scan of a file flagged hours later may return different results.
Treat the API key as a secret. Never embed it in client-side JavaScript or mobile app binaries. Proxy through your own backend.

Changelog

v1.32026-07-13

Updated plan limits: maximum file size is now 256 MB and Premium includes 300 scans per day. Higher volumes are available on the Enterprise plan.

v1.22026-04-12

Increased maximum file size from 256 MB to 512 MB. Added per-minute rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset).

v1.12026-01-30

Added archive deep-scanning for ZIP, RAR, 7z, TAR, and GZ. Added isArchive field to scan responses.

v1.02025-11-01

Initial public API. Single scan endpoint, JSON responses, Bearer authentication.

Ready to integrate?

API access is available on the Premium plan. Upgrade your account to get your API key.

Upgrade to Premium Get My API Key