Documentation | FileScanAPI

FileScanAPI

FileScanAPI offers a robust solution for malware detection. Simply upload a file directly to our platform, or direct us to a file's URL, and our API service will analyze it. We deliver an API response in real-time that identifies potential malware threats, ensuring your digital environment remains secure.

Definitions

Definition	Description
API Key	Uniquely assigned key to each API account to authenticate interactions with the API.

API Key

The FileScanAPI uses API keys to authenticate requests. You can view and manage your API key in the dashboard.

Please ensure to keep your API Key private as each request made with your API Key counts towards your account's plan limit.

To make an successful request, you must pass in your API Key into every request

We provide two ways to pass in your API Key for every request. Method one is to append your API Key to the request url. Method two is to pass in the API Key via the request header.

Method 1:

https://api.filescanapi.com/v1/file/27850df4-b22b-4444-a3b8-da89074a5898?api_key=API_KEY

Method 2:

curl https://api.filescanapi.com/v1/file/27850df4-b22b-4444-a3b8-da89074a5898 \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json'

API Quota

To determine your current request quota, you can take a look at the response header after a request.

Response Headers

Key	Description
`X-API-CURRENT`	Number of requests consumed for the month.
`X-API-QUOTA`	API quota limit for the month based on your account plan.

API Endpoints

We offer 3 endpoints, all which provides you access to different kinds of data. Below you will find a short summary of all available endpoints. Detailed explaination of any of the endpoints below will be provided in API Features.

// "file" - retrieve file Status and response (if processed).
https://api.filescanapi.com/v1/file

// "async file" - analyze a file asynchronously
https://api.filescanapi.com/v1/async/file

// "sync file" - analyze a file synchronously
https://api.filescanapi.com/v1/sync/file

API Error Codes

If your query fails, the API will return a 3-digit error-code and a plain text "info" property.

Example Error

{
  "success": false,
  "error": {
      "code": 104,
      "info": "Your monthly usage limit has been reached. Please upgrade your subscription plan."
  }
}

Common API Errors

Error Code	Description
`404`	User requested a non-existent API function
`500`	Something went wrong, please try again.
`101`	User did not supply an API Key
`102`	User did not supply an access key or supplied an invalid access key. Please sign up for a FREE API Key at filescanapi.com
`103`	The user's account is not active or this API key is deactivated
`104`	Too May Requests
`105`	User has reached or exceeded his subscription plan\'s monthly API request allowance
`201`	Invalid parameters
`202`	Upload failed
`203`	File is too large
`204`	Check "location" parameter. Unable to download file
`205`	Request timed out
`206`	No file id found

Additional Resources

API Response Samples	Download
Postman Project	See more

File

GET

Retrieve file Status and response (if processed).

Example API Request

https://api.filescanapi.com/v1/file/:id
?api_key=[API_KEY]

Request Parameters

Parameter	Description
`api_key`	[Required] Your API Key. More details.
`id`	[Required] Specify id.

Response

File Response

Async File

POST

Analyze a file asynchronously. We recommend this endpoint vs. sync analysis, especially with larger files.

Example API Request

https://api.filescanapi.com/v1/file/async
?api_key=[API_KEY]

Request Parameters

Parameter	Description
`api_key`	[Required] Your API Key. More details.
`location`	[optional] Specify file parameter or location parameter. Specify url where file is located.
`file`	[optional] Specify file parameter or location parameter. Specify file to upload.
`metadata`	[optional] Key value. Example use case is to store data and business logic such as internal IDs to be used post-processing.
`callback`	[Required] Specify callback url to call when our servers finish processing your file.

Example Location API Request

curl --location 'https://api.filescanapi.com/v1/file/async' \
  --header 'x-api-key: [API_KEY]' \
  --header 'Content-Type: application/json' \
  --data '{
      "location": "https://filescanapi.com/icon.png",
      "metadata": {
          "filename": "demo.png"
      },
      "callback": "https://example.com"
  }'

Example File API Request

curl --location 'https://api.filescanapi.com/v1/file/async' \
  --header 'x-api-key: [API_KEY]' \
  --form 'file=@"file.zip"' \
  --form 'metadata[filename]="file.zip"' \
  --form 'metadata[description]="description"' \
  --form 'callback="https://example.com"'

Response

File Response

Sync File

POST

Analyze a file synchronously. Async analysis is recommended for larger files.

Example API Request

https://api.filescanapi.com/v1/file/sync
?api_key=[API_KEY]

Request Parameters

Parameter	Description
`api_key`	[Required] Your API Key. More details.
`location`	[optional] Specify file parameter or location parameter. Specify url where file is located.
`file`	[optional] Specify file parameter or location parameter. Specify file to upload.
`metadata`	[optional] Key value. Example use case is to store data and business logic such as internal IDs to be used post-processing.

Example Location API Request

curl --location 'https://api.filescanapi.com/v1/file/sync' \
  --header 'x-api-key: [API_KEY]' \
  --header 'Content-Type: application/json' \
  --data '{
      "location": "https://filescanapi.com/icon.png",
      "metadata": {
          "filename": "demo.png"
      }
  }'

Example File API Request

curl --location 'https://api.filescanapi.com/v1/file/sync' \
  --header 'x-api-key: [API_KEY]' \
  --form 'file=@"file.zip"' \
  --form 'metadata[filename]="file.zip"' \
  --form 'metadata[description]="description"'

Response

File Response

Download sample responses

Example API Response

{
  "success": true,
  "data": {
    "id": "46b3b1b3-83b8-4153-8035-eefe41894789",
    "created_at": "2024-03-18T20:48:17.998Z",
    "status": {
      "code": 200,
      "message": "success"
    },
    "result": [],
    "metadata": {
      "filename": "currency.csv"
    },
    "stat": {
      "content_length": 4456,
      "checksum_md5": "bcc146cc324ddd4cf6d96a8416e966f3",
      "checksum_sha1": "03dafc63a05fa848a9c662fd180c513661e9d229",
      "checksum_sha256": "8a4d19d18c30b7774cd68355aef0e889bb88f9e29965dcd126374e32d2a2d87e",
      "created_at": "2024-03-18T20:48:20.062Z",
      "last_modified": "2024-03-18T20:48:20.354Z"
    }
  }
}

Response Attributes

Attribute Description

success Returns true or false depending if the API Request succeeded. If false, refer to API Errors.

data

id Unique ID of the response. Use this ID in file endpoint

created_at When the file was created in FileScanAPI system.

status Analysis status

code/message

code	message	Description
`100`	in progress
`200`	success
`301`	callback url failed	Check the callback url passed in. Callback url http status code is non-successful response.

result Name of malware found. Array will be empty if no malware found. Prefixed with mal.

metadata Depending on the key that is passed in. Returns key values of the argument metadata

stat File statistics

content_length File's content length

checksum_md5 File's md5 checksum

checksum_sha1 File's sha1 checksum

checksum_sha256 File's sha256 checksum

created_at File's created_at

last_modified File's last_modified

Overview & Specs

API Endpoints

Response

FileScanAPI

Definitions

API Key

API Quota

API Endpoints

API Error Codes

Additional Resources

File

Async File

Sync File

File Response