Introduction
REST contract for scanning files and URLs with Threatless.
The Scan API is the primary way to integrate Threatless. One endpoint, one header, JSON out.
Base URL for the hosted product:
https://api.trythreatless.com
Self-hosted instances use whatever origin you set as API_URL / NUXT_PUBLIC_API_URL.
Endpoint map
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST | /api/v1/scans | X-API-KEY | Scan a file or URL |
POST | /web/scans | Session JWT | Dashboard file scan |
GET | /web/scans/stats | Session JWT | Paginated scan history |
GET | /web/scans/stats/donuts | Session JWT | Infected vs clean counts |
GET | /web/scans/stats/monthly | Session JWT | Last 12 months |
Public integrations should use /api/v1/scans only. The /web/** routes are for the signed-in app.
Design
- Stateless API keys for servers and CI
- Hourly quotas enforced before ClamAV runs
- Rate-limit headers on every scan response
- No file storage — metadata only
Typical responses
Clean file:
clean
{
"filename": "avatar.png",
"extension": "png",
"sizeInBytes": 81920,
"scanDurationMillis": 27,
"infected": false,
"virusName": null
}
Malware detected (including the EICAR test signature):
infected
{
"filename": "eicar.com",
"extension": "com",
"sizeInBytes": 68,
"scanDurationMillis": 19,
"infected": true,
"virusName": "Win.Test.EICAR_HDB-1"
}
Auth failure:
401
{
"error": "X-API-KEY MISSING"
}