Scanii API basics


scanii was developed with the following goals in mind:

Before using the API, make sure register with for your own API key and secret. For help with registering, please check out our Getting Started guide



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:

  1. Client sends a HTTP POST request with the contents of myword.doc to using HTTP basic auth with its API key as the username and the API secret as the password
  2. 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" }


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:

HTTP response headers

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

Optional arguments

Things to keep in mind:

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

<?xml version="1.0" encoding="UTF-8" ?>
 <reason>good try but this api requires a http POST request</reason>

Valid formats include:

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


home | sign in | faq | docs | support
©2015 Uva Software, LLC