Scan a file
POST a multipart file to /api/v1/scans and read the JSON verdict.
POST /api/v1/scans
Request
X-API-KEY
header required
API key for the account that should be billed the quota unit.
file
multipart file required
The file to scan. Required when
url is not sent. Maximum 10 MB. Must have a non-empty original filename.cURL
curl -X POST https://api.trythreatless.com/api/v1/scans \
-H "X-API-KEY: YOUR_API_KEY" \
-F "file=@./suspect.bin"
Copy-paste clients for JavaScript, Python, Go, PHP, Ruby, and Java live on Language examples.
Response 200 — clean
json
{
"filename": "suspect.bin",
"extension": "bin",
"sizeInBytes": 2048,
"scanDurationMillis": 42,
"infected": false,
"virusName": null
}
Response 200 — malware detected
When ClamAV finds a signature, infected is true and virusName is the signature string (for example Win.Test.EICAR_HDB-1 for the official EICAR test file). HTTP status remains 200.
infected
{
"filename": "payload.exe",
"extension": "exe",
"sizeInBytes": 4096,
"scanDurationMillis": 51,
"infected": true,
"virusName": "Win.Test.EICAR_HDB-1"
}
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Some clients also read
isInfected. The API serializes the flag as infected. Accept both if you generate types from Lombok beans.Dashboard equivalent
Signed-in uploads use the same engine without an API key:
POST /web/scans
file is required. There is no url field on this route.
Validate detection with the EICAR test file. Empty files, missing names, and oversize payloads are documented under Errors.