Version 1.0

Background

Scanii.com was developed with the following goals in mind:

Simplicity (we’re purposely no-frills)
HTTP based and RESTFul
JSON based - but we also support other markups including XML and YAML
Command line friendly (Yes, it’s a requirement to be “curl” testable)

Authentication

Scanii uses basic HTTP authentication via a simple key (a 32 digit hash) and a secret password. As the name implies, it’s intended to be secret and assigned to a single account only (since that’s the way we keep track of your requests). HTTP basic auth was selected since it seems to strike a balance between usability and function.

Please note that our API uses HTTPS so that neither your key/secret combination nor your data is transmitted unencrypted.

Making a request

Basic interaction between a client that wants to have file “myword.doc” scanned looks like this:

Client sends a HTTP POST request with the contents of myword.doc to https://scanii.com/api/scan/ using HTTP basic auth with its API key as the username and the API secret as the password
Scanii process the file and sends back a HTTP response with status 200 and a JSON document as the page content. The JSON document will say if the file is infected or if an error occurred and why

The JSON response

Success (file was successfully scanned and no viruses were found):

{ “status”: “clean” }

File is infected:

{ “status”: “infected” , “virus”: [ “virus1”, “virus2”] }

Please note that “virus” is a json array of strings containing the names of the viruses found

Error (something exceptional happened):

{ “status”: “oops”, “reason”: “Task failed” }

Please note that the variable “reason” will try to give you an explanation of what happened

The sample responses above are abbreviated, in actuality some optional information is sent back to help you with troubleshooting, for example:

{ “status”: “clean”, “checksum”: “2e1050a898d25b4be016c5c29ae4df52387834b2”, “request_id”: “282a6f54-bdc3-11df-9335-d49a20d0dc30” }

where:

checksum - is the checksum we calculated for the content you sent to us.
request_id - a unique identifier for your request, send us this information when opening a support ticket

HTTP response codes

Scanii utilizes both JSON and HTTP response codes to convey information back to the API consumer. Currently the following HTTP response codes are meaningful:

200 - success (this is always accompanied by a JSON document)
400 - bad request
401 - Invalid creds (your SECRET and KEY combination is not valid)
406 - Not Acceptable - request is understood but not allowed to be executed
413 - Request Entity Too Large - if you exceed the maximum allowed POST size
500 - Error - please let us know if you see this
502 - Bad Gateway - scanii is down or being upgraded

HTTP response headers

To assist with troubleshooting, scanii will always return the following HTTP Headers:

X-Runtime: The amount of time (in milli seconds) it took for scanii to process your request. This is the processing time only and does not include the time waiting to send and/or receive data

Optional arguments

Things to keep in mind:

All parameters must be encoded as UTF-8 and urlencoded

Response Formatters

Scanii offers the ability to format its response to a few different markup languages. This is done by passing the format parameter to any of the API resources, for example:

$ curl -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 http://scanii.com/api/scan/?format=xml
<response>
<status>oops</status>
<reason>good try but this api requires a http POST request</reason>
</response><br>

Valid formats include:

xml
yaml - in beta
json - default

Please note that JSON is the fastest since it is how messages inside scanii are natively encoded.

Response code suppression:

For clients with limited ability to handle anything but a 200 HTTP response code, you can use the suppress_response_codes argument to tell scanii to always always return a response code of 200, even for errors. For example:

$ curl -I -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 http://scanii.com/api/scan/?suppress_response_codes

HTTP/1.0 200 OK

Date: Sat, 11 Sep 2010 17:14:23 GMT

Server: WSGIServer/0.1 Python/2.6.5

Vary: Cookie

X-Runtime: 10.01ms

Content-Type: application/javascript

{“status”: “clean”, “checksum”: “2e1050a898d25b4be016c5c29ae4df52387834b2”, “request_id”: “05d75318-bdc8-11df-9335-d49a20d0dc30”}

API Reference

⚠️ Please note that this API version is deprecated and listed here for backwards compatibility only.

Scanning a file:

POST https://scanii.com/api/scan/

Expects contents to be scanned to be sent as the body of the POST request
Returns JSON response with status

example:

$ curl -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 --data-binary @/tmp/word.doc https://scanii.com/api/scan/

{"status": "clean", "checksum": "54e20109cab27606e56fc1829e1ad996572eee20", "request_id": "69c8f428-f186-11df-8c04-d49a20d0dc30"}

Scanning a file asynchronously:

POST: https: https://scanii.com/api/scan/async

Expects contents to be scanned to be sent as the body of the POST request
Returns JSON response with status

example:

$ curl -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 --data-binary @/tmp/word.doc https://scanii.com/api/scan/async/

{"status": "pending", "checksum": "54e20109cab27606e56fc1829e1ad996572eee20", "request_id": "ae29f5f8-f186-11df-ba82-d49a20d0dc30"}

Go Fetch mode:

POST https://scanii.com/api/scan/fetch

Expects the following arguments:
- url: the location of the content you would like us to fetch and virus scan
- callback: the location you would like us to “ping” via a simple GET request once we’re done - optional
- post_callback: the location you would like us to POST the scan results once we’re done - optional
Returns JSON response with status
No content size limit

example:

$ curl -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 -d 'url=http://www.eicar.org/download/eicarcom2.zip' -d 'callback=http://example.com/pingback/' https://scanii.com/api/scan/fetch/

{"status": "pending", "checksum": "b440f1155cd7cf44ee7a9b80b5f5697c9bcbd6cd", "request_id": "bf242194-3e49-11e0-b52c-d49a20d0dc30"}

example using post_callback instead:

$ curl -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 -d 'url=http://www.eicar.org/download/eicarcom2.zip' -d 'post_callback=http://example.com/pingback/' <a href="https://scanii.com/api/scan/fetch/">https://scanii.com/api/scan/fetch/</a>

{"status": "pending", "checksum": "b440f1155cd7cf44ee7a9b80b5f5697c9bcbd6cd", "request_id": "bf242194-3e49-11e0-b52c-d49a20d0dc30"}

Checking the status of a request:

GET http://scanii.com/api/scan/status/{request_id}

Returns JSON response with request status or a 404 if the request_id is invalid

example:

$ curl -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 <a href="https://scanii.com/api/scan/status/2c3fd620-be2b-11df-8977-d49a20d0dc30">https://scanii.com/api/scan/status/2c3fd620-be2b-11df-8977-d49a20d0dc30</a>

{"status": "pending", "checksum": "91b5dfaad5790e4a4a32b010c92fa532211b199f", "request_id": "2c3fd620-be2b-11df-8977-d49a20d0dc30"}