Skip to main content

Documentation

Learning Center

Master content moderation with comprehensive guides, tutorials, and API documentation

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.

Written by the Discuse Team · Last updated June 2026