API Version 2.1

This describes usage of scanii.com’s API version v2.1. If you have any questions please contact support.

Notable changes from version 2.0

• File resource now accepts a metadata argument for arbitrary key/value pairs to be stored alongside the resource
• Added a beta account lookup resource

🌎 Endpoints

Scanii is a global content processing service with availability in the following regions/domains:

• Virginia / USA ➞ https://api-us1.scanii.com
• Dublin / Ireland ➞ https://api-eu1.scanii.com
• London / United Kingdom ➞ https://api-eu2.scanii.com
• Sydney / Australia ➞ https://api-ap1.scanii.com
• Singapore / Singapore ➞ https://api-ap2.scanii.com

For sake of this overview we will utilize api-us1.scanii.com as the domain name since it’s the simplest to use.

👉 Specification

We publish API specs in the form of OpenAPI descriptors because they are both human readable and machine parsable allowing for quick client generation.

Now, without further ado, let's tour the API.

🌍 API tour

Checking your API credentials

For the examples below we will assume that the user has a valid API key, and we will navigate through a few common API calls using the cURL command line tool. Further information on using cURL

Let’s start with a simple Ping call that tells us that our API key is ready for use:

$ curl -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 https://api-us1.scanii.com/v2.1/ping
{
    "message" : "pong",
    "key" : "8eb05c68f386421db2dd4929fc4f77ad"
}

Analyzing files synchronously

Looks good, now let’s try to send a file for processing synchronously (that is, the client will wait until the processing is completed):

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 -F metadata[filename]=suba002.exe -F file=@suba002.exe https://api-us1.scanii.com/v2.1/files
HTTP/1.1 100 Continue
HTTP/1.1 201 Created
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Sat, 12 Dec 2015 17:34:10 GMT
Location: https://api-us1.scanii.com/v2.1/files/4d323e37433a76d59a78a97d5265ad67
X-Runtime: 1245ms
X-Scanii-Host-Id: 86ddeebc
X-Scanii-Request-Id: ec9a8d74-823b-457f-bdf8-0836c47f7534
Content-Length: 333
Connection: keep-alive
{
  "id" : "4d323e37433a76d59a78a97d5265ad67",
  "checksum" : "edbb54821bc3f5666be48184a822c3df59392c31",
  "content_length" : 1579562,
  "findings" : [ "av.win.trojan.agent-948155" ],
  "creation_date" : "2015-12-12T17:34:12.031Z",
  "content_type" : "application/x-msdownload",
  "metadata" : {
    "filename" : "suba002.exe"
  }
}

Scanii has discovered something in the file. "Findings" refers to a comprehensive list of significant encounters our engine encountered during the file's processing. In this instance, our antivirus engine detected the presence of the "av.win.trojan.agent-948155" malware..

In the aforementioned example, we utilized Scanii's custom metadata feature to store the file name along with the processed content. When we send arguments in the format metadata[key]=value, they are automatically saved with the resource. This serves as an excellent location to store your business logic, such as the internal ID of the content or the name of the web server (or application) responsible for generating the request.

Analyzing files asynchronously

Now let’s say that you would like to batch process lots of files at once and be notified as processing completes, here’s an example of using our asynchronous callback endpoint:

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 -F file=@/Users/rafael/virus.exe -F callback=https://acme.com/scanii-webhook   https://api-us1.scanii.com/v2.1/files/async
HTTP/1.1 100 Continue
HTTP/1.1 202 Accepted
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 29 May 2015 06:00:36 GMT
Location: https://api-us1.scanii.com/v2.1/files/decad1d51b7981911113eb735739e73f
X-Runtime: 1113ms
X-Scanii-Host-Id: 613a7f69
X-Scanii-Request-Id: b12f1da6-f76b-4489-8e47-443c3ffc91ea
Content-Length: 41
Connection: keep-alive
{"id":"decad1d51b7981911113eb735739e73f"}

In the example above our API client will return immediately (and not wait for the content processing to finish) and notify via a HTTP POST request the endpoint https://acme.com/scanii-webhook once completed. The payload of the callback will match the usual JSON response payload as below:

{
  "id" : "decad1d51b7981911113eb735739e73f",
  "checksum" : "edbb54821bc3f5666be48184a822c3df59392c31",
  "content_length" : 1579562,
  "findings" : [ "av.crdf.malware-generic.2462546599.unofficial" ],
  "creation_date" : "2015-05-29T06:00:37.772Z",
  "content_type" : "application/x-msdownload"
}

