Version 1.0

Background 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)


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” }


  • 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



<reason>good try but this api requires a http POST request</reason>


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/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:


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


$ curl -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 --data-binary @/tmp/word.doc

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

Scanning a file asynchronously:

POST: https:

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


$ curl -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 --data-binary @/tmp/word.doc

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

Go Fetch mode:


  • 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


$ curl -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 -d 'url=' -d 'callback='

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

example using post_callback instead:

$ curl -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 -d 'url=' -d 'post_callback=' <a href=""></a>

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

Checking the status of a request:


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


$ curl -u 69b4ae1ba2f34798b2e362548f0f69c9:12345 <a href=""></a>

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

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us