Online Website Malware Scanner
SaaS Web Malware Solution

Quttera API attempts to conform to the design principles of Representational State Transfer (REST). Simply change the format extension in a request to get results in the format of your choice. API supports JSON, XML and YAML formats. If no format is specified, JSON is used as default format.

HTTP Status Codes

The Quttera API attempts to return appropriate HTTP status codes for every request.

Code Text Description
200 OK Success!
400 Bad Request The request was invalid. In API v2.0, a request with invalid URL, invalid format or wrong parameter is considered invalid and you will get this response.
401 Unauthorized API key is incorrect or is not activated.
402 Payment Required Returned when user reached limit of scan requests quota. In order to continue using scan API a new key must be purchased.
403 Forbidden The request is understood, but it has been refused or access is not allowed. In example it is returned when user with blacklisting plan privileges tries to scan a domain or delete the scan report.
404 Not Found The URI requested is invalid or the resource requested, such as URL or Investigation Report does not exist.
429 Too Many Requests Returned in API v2.0 when a request cannot be served due to the daily rate limit having been reached for the API key. Contact us for API Plans and Pricing.
500 Internal Server Error Something is broken. Please post to the group or email the support

API request types

Resource Description
POST /api/v2/<api-key>/url/scan/<domain-name>[.json|.xml|.yaml]Submits domain for new scan
PUT /api/v2/<api-key>/url/scan/<domain-name>[.json|.xml|.yaml]Submits domain, with existing threat report, for re-scan
GET /api/v2/<api-key>/url/status/<domain-name>[.json|.xml|.yaml]Returns current status of domain submitted for scan
GET /api/v2/<api-key>/url/report/<domain-name>[.json|.xml|.yaml]Returns malware scan report for domain
DELETE /api/v2/<api-key>/url/<domain-name>Removes scan data for domain
POST /api/v2/<api-key>/url/stats[.json|.xml|.yaml]Returns information about the system

Top

POST /api/v2/<api-key>/url/scan/<domain-name>[.json| .xml| .yaml]

Submits domain for scan via HTTP POST request

  • Parameters:

    NameTypeValue
    apikeymandatoryAPI key provided during registration
    domain-namemandatoryurl to scan
    formatoptionalyaml, xml or JSON. Default is JSON

  • Usage:

    POST http://api.server.com/api/v2/<api-key>/url/scan/<domain-name>[.json| .xml| .yaml]
    POST http://api.server.com/api/v2/<api-key>/url/scan/<domain-name>

  • Example request:

    XML format
      # curl -X POST http://api.quttera.com/api/v2/A58E3D9E-514B-31DE-9617-2EB82B6770D0/url/scan/quttera.com.xml
    JSON format (default)
      # curl -X POST http://api.quttera.com/api/v2/A58E3D9E-514B-31DE-9617-2EB82B6770D0/url/scan/quttera.com

  • Response:

    If URL has already been investigated in last 24 hours, the output will contain domain status (clean, potentially suspicious, suspicious or malicious).

    If scan job is 'in progress', the output will contain 'current investigation status' (new, download, downloaded or scan).

    Returned Parameters:

    urlScanned URL
    ageTime when scan job started
    left_ro_requestsNumber of database query requests left for the specified API key
    left_rw_requestsNumber of scan/re-scan requests left for the specified API key
    stateCurrent investigation status of the URL. If scan is in progress then this parameter will contain one of the following values (new, download, downloaded or scan). If scan finished, then this parameters will contain one of the following values (clean, potentially suspicious, suspicious or malicious).

  • Screenshot:
    • Scan domain request to Quttera's API

      Scan domain request to Quttera's API

      Example of malware scanner API output for google.com domain

Top

PUT /api/v2/<api-key>/url/scan/<domain-name>[.json| .xml| .yaml]

Submits domain for re-scan via HTTP PUT request.

  • Parameters:

    NameTypeValue
    apikeymandatoryAPI key provided during registration
    domain-namemandatoryurl to re-scan
    formatoptionalyaml, xml or JSON. Default is JSON

  • Usage:

    PUT http://api.server.com/api/v2/<api-key>/url/scan/<domain-name>[.json| .xml| .yaml]
    PUT http://api.server.com/api/v2/<api-key>/url/scan/<domain-name>

  • Example request:

    YAML format
      # curl -X PUT -H 'Content-Length: 0' http://api.quttera.com/api/v2/A58E3D9E-514B-31DE-9617-2EB82B6770D0/url/scan/quttera.com.yaml
    JSON format (default)
      # curl -X PUT -H 'Content-Length: 0' http://api.quttera.com/api/v2/A58E3D9E-514B-31DE-9617-2EB82B6770D0/url/scan/quttera.com

  • Response:

    Note: if provided URL was never scanned this API will work like previous one.

    If URL is in progress this request will return current status of scan job and won't start a new re-scan. If this URL was scanned before and the report exists in database then this request will always start a new scan.

    Returned Parameters:

    urlScanned URL
    ageTime when scan job started
    left_ro_requestsNumber of database query requests left for the specified API key
    left_rw_requestsNumber of scan/re-scan requests left for the specified API key
    stateCurrent investigation status of the URL. If scan is in progress then this parameter will contain one of the following values (new, download, downloaded or scan). If scan finished, then this parameters will contain one of the following values (clean, potentially suspicious, suspicious or malicious).

  • Screenshot:
    • Scan domain request to Quttera's API

      Re-scan domain request to Quttera's API

      Example of malware scanner API output for rescan of google.com domain

Top