Also notice that the all content processed has a unique persistent and retrievable locator:

$ curl -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 https://api-us1.scanii.com/v2.1/files/decad1d51b7981911113eb735739e73f
{
  "id" : "decad1d51b7981911113eb735739e73f",
  "checksum" : "edbb54821bc3f5666be48184a822c3df59392c31",
  "content_length" : 1579562,
  "findings" : [ "av.crdf.malware-generic.2462546599.unofficial" ],
  "creation_date" : "2015-05-29T06:00:37.772Z",
  "content_type" : "application/x-msdownload"
}

Analyze files stored remotely

Lastly, let’s have Scanii fetch the content to be processed directly from a third party resource (in this case private Amazon S3 object that we will access using query string authentication):

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 --data-urlencode location='https://scanii.s3.amazonaws.com/eicarcom2.zip?AWSAccessKeyId=AKIAJNN3CBMBGCMQDU4A&Expires=1432966418&Signature=QjxrlqDq587fSDkhqfI5Kt2LVN8%3D' -d callback=https://acme.com/scanii-webhook https://api-us1.scanii.com/v2.1/files/fetch
HTTP/1.1 202 Accepted
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 29 May 2015 06:19:32 GMT
Location: https://api-us1.scanii.com/v2.1/files/425700a659d88a3e4fc8551f2da1eed1
X-Runtime: 0ms
X-Scanii-Host-Id: 613a7f69
X-Scanii-Request-Id: 538547c8-37be-47b3-9333-ca489eb68bd5
Content-Length: 41
Connection: keep-alive
{"id":"425700a659d88a3e4fc8551f2da1eed1"}

In the example above we pass the location to be fetched, processed and eventually have the results send to a callback URL.

Using Temporary Authentication Tokens

Authentication tokens are temporary use API credentials aimed at making it easier to do client side processing, with them you can generate a token you can send to the insecure client to submit content directly to Scanii for analysis.

Here’s how you create one:

curl -i -X POST -u a4d6b8a87ddd09c2647d97741bc380c4:12345678 -d timeout=30 https://api-us1.scanii.com/v2.1/auth/tokens
HTTP/2 201 
date: Mon, 21 Sep 2020 11:48:34 GMT
content-type: application/json
content-length: 151
location: https://api-us1.scanii.com/v2.1/auth/tokens/6602a804f7232817676146592de3a667
x-runtime: 112ms
x-scanii-host-id: 589e5e35
access-control-allow-origin: *
access-control-allow-headers: Authorization
x-scanii-request-id: 83ec1fda-6e13-4520-96d8-ed37ecf40269
{
  "id" : "6602a804f7232817676146592de3a667",
  "creation_date" : "2020-09-21T11:48:34.824146Z",
  "expiration_date" : "2020-09-21T11:49:04.824146Z"
}

In the example above we created a new temporary authentication token with a 30-second timeout, and we’re going to use it to authentication a content analysis request. Please note that we’re using the temporary auth token for the authentication username and leaving the password blank:

curl -i -X POST -u 6602a804f7232817676146592de3a667: -F file=@contents.txt  https://api-us1.scanii.com/v2.1/files
HTTP/2 201 
date: Mon, 21 Sep 2020 11:52:31 GMT
content-type: application/json
content-length: 255
location: https://api-us1.scanii.com/v2.1/files/fb7b800970fdaaac1a87d2b39bb5fb14
x-amzn-trace-id: Root=1-5f6893ff-a0676c31f9eecd8c82fc52e2;
x-runtime: 79ms
x-scanii-host-id: 4aad24e4
access-control-allow-origin: *
access-control-allow-headers: Authorization
x-scanii-request-id: 00661172-7c62-4d57-8fd6-5248ee880cf9
{
  "id" : "fb7b800970fdaaac1a87d2b39bb5fb14",
  "checksum" : "22596363b3de40b06f981fb85d82312e8c0ed511",
  "content_length" : 12,
  "findings" : [ ],
  "creation_date" : "2020-09-21T11:52:31.600929Z",
  "content_type" : "text/plain",
  "metadata" : { }
}

Congratulations, you have reached the end of our overview 👏

Feeling stuck? Just email us at support@uvasoftware.com and we will help you get unstuck!