Overview

This describes usage of scanii.com's API version 2.0. If you have any questions please contact support here.

TLDR: You can find a list of all resources here

The examples below are utilizing the cURL command line library and should be easily translated into any programming language.

Endpoints

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

For sake of this overview we will utilize api.scanii.com as the domain name since it's the simplest to use - you can find out more about it here.

Basics

All access happens over HTTPS using the https://api.scanii.com domain name and the /v2.0 base path. All responses utilize JSON and all dates are in the ISO8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, here's a sample response from our Ping resource:

$ curl -i  -u 8eb05c68f386421db2dd4929fc4f77ad:123456 https://api.scanii.com/v2.0/ping
HTTP/1.1 200 OK
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Wed, 27 May 2015 16:01:23 GMT
X-Runtime: 0ms
X-Scanii-Host-Id: 99408e47
X-Scanii-Request-Id: 11c16335-c532-4a72-b8c9-ef7581678daf
Content-Length: 70
Connection: keep-alive

{
  "message" : "pong",
  "key" : "8eb05c68f386421db2dd4929fc4f77ad"
}

Authentication

All of our resources utilize HTTP basic authentication to unique identify clients and since all interactions happen over TLS credentials are always safely transmitted.

$ curl -i  -u 8eb05c68f386421db2dd4929fc4f77ad:123456 https://api.scanii.com/v2.0/ping

In the example above, 8eb05c68f386421db2dd4929fc4f77ad:123456 represent the api key (8eb05c68f386421db2dd4929fc4f77ad) and its secret (123456). The API credentials are created (and managed) by the user using Scanii's web interface here https://scanii.com/account/settings/keys.

HTTP Response codes

Scanii strives to adhere to common REST principles for its responses whenever practical and retain consistent response codes across its resources.

Here are the common HTTP ERROR response codes across our resources:

Success codes will vary by resource but will always be in the 2XX range.

HTTP Response headers

Scanii utilizes HTTP response headers to provide metadata about the API response and its resources. For example:

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:123456789 -F file=@/tmp/foo.exe https://api.scanii.com/v2.0/files
HTTP/1.1 201 Created
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 29 May 2015 05:33:30 GMT
Location: https://api.scanii.com/v2.0/files/9a1880dcb5e31d47c11be8ab243078ab
X-Runtime: 4164ms
X-Scanii-Host-Id: 613a7f69
X-Scanii-Request-Id: 0cb43907-684a-4439-a164-3e40edde1f48
Content-Length: 299
Connection: keep-alive

{
  "id" : "9a1880dcb5e31d47c11be8ab243078ab",
  "checksum" : "edbb54821bc3f5666be48184a822c3df59392c31",
  "content_length" : 1579562,
  "findings" : [ "av.crdf.malware-generic.2462546599.unofficial" ],
  "creation_date" : "2015-05-29T05:33:34.390Z",
  "content_type" : "application/x-msdownload"
} 

Cross Origin Resource Sharing - CORS

Along with the HTTP headers listed above, our APIs also support Cross Origin Resource Sharing (http://en.wikipedia.org/wiki/Cross-origin_resource_sharing) for AJAX requests from any resource. Here's what a sample request from a browser hitting our endpoint would look like:

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:123456789 -H "Origin: http://example.com"  https://api.scanii.com/v2.0/ping
HTTP/1.1 200 OK
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 29 May 2015 05:38:57 GMT
X-Runtime: 0ms
X-Scanii-Host-Id: 613a7f69
X-Scanii-Request-Id: 68177aeb-0648-4946-acaa-8b4de08bbb6b
Content-Length: 70
Connection: keep-alive

{
  "message" : "pong",
  "key" : "8eb05c68f386421db2dd4929fc4f77ad"
}

API Tour

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.scanii.com/v2.0/ping
{
    "message" : "pong",
    "key" : "8eb05c68f386421db2dd4929fc4f77ad"
}

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 file=@/Users/rafael/virus.exe https://api.scanii.com/v2.0/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: Fri, 29 May 2015 05:52:28 GMT
Location: https://api.scanii.com/v2.0/files/2914d80c2bf5f3818cbc3ed3b833285c
X-Runtime: 1030ms
X-Scanii-Host-Id: 613a7f69
X-Scanii-Request-Id: 57f5e0d3-bfb7-4977-b9b9-ebdd2f0a3748
Content-Length: 299
Connection: keep-alive

{
  "id" : "2914d80c2bf5f3818cbc3ed3b833285c",
  "checksum" : "edbb54821bc3f5666be48184a822c3df59392c31",
  "content_length" : 1579562,
  "findings" : [ "av.crdf.malware-generic.2462546599.unofficial" ],
  "creation_date" : "2015-05-29T05:52:29.067Z",
  "content_type" : "application/x-msdownload"
}

Well, looks like Scanii found something in that file, "findings" is always a list of everything meaningful our engine encountered while processing that file, in this case our anti virus engine found the "av.crdf.malware-generic.2462546599.unofficial" malware.

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.scanii.com/v2.0/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.scanii.com/v2.0/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.scanii.com/v2.0/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"
}

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 -d location="https%3A%2F%2Fscanii.s3.amazonaws.com%2Feicarcom2.zip%3FAWSAccessKeyId%3DAKIAJNN3CBMBGCMQDU4A%26Expires%3D1432966418%26Signature%3DQjxrlqDq587fSDkhqfI5Kt2LVN8%253D" -d callback=https://acme.com/scanii-webhook https://api.scanii.com/v2.0/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.scanii.com/v2.0/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 an urlencoded location to be fetched, processed and eventually have the results send to a callback URL.

Congratulations, you have reached the end of our overview, now you should dig deeper into our Resources

Last updated on 05/25/2015.