# Using the API

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](https://staging.bucketscan.com/sign-up). Once logged in, go to the [Bucketscan Dashboard](https://staging.bucketscan.com/dashboard) - this is where you can grab your API Key (look at the bottom of the page).

<figure><img src="https://2152520714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYHk6lIrNdlgfiZg3Xso6%2Fuploads%2FMcErMk7tEMrIdZKCI5am%2FAPI%20Key.png?alt=media&#x26;token=82edd696-970e-48cc-8b64-d79864bf8365" alt=""><figcaption><p>Your account API key for accessing the Bucketscan API</p></figcaption></figure>

{% hint style="info" %}
Click the "Copy to Clipboard" button to the right of the text box
{% endhint %}

## 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](#check-the-results-of-a-scan) for the scan's results.

```sh
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"
```

{% hint style="info" %}
Replace the `{insert-your-api-key-here}`token with the API Key you copied in the [Authorization](#authorization) step above.
{% endhint %}

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

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

Note the returned `SCAN_ID`value, which will be used to [check the result](#check-the-results-of-a-scan).

## Check the results of a scan

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

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

{% hint style="info" %}
Be sure to replace the `{scanId}`token with the `SCAN_ID`value you noted when [initiating a scan](#initiate-a-scan).
{% endhint %}

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

```sh
{"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              |