API Overview

The FileSafety API is a RESTful JSON API for scanning files against viruses and NSFW content.

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`
`application/json`	Presigned URL requests to `POST /v1/scan`, all other endpoints

Responses are always application/json.

Endpoints

Method	Path	Description
`POST`	`/v1/scan`	Submit a file for scanning (direct upload or presigned URL)
`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	A scan engine 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.

Request IDs

Every API response includes a unique request identifier for troubleshooting. Include this ID when contacting support about a specific request.

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.