VirusCheckMate Developer Guide

  DOWNLOAD PHP EXAMPLES

General rules of API v1

POST/api/{version}/{method}/{submethod}/{another_params/}{response type}
ParameterDescription
versionVersion of API interface, for now - v1
methodservice or check
response_typejson (by default) or xml
Response (in json format):
{
  "status":   {status}
  "status_t": {message}
  "data":     {...}
}
VariableDescription
statusRequest status, 1 is OK and -1 is error, see status_t for additional information
status_tAdditional information, 'OK' or error message
HTTP Statuses:
ValueDescription
200OK
206OK, partial results, task is not finished
400Incorrect input data (see status_t for more information)
401Authorization errors
403Account blocked
404Task not found
405Method not allowed
500Service errors
503Service closed for maintenance

Get Service Information

Receiving list of available engines and user-agent profiles.
POST/api/v1/service/get/{task_id/}{response type}
Request parameters:
ParameterRequiredDefaultDescription
apikeyfalse-If specified, return list of possible engines and ua profiles for current user
task_idfalse-If specified, return list of engines for current task

Heads up! Field apikey used for authorization. The key is generated for each user, and also depends on the IP address. Keys are not suitable for use with a computer with an IP address different from the one on which it was generated. You can find your current apikey in settings page.

Response:
{
  "status": 1      
  "status_t": "OK" 
  "data":{
    "engines":{
      1:{
        "id": 1                              // Engine ID
        "status": 1                          // Status of engine:
                                             // 	1 - ready
                                             //		0 - unavailable now
        "short_name": "nod32"                // Short name of engine
        "full_name": "ESET NOD32 Antivirus"  // Full name
        "version": "7.0.302.26"              // Full version 
        "def_time": "27-02-14 13:32"         // Time if definitions update (in GMT)
        "type": 3                            // Types of checks possible on this engine:
                                             //		1 - only file and webpages
                                             //		2 - only domain
                                             //		3 - all types
        "is_cloud": 0                        //		0 - without cloud
                                             //		1 - cloud-based
        "in_task": 1                         // 	1 - present in task, or task not specified
                                             // 	0 - task specified, but engine not present in task
        }
      2:{
        "id": 2
        "status": 1
        "short_name": "mssec"
        "full_name": "Microsoft Security Essentials"
        "version": "2.1.1116.0"
        "def_time": "27-02-14 13:14"
        "type": 1
        "in_task": 1
        }
        ...
    }
    "uaprofiles":{
      0:{
        "agent_name": "Firefox on Windows XP"  // Name of UA profile
        "owner": 0                             // 	0 - public profile
                                               // 	1 - created by the current user
        "id": 3                                // Profile ID
        }
      1:{
        "agent_name": "IE 9 on Windows 7"
        "owner": 0
        "id": 4
        }				
		...
	}
    "task_type": 0                            // If task_id specified than indicates the type of task
                                              // 	1 - file
                                              // 	2 - link
                                              // 	3 - webpage
                                              // 	4 - domain
                                              // 	5 - IP
                                              // 	6 - list of domains and IPs
                                              // 	7 - file on cloud-based modules
                                              // 	8 - link on cloud-based modules
                                              // if not -  null
  }
}
Examples:
POST/api/v1/service/get/
no params
POST/api/v1/service/get/
apikey55de2e769181d9259fc0bc96ab6e34c55ba8b909

Get Task Data

