Skip to main content
POST
File Scan analyzes a file for malware and returns a verdict, file hash, and supporting indicators.

Authentication

Send your API key as Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Request

string
required
Set this value to file. It’s case-sensitive: FILE returns 400.
file
The file to scan, uploaded as multipart/form-data. Send exactly one of this field, content_base64, or source_url. When you omit filename, the uploaded file’s name is used.
string
For a JSON body, the base64-encoded file. Send raw base64 only, without a data URL prefix.
string
A URL from which Encrata downloads the file, such as a short-lived signed storage link. Only public http and https addresses are fetched: a private or internal address, a redirect to one, file://, or a URL that doesn’t return the file returns 400. Sending it together with file or content_base64 returns 400.
string
The original file name. Encrata checks it against the real file type, so send it whenever you have it.
boolean
Set to true to include STIX 2.1 output when available. Defaults to false. Any other value returns 400 with “stix must be true or false.”
The maximum file size is 10 MB, whether you upload the file or send a source_url.

Example request

Upload the file from disk as multipart/form-data. Replace document.pdf with the path to your file.
To send JSON instead, base64-encode the file into content_base64:
For files already in storage, send a short-lived download link in source_url instead of uploading the file:

Example response

A scan of the EICAR test file, a harmless file every antivirus detects:
credits is 0 because this file had been scanned before. A first scan returns 1.

How the verdict is decided

A medium-tier rule matches curl ... | sh anywhere, so an installation guide or README that contains such a command comes back suspicious with low confidence. It’s never malicious for that alone.

File result fields

A file result has the common fields plus these.
string
The SHA-256 hash of the scanned file.
string
The file type reported by the file scanner, such as PDF document, version 1.4.
integer
Credits this scan charged: 1, or 0 when you scanned the same file before, even under a different name.
object[]
Every check the scan ran and whether it answered. See Checks and coverage.
object[]
Evidence for the verdict. Each item contains source, malicious, detail, and optional severity. source is antivirus, detection_rules, embedded_content, file (the file name, an archive that couldn’t be opened, or a compression bomb), or engine (a check that didn’t run).
object[]
The hash reputation answer. source is always encrata intelligence.
object[]
What the scan observed. It always contains the file’s SHA-256 (with source set to upload), even when verdict is clean. Its role is threat when verdict is malicious or the hash matches a known malware sample, and observed otherwise. See IOCs.
See Malware Scan for the shared fields: assessment, recommended_action, confidence_reason, coverage, data_flow, and duration_ms.

Errors

Errors use the same envelope as successful responses, with success set to false. Branch on result.code. message is a sentence you can show to users. The response panel shows an example of each status. Errors aren’t charged.

Credits

A scan costs 1 credit. Scanning the same file again, even under a different name, is free and returns credits: 0.