API Usage for File search (2.0)

It's just an HTTP GET, and the page will return some simple text/XML/JSON/serialize indicating the file risk, adding hash and some other information.

Example:
  • http://{your_api_host}/2.0/file/?md5=945FBB881AE927A44DFD96440F2F4F44&len=7040&pkey=&out=1

Parameters

These are the input values that specify your request.

Parameter Description
pkey (REQUIRED) Each subscriber to API Web Services is uniquely identified by an ID sequence and every request to Web services requires this ID.
md5 MD5 hash of file
len File size in bytes
out You can select your response format with "out" parameter.
The default is 0 — text, 1 — JSON, 2 — XML, 3 — PHP SERIALIZE . By default as 0
qt Optional parameter for show query process time. By default as 0

Returns

API returns XML, JSON or text which means it can be used within any programming language and on any platform.
XML example: <ace2.0> <md5>945FBB881AE927A44DFD96440F2F4F44</md5> <crc32>27755BF8</crc32> <filesize>7040</filesize> <risk>0</risk> <filename>KDCOM.DLL</filename> </acefile>

Response fields

Please note that the number of response parameters may change from time to time to tell you more about particular threats.

  • md5 — hash of file
  • crc32 — hash of file, must be used for prevent hash collision
  • filesize — size of file
  • risk — file risk. 0 - clean, 10 - clean (auto-verdict), 70 - suspicion, 100 - malware
  • filename — name of file in ACE DB

Risk

Risk Level (%) Description
0 file is clean
10 file is clean (auto verdict)
70 malware suspicion
100 malware

Returns for simple text

0
27755BF8
# Request generated in 0.004711 seconds. 4 queries.

ACE return two strings have result values and CRC32 (optional comment string):

String 1: VERDICT (Object risk level)
String 2: CRC32 of file.
String 3: (optional, start from # char) debug information.

Returns for unknown (clean) file

Means that the processed checks are OK and the tested file is not located at one of the known malware or suspicion DB.

COMPLETED: OK. Not found.

Error reporting

Any errors reported, within the control of the API, will be presented in the simple text format and started from "ERROR:"

  • ERROR: Validating API request format failed, please check your API request.
  • ERROR: Authenticating customer failed, please check your authentication ID.
  • ERROR: Authenticating customer failed, your authentication ID is disabled.
  • ERROR: API determines some internal errors, please try again or contact us.