POST/api/v1/check/get/{task_id/}{crc32/}{response type}
Request parameters:
ParameterRequiredDefaultDescription
task_idtrue-Task ID (example : 'EU1ZL9n0O5Ka')
crcfalse-Checksum from the previous query. If no new data, the field data is empty in response, to reduce traffic (example: 'crc-32444234')
Response:
HTTP Statuses:
ValueDescription
200Task finished
206Task in work, partial results returned
404Task not found
Data conteins blocks:
Block nameDescription
infoTask information
resultsResults of checks
objectsInformation about objects
warningsErrors, warnings, and notifications
crc32CRC32 of data
Important fields:
Fields nameDescription
info.status Status of task:
-1
Error
0
Task in queue
1,2,3
Task in work
4,5,6,7
Task finished
results.{engine}.statusStatus of current engine:
0
Not started yet
1
Started
2
Finished
results.{engine}.objects.{object}.statusStatus of current object in current engine:
0
Not started yet
1
Fast check is complete, see fast_detect for result
2
Slow check is complete or not required, see slow_detect for result
warnings.{number}.levelLevel of risk:
0
Debug message (not displayed without the debug mode)
1
Notifications
2
Warnings
3
Errors
4
Critical errors
{
   "status":1,
   "status_t":"Partial results",
   "data":{
      "info":{
         "check_id":"PY3kN2SXumYU",         // Task ID
         "status":3,                        // Status
         "object_name":"test.rar",          // Name of main object
         "objects_count":2,                 // Objects (files, pages...) in task
         "objects_size":238592,             // Summary size of unpacked objects
         "isfast":0,                        // Option 'option_fast'
         "started_at":"28-02-14 14:24:11",  // Time of creation (GMT)
         "duration":0                       // Duration in seconds, equal null if not finished
      },
      "results":{
         "comodo":{                         // Short name of engines
            "status":2,                     // Status of task
            "objects":{						
               "first.exe":{                // Object name
                  "fast_detect":0,          // Status of fast detection:
                                            //   1 - detect
                                            //   0 - clean, or not finished
                                            // ('status' of object must be 1 before using this field)
                  "slow_detect":0,          // Status of slow detection:
                                            //   1 - detect,
                                            //   0 - clean, or not finished
                                            // ('status' of object must be 2 before using this field)
                  "detect_name":"",         // Name of detection or empty
                  "status":2                // Status of current object in current engine
               },
               "second.exe":{
                  "fast_detect":0,
                  "slow_detect":0,
                  "detect_name":"",
                  "status":2
               }
            }
         },
         "adaware":{
            "status":2,
            "objects":{
               "first.exe":{
                  "fast_detect":1,
                  "slow_detect":1,
                  "detect_name":"Gen:Variant.Kazy.319707",
                  "status":2
               },
               "second.exe":{
                  "fast_detect":1,
                  "slow_detect":1,
                  "detect_name":"Gen:Variant.Kazy.319707",
                  "status":2
               }
            }
         },
         "twister":{
            "status":1,
            "objects":{
               "first.exe":{
                  "fast_detect":1,
                  "slow_detect":0,
                  "detect_name":"",
                  "status":1
               },
               "second.exe":{
                  "fast_detect":1,
                  "slow_detect":0,
                  "detect_name":"",
                  "status":1
               }
            }
         },
         ...
      },
      "objects":[
         {
            "object":"first.exe",                               // Name of object
            "size":119296,                                      // Size of object
            "md5":"47c1cad6cf170a695670096dda35d4c6",           // MD5
            "sha1":"fa33cb459217121c2cb849323ecf80d8f615f248"   // SHA1
         },
         {
            "object":"second.exe",
            "size":119296,
            "md5":"3608b60a453b6c0e9cc55f02768e1d3e",
            "sha1":"0761110ffe313dd8ff8e5e5346db0485e03ec492"
         }
      ],
      "warnings":{
         "1131585":{                                            // Number of the ticket for the support
            "error":"ERROR_FILE_WARNING",                       // Unlocale error text,
                                                                // for full text of error use the file
            "level":2,                                          // Level of risk
            "engine_id":30,                                     // ID of engine, if null error is a general
            "engine_name":"twister",                            // Engine short name
            "object_name":"first.exe"                           // Object name
         }
      },	  
      "crc32":893397190
   }
}
Examples:
POST/api/v1/check/get/PY3kN2SXumYU/
no params
POST/api/v1/check/get/PY3kN2SXumYU/crc-893397190/xml
no params

Create New Task

POST/api/v1/check/new/
Request parameters:
ParameterRequiredDefaultDescription
apikeytrue--
task_typefalsefileType of check, can be 'file', 'link', 'webpage', 'domain', 'clouds_file', 'clouds_link'
filefalse-File for check, required if task_type is 'file', or not specified
urlfalse-Link to file for checking (type 'file'), to webpage (type 'webpage') or domain name
enginesfalsemain profileEnumeration short names separated by ','
Like "nod32,avg,norman,vba32"
use_profilefalse-Profile name to use, can use public
Like 'All available' or private)
uagentsfalseall publicEnumeration of Uset-Agents profiles separated by ','
Like "Firefox on Windows XP,IE 9 on Windows 7"
option_fastfalsefalseTo use 'fast' type of check
option_usecachefalsetrueTo disable caching results (not check if already detected)
option_autocheckfalsefalseTo move task to autochecks
response_typefalseon_closeWait until the task finished (do not use a field or 'on_close') or return immediately (any value except 'on_close')
Response:

If response_type set to 'on_close' or not used equal 'Get Task Data' results
Else return immediately, and if no error then HTTP STATUS equal 200

{
  "status":1,
  "status_t":"Task created",
  "data":{
    "task_id":"CW0sIiUpL92N"  // New task ID
  }
}
Examples:

Check file "file_to_check.exe" for all available engines:

POST/api/v1/check/new/
apikey55de2e769181d9259fc0bc96ab6e34c55ba8b909
file@C:\file_to_check.exe

Check file from url, use AVG and NOD32 engines, and move to autochecks , return immediately

POST/api/v1/check/new/
apikey55de2e769181d9259fc0bc96ab6e34c55ba8b909
task_typeurl
urlhttp://example.com/test.zip
enginesnod32,avg
option_autochecktrue
response_typeimmediately

Check webpage, use option 'fast' and couple of own User-Agent profiles, return after task is completed

POST/api/v1/check/new/
apikey55de2e769181d9259fc0bc96ab6e34c55ba8b909
task_typewebpage
urlhttp://example.com/index.php
option_fasttrue
uagentsFirefox 25 on Windows 7,Chrome 33 on Windows 7

Check domain, use own profile 'All actual for me', return immediately

POST/api/v1/check/new/
apikey55de2e769181d9259fc0bc96ab6e34c55ba8b909
task_typedomain
urlwww.viruscheckmate.com
use_profileAll actual for me
response_typeimmediately