Skip to content
FileSafety FileSafety Docs

Quick Start

FileSafety is a content security API that detects malware, identifies unsafe images, and analyzes text content in uploaded files. This guide walks you through the steps to get your first scan result.

1. Create an account

Section titled “1. Create an account”

Sign up at 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"

This uses the sync endpoint, which waits for the scan to complete and returns the full result directly. Best for files under ~100 MB. For very large files or when you want a non-blocking workflow, use the async endpoint (POST /v1/scan/async) instead — see First Scan for details.

4. Read the result

Section titled “4. Read the result”

The sync endpoint returns the complete scan result:

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "complete",
  "verdict": "clean",
  "virus": {
    "clean": true,
    "signature": null
  },
  "nsfw": {
    "clean": true,
    "categories": [],
    "confidence": 0.01
  },
  "text": {
    "clean": true,
    "toxic": { "labels": [], "maxScore": 0.0 },
    "pii": { "entities": [], "count": 0 },
    "sentiment": { "dominant": "NEUTRAL", "scores": {} }
  },
  "file_hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "completed_at": "2026-03-23T12:00:00Z"
}

The response includes three types of analysis (applied automatically based on file size):

  • virus — Malware detection (all files)
  • text — Text content analysis including toxicity, PII detection, and sentiment (files up to 100 MB)
  • nsfw — Unsafe image detection (files up to 10 MB)

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.
toxicToxic or harmful text content detected. See text.toxic for details.
mixedMultiple types of issues detected.
failedScan could not complete. Retry or contact support.

Next steps

Section titled “Next steps”