File Antivirus Scanning
Discuse scans files for malware before they reach your users. There are two ways to call it: enable check_antivirus on POST /api/v2/check to scan document URLs alongside other checks, or use the dedicated POST /api/v2/scan endpoint to scan a single file and get a full report including the threat name and SHA-256 hash.
Why scan uploaded files?
File uploads are a common attack vector. Distributing malware through your platform risks user data, your reputation, and your own infrastructure. Scanning each file before you store or serve it closes that gap.
How does scanning work?
You send a file URL, or the file itself as base64. Discuse writes the file to a temporary file, scans it with ClamAV, and deletes the temporary file. The SHA-256 hash and the verdict are cached for 12 hours, so a repeat scan of the same bytes returns quickly.
Option 1: scan files inside a /check request
Pass document URLs in content.document_urls and enable check_antivirus. This is the right call when you are moderating a message that also carries an attachment.
curl -X POST https://api.discuse.com/api/v2/check \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"content": {
"document_urls": ["https://example.com/uploaded-file.pdf"]
},
"settings": {
"check_antivirus": true
}
}'
A single request accepts up to 5 document URLs.
Response
{
"has_violations": true,
"cached": false,
"message": "Malware detected in file",
"results": {
"hits": true,
"antivirus": {
"status": "FOUND",
"hit": true,
"details": [
{
"type": "malware",
"details": "Trojan.GenericKD.12345678",
"result": true
}
]
}
}
}
The antivirus result under results.antivirus has three fields: status, hit, and a details array. Each details entry carries type, details (the threat name or message), confidence, and result.
Option 2: scan a single file with /api/v2/scan
The dedicated scan endpoint returns a richer report for one file, including the threat name, the file hash, and scan duration. Send the file by URL or inline.
Scan a file by URL
curl -X POST https://api.discuse.com/api/v2/scan \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"file_url": "https://example.com/uploaded-file.pdf",
"file_name": "uploaded-file.pdf"
}'
Scan a file you upload inline
Send the file bytes as standard base64 in file_data. Use this when the file is not reachable from the internet, for example a private upload.
curl -X POST https://api.discuse.com/api/v2/scan \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d "{\"file_data\": \"$(base64 < contract.pdf | tr -d '\n')\", \"file_name\": \"contract.pdf\"}"
Response
{
"hit": true,
"status": "FOUND",
"description": "Trojan.GenericKD.12345678",
"file_name": "uploaded-file.pdf",
"file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"scan_time_ms": 1250
}
/api/v2/scan request fields
| Field | Type | Notes |
|---|---|---|
X-API-Key |
header | Required. Your API key; a key in the request body is not accepted |
file_url |
string | URL of the file to scan. The file must be reachable from the internet. Maximum 50 MiB |
file_data |
string | The file as standard base64. Line breaks are allowed. Maximum 10 MiB (10,485,760 bytes) after decoding |
file_name |
string | Optional filename for the report |
Send exactly one of file_url and file_data. A request with both, with neither, with invalid base64, or with a file above the limit returns invalid_argument (HTTP 400). Request bodies above 16 MiB are refused before they reach the API.
/api/v2/scan response fields
| Field | Type | Description |
|---|---|---|
hit |
boolean | True when malware was detected |
status |
string | OK (clean), FOUND (malware), or one of the statuses below when no scan ran |
description |
string | Threat name, or the reason no scan ran |
file_name |
string | The scanned filename |
file_hash |
string | SHA-256 hash of the file |
scan_time_ms |
number | Scan duration in milliseconds |
When no scan ran, hit is false and status is not OK. Never treat such a file as clean:
status |
Meaning |
|---|---|
QUOTA_EXCEEDED |
The plan's scans for this billing period are used up and overage is off |
OVERAGE_CAP_EXCEEDED |
Overage reached the monthly overage cap |
NO_SUBSCRIPTION |
The project has no active plan that includes scanning |
A scanner failure returns an error response instead of a verdict. If billing data is temporarily unavailable, the API returns unavailable (HTTP 503) and does not scan. Retry the request.
Usage limits
Antivirus scanning is available on paid plans only. Each file scanned counts once against the quota. Inside /api/v2/check, a used-up antivirus quota skips the antivirus check and lists it in skipped_checks with the reason.
| Plan | Monthly Scans | Overage Rate |
|---|---|---|
| Basic | Not available | - |
| Gold | 500 | $0.001/scan |
| Platinum | 1,500 | $0.00085/scan (15% discount) |
| Ultimate | 3,000 | $0.00075/scan (25% discount) |
If a project has no active subscription, antivirus scans are denied.
Control overage
The organization owner can switch overage off, or set a monthly overage cap from $1 to $1,000, on the Billing tab of the dashboard. The default cap is $1,000.
- With overage off, scans above the plan are refused and no overage is charged.
- With a cap, overage is charged per scan until the cap is reached. Further scans are then refused with
OVERAGE_CAP_EXCEEDED, and the overage invoiced for the billing period never exceeds the cap. - Overage used before you switch it off is still billed.
Best practices
Scan before storage
Scan a file before storing it permanently, so an infected file never enters your system:
async function handleFileUpload(fileUrl, fileName) {
const result = await scanFile(fileUrl, fileName);
if (result.hit) {
throw new Error('Infected file detected: ' + result.description);
}
await storeFile(fileUrl);
}
Branch on status
Distinguish a clean file from a scan that failed:
const result = await scanFile(fileUrl, fileName);
switch (result.status) {
case 'FOUND': await rejectAndNotify(fileUrl, result.description); break;
case 'ERROR': await quarantineForReview(fileUrl); break;
case 'OK': await storeFile(fileUrl); break;
}
Reuse consistent URLs
Identical files are cached. Using stable file URLs lets repeat scans return from cache instead of re-downloading.
Integration examples
Node.js (dedicated scan endpoint)
async function scanFile(fileUrl, fileName) {
const response = await fetch('https://api.discuse.com/api/v2/scan', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': process.env.DISCUSE_API_KEY
},
body: JSON.stringify({ file_url: fileUrl, file_name: fileName })
});
return response.json();
}
Python (dedicated scan endpoint)
import os
import requests
def scan_file(file_url, file_name=None):
response = requests.post(
'https://api.discuse.com/api/v2/scan',
headers={
'Content-Type': 'application/json',
'X-API-Key': os.environ['DISCUSE_API_KEY']
},
json={'file_url': file_url, 'file_name': file_name}
)
return response.json()
Ready to protect your platform from malware? Get started with Discuse.