API Reference

This pages provides a simple reference for the scanning REST API. This is all you need for 99% of use cases. You can try these end points in your browser from this page.

For more advanced usage see the full Open API 3.0 definition and Swagger UI

Choose API Key

You can use this page to try the various API end points.

The default API Key is used here, but you choose another by clicking the button below.

Currently Selected API Key:

Name: Default

Key: r2iKI4q7Lu91Nu5uPl3eW3BPmRo4XK1ZbhLWtOKd

You’ll need to sign in to use your own keys.

To create your own key see How To Create A Key

Scan Helpers

The Scan Helper end points are the simplest way to use the API. They are a wrappers for the standard Scanning end points. Designed for use from simple scripting languages or no code tools with limited functionality. They take care of SHA256, upload to storage and polling for the scan result, so you can just upload the file and get the result.

Web Scanning

The web scanning end points are straight forward to use, simply specify the URL to scan and call the API.

You can choose between score, quick scan and deep End Points depending on the depth analysis you want. See Types Of Scan.

You will receive a report_id that you use with the Report Retrieval end point to get the full analysis report. If the scan was done synchronously you’ll also get the score and verdict, otherwise they will also be available via the Report Retrieval end point when the scan is complete.

File Scanning

To scan a file, take its SHA256 and call one of the scanning end points. If the platform doesn’t need the file (data may be cached) you’ll get the result.

If the file is needed, you’ll get an HTTP 404 and you’ll need to upload the file with the File Upload end point before trying again. See Uploading A Threat Object.

For use cases where your scanning new files the platform is un likely to hace cached data on, you’ll be better calling the file upload first.

As with Web, you can choose between score, quick scan and deep End Points depending on the depth analysis you want. See Types Of Scan.

Email Scanning

Email scanning is similar to File scanning in that you can call the API first with the email_id. Typically the email_id is the SHA256 of the email, but it does not have to be, it can be any user defined id unique to the email. Like the File Scanning end points, if the Platform needs the email you’ll get a 404 and you’ll need to use the upload end point to upload it. See Uploading A Threat Object. In most Email scanning use cases you’ll only scan the email once so your better off uploading first.

The there are a few more end points for Email then there are for Web or File, that’s to allow you to specify wether your want scan the full email, attachments only or both.

As with Web and File you can choose between score, quick scan and deep End Points depending on the depth analysis you want. See Types Of Scan.

You will receive a report_id that you use with the Report Retrieval end point to get the full analysis report. If the scan was done synchronously you’ll also get the score and verdict.

Report Retrieval

When you call any of the scan end points you will receive a report_id. You can use this with the Report Retrieval end point to get the full analysis report. If the scan is still in progress you’ll get an in progress response and you’ll need to poll for the scan to complete. You should use an exponential back off to poll for results starting with an immediate poll.

Health Check

The health check api is used to check connectivity and availability of the service and the validity of your api key.

Switch API Key