Using the API

Walkthrough for using the Bucketscan API with your application

Bucketscan has an API for it's customers to use. This allows you to directly integrate the turn key scanning solution to any application or architecture, regardless of how you have hosted. You can even make use of it locally!

Authorization

To use the API, you must have a valid API token. So before you start, make sure you've signed up for a Bucketscan account. Once logged in, go to the Bucketscan Dashboard - this is where you can grab your API Key (look at the bottom of the page).

Your account API key for accessing the Bucketscan API

Click the "Copy to Clipboard" button to the right of the text box

Initiate a scan

Now that you've got an API key, you can write a request to upload a file to the Bucketscan API. This will automatically trigger a virus scan in the background. This is an asynchronous process, so you must check back later for the scan's results.

curl -XPOST https://bucketscan.com/api/v1/scans/initiate \
  -H "x-api-key: {insert-your-api-key-here}" \
  -F "file=@relative/path/to/file.txt"

Replace the {insert-your-api-key-here}token with the API Key you copied in the Authorization step above.

Assuming the call is successful, you will receive an HTTP JSON response that contains the Id of the process that has been triggered.

{"status":200,"message":"Successfully uploaded file.txt!","scanId":"SCAN_ID"}

Note the returned SCAN_IDvalue, which will be used to check the result.

Check the results of a scan

To check the results of a scan, you can use a simple GETrequest, as seen below.

curl https://bucketscan.com/api/v1/scans/{scanId} \
  -H "x-api-key: {insert-your-api-key-here}"

Be sure to replace the {scanId}token with the SCAN_IDvalue you noted when initiating a scan.

This will return an HTTP JSON response detailing the current result of the scan.

{"status":200,"message":"OK","scanId":"SCAN_ID","scanResult":"pending"}

Scan results

Below is a table detailing the different scan results with descriptions of what each means.

Name	Description	Is an end result
pending	Indicates that a scan has been started, but has not yet completed	No
failed	Shows that something went wrong during the scan. Contact Support for help	Yes
completed_clean	Represents a scan that has completed successfully, and no malicious content has been found within the file	Yes
completed_infected	Represents a scan that has completed successfully, but that malicious content has been found within the file	Yes