GET /api/v2/<api-key>/url/status/<domain-name>[.json| .xml| .yaml]

Retrieves current investigation status of URL submitted for scan.

  • Parameters:

    NameTypeValue
    apikeymandatoryAPI key provided during registration
    domain-namemandatoryurl to get the status for
    formatoptionalyaml, xml or JSON. Default is JSON

  • Usage:

    GET http://api.server.com/api/v2/<api-key>/url/status/<domain-name>[.json| .xml| .yaml]
    GET http://api.server.com/api/v2/<api-key>/url/status/<domain-name>

  • Example request:

    YAML format
      GET http://api.quttera.com/api/v2/A58E3D9E-514B-31DE-9617-2EB82B6770D0/url/status/quttera.com.yaml

  • Response:

    If requested URL doesn't exist in database, the query returns "not-found" error.

    If URL was found then its investigation status is being returned.

    Following are some examples of the domain/URL investigation status responses for quttera.com domain:

    If quttera.com was never scanned before 
     # 'Required URL not found'
     
    If quttera.com scan status is: 'new' or 'download'  
     # 'quttera.com is being scanned' 
     
    If quttera.com scan status is: 'downloaded'  
     # 'Current investigation status of quttera.com is: downloaded'  
     
    If quttera.com scan status is: 'clean' 
     # 'Current investigation status of quttera.com is: clean'
     
    If quttera.com status is: 'potentially suspicious' 
     # 'Current investigation status of quttera.com is: potentially suspicious'
     
    If quttera.com status is: 'suspicious' 
     # 'Current investigation status of quttera.com is: suspicious'
     
    If quttera.com status is: 'malicious' 
     # 'Current investigation status of quttera.com is: malicious'

  • Screenshot:
    • Scan domain request to Quttera's API

      Get scan status request to Quttera's API

      Example of malware scanner API output when requesting the scan job status for google.com domain

Top

GET /api/v2/<api-key>/url/report/<domain-name>[.json| .xml| .yaml]

Retrieves detailed investigation report for previously scanned domain.

  • Parameters:

    NameTypeValue
    apikeymandatoryAPI key provided during registration
    domain-namemandatoryurl to get the scan report for
    formatoptionalyaml, xml or JSON. Default is JSON

  • Usage:

    GET http://api.server.com/api/v2/<api-key>/url/report/<domain-name>[.json|.xml|.yaml]
    GET http://api.server.com/api/v2/<api-key>/url/report/<domain-name>

  • Example request:

    YAML format
      GET http://api.quttera.com/api/v2/A58E3D9E-514B-31DE-9617-2EB82B6770D0/url/report/quttera.com.yaml

  • Response:

    Returns detailed sitescan report for previously scanned domain.
    Returned Parameters:

    urlScanned URL
    ageScan start time
    stateCurrent investigation status of the URL. If scan is in progress then this parameter will contain one of the following values (new, download, downloaded or scan). If scan finished, then this parameters will contain one of the following values (clean, potentially suspicious, suspicious or malicious).
    left_ro_requestsNumber of database query requests left for the specified API key
    left_rw_requestsNumber of scan/re-scan requests left for the specified API key
    reportlist of malware scan reports per each file downloaded from the domain. Each report contains the following fields:
    • File - URI to investigated file
    • Severity - severity of the detected threat
    • Reason - reason why the file was detected
    • Details - more details on detection
    • Offset - offset of the detection (if applicable)
    • Threat dump - dump of the malware (if applicable)
    • File size [byte] - size of this file
    • File type - type of this file
    • MD5 - MD5 signature of this file
    • Scan time [sec] - time in seconds required to scan this file

  • Screenshot:
    • Scan domain request to Quttera's API

      Get malware scan report request to Quttera's API

      Example of malware scanner API output when malware report for google.com domain was requested (Broken-view is used because of the file size)

Top

DELETE /api/v2/<api-key>/url/<domain-name>

Removes investigation information of previously scanned domain. Note: OEM installation only.

  • Parameters:

    NameTypeValue
    apikeymandatoryAPI key provided during registration
    domain-namemandatoryurl which scan report will be deleted

  • Usage:

    DELETE http://api.server.com/api/v2/<api-key>/url/<domain-name>

  • Example request:

     # curl -X DELETE http://api.quttera.com/api/v2/A58E3D9E-514B-31DE-9617-2EB82B6770D0/url/quttera.com

Top

POST /api/v2/<api-key>/url/stats[.json| .xml| .yaml]

Retrieves current status of the system. Note: OEM installation only.

  • Parameters:

    NameTypeValue
    apikeymandatoryAPI key provided during registration
    formatoptionalyaml, xml or JSON. Default is JSON

  • Usage:

    POST http://api.server.com/api/v2/<api-key>/url/stats[.json|.xml|.yaml]
    DELETE http://api.server.com/api/v2/<api-key>/url/stats

  • Example request:

    XML format
     # curl -X POST http://api.quttera.com/api/v2/A58E3D9E-514B-31DE-9617-2EB82B6770D0/url/stats.xml

  • Response:

    API reply format:

    download_pended      - number of URLs in new state (before download)
    downloading          - number of URLs in download state
    scan_pended          - number of downloaded URLs waiting for scanner
    scanning             - number of URLs in scan state
    total_in_progress    - total number of URLs in progress

If you have any questions about the API you can chat with us at our Forum or send us an email (support@quttera.com).

Top


  • Connect With Us
  • Facebook
  • Twitter
  • YouTube

Powered by Quttera © 2014. All rights reserved