GET /v1/scan/{id}

Retrieve the status and results of a previously submitted scan.

GET https://api.filesafety.dev/v1/scan/{id}

Authentication

Requires x-api-key header. See Authentication.

Path parameters

Parameter	Type	Description
id	string	The scan ID returned by POST /v1/scan (e.g., scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V).

Example request

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

Response schema

Field	Type	Present	Description
scan_id	string	Always	Unique scan identifier.
status	string	Always	Current scan status. See lifecycle below.
verdict	string	When complete	Overall result: clean, infected, nsfw, mixed, or failed.
virus	object	When complete	Virus scan results.
virus.engine	string	When complete	Scan engine used. Currently always "clamav".
virus.clean	boolean	When complete	true if no virus detected.
virus.signature	string | null	When complete	Name of the detected threat, or null if clean.
nsfw	object	When complete	NSFW scan results.
nsfw.clean	boolean	When complete	true if no NSFW content detected.
nsfw.categories	string[]	When complete	List of detected NSFW categories (empty if clean).
nsfw.confidence	number	When complete	Confidence score between 0 and 1.
file_hash	string	When complete	Cryptographic hash of the file, prefixed with sha256:.
completed_at	string	When complete	ISO 8601 timestamp of when scanning finished.

Status lifecycle

A scan moves through the following statuses:

awaiting_upload → pending → scanning → complete
                                     ↘ failed

Status	Description
awaiting_upload	Presigned URL was issued but the file has not been uploaded yet.
pending	File received and queued for scanning.
scanning	Scan engines are actively processing the file.
complete	Scanning finished. Verdict and results are available.
failed	Scanning could not complete due to an internal error.

Verdict values

The verdict field is present only when status is complete:

Verdict	Meaning
clean	No threats detected by any scan engine.
infected	Virus or malware detected. Check virus.signature for the threat name.
nsfw	NSFW content detected. Check nsfw.categories for details.
mixed	Both virus and NSFW issues detected.
failed	At least one scan engine failed. Retry the scan.

Example responses

Awaiting upload

{
  "scan_id": "scn_01HX8A1B2C3D4E5F6G7H8I9J0K",
  "status": "awaiting_upload"
}

Pending

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

Scanning

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "scanning"
}

Complete — clean

{
  "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"
}

Complete — infected

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "complete",
  "verdict": "infected",
  "virus": {
    "engine": "clamav",
    "clean": false,
    "signature": "Win.Trojan.Agent-123456"
  },
  "nsfw": {
    "clean": true,
    "categories": [],
    "confidence": 0.02
  },
  "file_hash": "sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "completed_at": "2026-03-23T12:01:30Z"
}

Complete — nsfw

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "complete",
  "verdict": "nsfw",
  "virus": {
    "engine": "clamav",
    "clean": true,
    "signature": null
  },
  "nsfw": {
    "clean": false,
    "categories": ["explicit_nudity", "graphic_violence"],
    "confidence": 0.97
  },
  "file_hash": "sha256:f1e2d3c4b5a6f1e2d3c4b5a6f1e2d3c4b5a6f1e2d3c4b5a6f1e2d3c4b5a6f1e2",
  "completed_at": "2026-03-23T12:02:45Z"
}

Failed

{
  "scan_id": "scn_01HX7Z9K3M2N4P5Q6R7S8T9U0V",
  "status": "complete",
  "verdict": "failed"
}

Error responses

Status	Error	Cause
401	"Invalid or missing API key"	Missing or invalid x-api-key header.
404	"Scan not found"	No scan exists with the given ID.

Polling recommendations

• Poll every 2-3 seconds after submitting a scan.
• Most scans complete within 15 seconds.
• Stop polling when status is complete or failed.
• For production use, prefer webhooks over polling to reduce unnecessary requests.