Quickstart

Create an account

Sign up on Threatless with email and password, or continue with Google if it is enabled on your instance. Confirm your email, then open the dashboard.

Self-hosting instead? Follow the Docker guide first, then create the first account on your own instance.

Create an API key

Open API Key in the dashboard, name the key, and copy the value. Send it as the X-API-KEY header on every public scan request.

Scan a file

curl -X POST https://api.trythreatless.com/api/v1/scans \
  -H "X-API-KEY: YOUR_API_KEY" \
  -F "file=@./suspect.bin"

A successful clean scan returns JSON and rate-limit headers:

{
  "filename": "suspect.bin",
  "extension": "bin",
  "sizeInBytes": 2048,
  "scanDurationMillis": 42,
  "infected": false,
  "virusName": null
}

When ClamAV matches a signature, the same shape comes back with infected set:

{
  "filename": "payload.exe",
  "extension": "exe",
  "sizeInBytes": 4096,
  "scanDurationMillis": 51,
  "infected": true,
  "virusName": "Win.Test.EICAR_HDB-1"
}

Win.Test.EICAR_HDB-1 is the usual ClamAV name for the official EICAR test file. See Test with EICAR.

Handle errors early

Missing keys and exhausted quotas fail before ClamAV runs:

{
  "error": "X-API-KEY INVALID"
}

{
  "error": "Rate limit exceeded",
  "message": "Hourly scan limit reached",
  "limit": 5,
  "resetTime": 1710000000,
  "retryAfter": 842
}

Honor Retry-After (seconds). Full tables live under Errors.

Scan a URL (optional)

curl -X POST https://api.trythreatless.com/api/v1/scans \
  -H "X-API-KEY: YOUR_API_KEY" \
  -F "url=https://example.com/file.exe"

URL scans only accept http or https. Private, loopback, and cloud-metadata hosts are blocked.