API Overview

The FileSafety API is a RESTful JSON API for scanning files and URLs. It provides three types of analysis, applied automatically based on file size:

Malware detection — Viruses, trojans, ransomware, and other threats (all files).
Content analysis (images) — Explicit nudity, suggestive content, graphic violence (files up to 10 MB).
Content analysis (text) — Toxic language, PII detection, and sentiment analysis (files up to 100 MB).

All scan types are included in every plan at no extra cost.

Base URL

All API requests use the following base URL:

https://api.filesafety.dev

All endpoints are served over HTTPS. Plain HTTP requests are rejected.

Versioning

The API is versioned via the URL path. The current version is v1:

https://api.filesafety.dev/v1/scan

When breaking changes are introduced, they will ship under a new version prefix (e.g., /v2/). The previous version will continue to work for a documented deprecation period.

Authentication

Every request must include your API key in the x-api-key header:

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

See Authentication for key format, rotation, and security best practices.

Content types

The API accepts two content types depending on the endpoint:

Content Type	Used For
`multipart/form-data`	Direct file uploads to `POST /v1/scan` and `POST /v1/scan/async`
`application/json`	URL scanning, presigned URL requests, and all other endpoints

Responses are always application/json.

Endpoints

Method	Path	Description
`POST`	`/v1/scan`	Scan a file or URL synchronously (returns result in the response)
`POST`	`/v1/scan/async`	Scan a file or URL asynchronously (returns scan ID; poll or use webhooks)
`GET`	`/v1/scan/{id}`	Retrieve the status and results of a scan
`GET`	`/v1/usage`	Check your current plan quota and usage

Common response format

Success responses

Successful responses return a JSON object with endpoint-specific fields. There is no wrapping envelope — the data is at the top level:

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

Error responses

Error responses use a consistent format with an error field and an appropriate HTTP status code:

{
  "error": "Invalid or missing API key"
}

Status	Error Type	Description
`400`	ValidationError	Missing or invalid request parameters
`401`	InvalidApiKeyError	API key is missing, malformed, or revoked
`404`	ScanNotFoundError	The requested scan ID does not exist
`429`	QuotaExceededError	Monthly scan quota reached (free plan blocks; paid plans allow overage)
`502`	UpstreamError	An upstream service failed or timed out

See Errors for detailed descriptions and troubleshooting.

Rate limits

The API does not currently enforce per-second rate limits. Throughput is governed by your plan’s monthly scan quota. If you are on the free plan and exceed your 10-scan quota, requests return 429. Paid plans allow overage at $0.01 per additional scan.

Pagination

No endpoints currently return paginated results. The usage endpoint returns aggregate data, and scan results are retrieved individually by ID.

SDKs and libraries

The API is designed to work with standard HTTP clients in any language. See Code Examples for ready-to-use implementations in curl, Node.js, and Python.