Quttera
Create your API account

Quttera Website Malware Scanner API v2.0

The Quttera's Website Malware Scanner API(Application Programming Interface) enables third-party applications or developers to access Quttera's WIS(Web Investigation System) data to perform "blacklisting check" and/or run a real-time scan of a domain programmatically via simple HTTP requests.

This API is designed primarily to help online businesses (ad networks, multi-sites owners and etc...) and security vendors to acquire the information about the URL/website/domain safety. Its real-time malware scanning component is highly effective and efficient against constantly evolving web threats. Based on years of research and real-life testing this version of API is more seasoned and adopted to the variety of security demands. It allows both the query to Quttera's database of already scanned URLs/domains and a request to run the new real-time scan. Additional flexibility is achieved by offering the customer to select the size of the overall downloaded content from the domain. As opposed to public scanner, you can select up to 150Mb of content.

Each new real-time malware scan retrieves the content from URLs located on the specified domain and performs in-depth investigation on each one of them. If identified suspicious scripts, malicious media, vulnerability exploits or any other web security threat, the API response will contain the detailed malware analysis info per scanned file.

This documentation describes how to request data from the API and how to interpret the response.

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

Getting started

We offer all accounts as standard monthly subscription with 14 days free trial period. This means that if you cancel your account before the end of the trial period you won't be charged.

To sign up just select from the available plans and create account via BlueSnap - online payment processing. You will receive the Quttera REST-API registration activation email from support@quttera.com with the activation link. Click the link to go to the web page and copy your personal API key.

Once you have the key, you can start querying the API.

Top

Pricing & usage policies

Quttera's API pricing is based on usage and the size of data to be downloaded from the domain (in scan requests only). All accounts have available set of query volume. Customers pay monthly fixed cost to activate the appropriate API key. Monthly subscription activates the key until the next payment cycle. If subscription was cancelled or was not renewed the unused requests will not be saved. NOTE: Scan requests quote is monthly while database query quote is daily.

Custom, no-obligation quote based on your requirements

As already stated, we offer various API account types and configurations for organizations and companies. Tell us about your needs and we will make sure you get the most accurate price. Email: cotactus@quttera.com

General terms

The rules below are used to count the API requests and they are applicable for all API accounts:

  1. URL investigation request to scan the domain that was last scanned more than 24h ago is counted as new scan request.
  2. Investigation report retrieval request for specified URL that was scanned in last 24h is counted as single database query.
  3. Consequent URL investigation request to scan the same domain is counted as new scan request.
  4. If investigation report retrieval request to a database failed to locate the report for specified domain, this will not be counted as database query.

Top

API summary

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 priviligies 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. See 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/<url>[.json|.xml|.yml]Submits domain for new scan
PUT /api/v2/<api-key>/url/scan/<url>[.json|.xml|.yml]Submits domain, with existing threat report, for re-scan
GET /api/v2/<api-key>/url/status/<url>[.json|.xml|.yml]Returns current status of domain submitted for scan
GET /api/v2/<api-key>/url/report/<url>[.json|.xml|.yml]Returns malware scan report for domain
DELETE /api/v2/<api-key>/url/<url>Removes scan data for domain
POST /api/v2/<api-key>/url/stats[.json|.xml|.yml]Returns information about the system

Top

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

Submits domain for scan via HTTP POST request

  • Parameters:

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

  • Usage:

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

  • 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).

    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/<url>[.json| .xml| .yml]

Submits domain for re-scan via HTTP PUT request.

  • Parameters:

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

  • Usage:

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

  • 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.yml
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.

    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/<url>[.json| .xml| .yml]

Retrieves current investigation status of URL submitted for scan.

  • Parameters:

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

  • Usage:

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

  • Example request:

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

  • 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/<url>[.json| .xml| .yml]

Retrieves detailed investigation report for previously scanned domain.

  • Parameters:

    NameTypeValue
    apikeymandatoryAPI key provided during registration
    urlmandatoryurl 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/<url>[.json|.xml|.yml]
GET http://api.server.com/api/v2/<api-key>/url/report/<url>

  • Example request:

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

  • Response:


    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/<url>

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

  • Parameters:

    NameTypeValue
    apikeymandatoryAPI key provided during registration
    urlmandatoryurl which scan report will be deleted

  • Usage:

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

  • 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| .yml]

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|.yml]
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

Support

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