Bucketscan Docs
Bucketscan Docs
  • Welcome
  • Getting Started
    • Quickstart
      • Using the API
  • API
    • Scans
Powered by GitBook
On this page
  • Authorization
  • Initiate a scan
  • Check the results of a scan
  • Scan results
  1. Getting Started
  2. Quickstart

Using the API

Walkthrough for using the Bucketscan API with your application

PreviousQuickstartNextScans

Last updated 6 months ago

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 . Once logged in, go to the - this is where you can grab your API Key (look at the bottom of the page).

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

Initiate a scan

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"

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"}

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}"

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

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 for the scan's results.

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

Note the returned SCAN_IDvalue, which will be used to .

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

check back later
Authorization
check the result
initiating a scan
Bucketscan account
Bucketscan Dashboard
Your account API key for accessing the Bucketscan API