Skip to content
FileSafety Docs

Quick Start

FileSafety is a REST API that scans files for viruses and NSFW content. This guide walks you through the five steps to get your first scan result.

1. Create an account

Section titled “1. Create an account”

Sign up at app.filesafety.dev/dashboard. You can start on the free plan with 10 scans per month — no credit card required.

2. Get your API key

Section titled “2. Get your API key”

After signing in, navigate to Settings in the dashboard sidebar. Your API key is displayed under the API Keys section. It looks like this:

fs_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

Copy it and store it somewhere safe. You will need it for every API request.

3. Scan a file

Section titled “3. Scan a file”

Use curl to submit a file for scanning. Replace YOUR_API_KEY with the key from step 2.

Terminal window
curl -X POST https://api.filesafety.dev/v1/scan \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@./document.pdf" \
  -F "webhook_url=https://your-app.com/webhooks/filesafety"

You will get back a response immediately:

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "pending",
  "eta_seconds": 15
}

4. Poll for the result

Section titled “4. Poll for the result”

While the scan is running, you can check its status:

Terminal window
curl https://api.filesafety.dev/v1/scan/scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V \
  -H "x-api-key: YOUR_API_KEY"

Once processing finishes, the response includes the full verdict:

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "complete",
  "verdict": "clean",
  "virus": {
    "engine": "clamav",
    "clean": true,
    "signature": null
  },
  "nsfw": {
    "clean": true,
    "categories": [],
    "confidence": 0.01
  },
  "file_hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "completed_at": "2026-03-23T12:00:00Z"
}

You will also receive this result as a webhook POST to the webhook_url you provided in step 3.

5. Understand the verdict

Section titled “5. Understand the verdict”

The verdict field tells you whether the file is safe:

VerdictMeaning
cleanNo threats detected. Safe to use.
infectedVirus or malware detected. The virus.signature field contains the threat name.
nsfwExplicit or inappropriate content detected. See nsfw.categories for details.
mixedBoth virus and NSFW issues detected.
failedScan could not complete. Retry or contact support.

Next steps

Section titled “Next steps”