Version 2.1 Resources

Hello reader, 

The documentation below lists all the REST resources supported by version 2.1 of the Scanii API. For an easier to follow along introduction to our API check out this API's tour. All examples below were made using cURL for its approachability but should translate trivially to any programming language with HTTP support. 

Now without further ado, let's talk about the first resource: files.

Files Resource

Main resource for content processing

GET https://api.scanii.com/v2.1/files/{id}

Retrieves a previously processed file resource

  • Authenticated: Yes
  • Consumes: *
  • Produces: application/json

Example usage:

$ curl -i  -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 https://api.scanii.com/v2.1/files/decad1d51b7981911113eb735739e73f
HTTP/1.1 200 OK
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 29 May 2015 07:18:21 GMT
Vary: Accept-Encoding
X-Runtime: 91ms
X-Scanii-Host-Id: 613a7f69
X-Scanii-Request-Id: a6b34efc-4b87-4371-a32a-15714017b34c
Content-Length: 299
Connection: keep-alive

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

POST https://api.scanii.com/v2.1/files

Submits a file for processing synchronously

  • Authenticated: Yes
  • Consumes: multipart/form-data
  • Produces: application/json
  • Parameters:
    • file: contents of the file to be processed (100MB limit) 
    • callback: optional callback URL
    • metadata[key]: optional metadata argument to be stored with the resource

Example:

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 -F file=@/Users/foo/malware.exe https://api.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: Fri, 29 May 2015 07:18:57 GMT
Location: https://api.scanii.com/v2.1/files/8db1c19c20d3aff74f9b8110e6ba78ad
X-Runtime: 869ms
X-Scanii-Host-Id: 613a7f69
X-Scanii-Request-Id: fbc1d499-714c-4425-9a8d-c7c7f84447f0
Content-Length: 299
Connection: keep-alive

{
  "id" : "8db1c19c20d3aff74f9b8110e6ba78ad",
  "checksum" : "edbb54821bc3f5666be48184a822c3df59392c31",
  "content_length" : 1579562,
  "findings" : [ "av.crdf.malware-generic.2462546599.unofficial" ],
  "creation_date" : "2015-05-29T07:18:58.123Z",
  "content_type" : "application/x-msdownload"
}

POST https://api.scanii.com/v2.1/files/async

Submits a file for processing asynchronously

  • Authenticated: Yes
  • Consumes: multipart/form-data
  • Parameters:
    • file: contents of the file to be processed
    • callback: optional callback URL to be notified once processing is completed
    • metadata[key]: optional metadata argument to be stored with the resource

Example:

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 -F file=@/Users/rafael/Desktop/virus/suba002.exe https://api.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 07:19:34 GMT
Location: https://api.scanii.com/v2.1/files/40e6b94b3c540373cbc768f4cb1f1639
X-Runtime: 955ms
X-Scanii-Host-Id: 613a7f69
X-Scanii-Request-Id: d336e807-5c48-4c62-b886-00270a1af173
Content-Length: 41
Connection: keep-alive

{"id":"40e6b94b3c540373cbc768f4cb1f1639"}

POST https://api.scanii.com/v2.1/files/fetch

Submits a remote file to be processed asynchronously

  • Authenticated: Yes
  • Consumes: application/x-www-form-urlencoded
  • Produces: application/json
  • Parameters:
    • location: URL of the file to be fetched and processed
    • callback: optional callback URL to be notified once processing is completed
    • metadata[key]: optional metadata argument to be stored with the resource

Example:

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 --data-urlencode location='https://acme.com/file1' -d callback=https://acme.com/scanii-webhook https://api.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 07:20:29 GMT
Location: https://api.scanii.com/v2.1/files/7c66c10c5e657d0dac48d69637b8d3e3
X-Runtime: 0ms
X-Scanii-Host-Id: 613a7f69
X-Scanii-Request-Id: ee7f19de-e1bc-4548-8f08-967a237fc954
Content-Length: 41
Connection: keep-alive

{"id":"7c66c10c5e657d0dac48d69637b8d3e3"}

Authentication Tokens

Grants temporary access to API clients

Authentication tokens are to be used in situations in which you want to grant temporary access to Scanii's API to third party or untrusted sources. The canonical example being allowing API calls to happen from a untrusted web browser on your behalf in a secure fashion. Instead of shipping your real API keys to the client's browser, you generate a time bound authentication token. 

Authentication tokens have limits: 

  1. They cannot be used to generate other authentication tokens
  2. They cannot be used to access administrative resources
GET https://api.scanii.com/v2.1/auth/tokens/{id}

Retrieves a previously created token

  • Authenticated: Yes
  • Consumes: *
  • Produces: application/json

Example:

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 https://api.scanii.com/v2.1/auth/tokens/d8a718b58ad883dbb9b01c5a9083e230
HTTP/1.1 200 OK
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 29 May 2015 07:12:28 GMT
X-Runtime: 0ms
X-Scanii-Host-Id: 613a7f69
X-Scanii-Request-Id: 46dfa9e6-7a04-4f7a-bc75-0b7d386148b7
Content-Length: 145
Connection: keep-alive
{
  "id" : "d8a718b58ad883dbb9b01c5a9083e230",
  "creation_date" : "2015-05-29T07:08:00.348Z",
  "expiration_date" : "2015-05-29T07:08:20.348Z"
}

POST https://api.scanii.com/v2.1/auth/tokens/

Creates a temporary authentication token

  • Authenticated: Yes
  • Consumes: application/x-www-form-urlencoded
  • Produces: application/json
  • Parameters:
    • timeout: number of seconds this token should be valid for (optional defaults to 300 seconds)

Example:

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:12345678-d timeout=20 https://api.scanii.com/v2.1/auth/tokens
HTTP/1.1 201 Created
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 29 May 2015 07:13:16 GMT
Location: https://api.scanii.com/v2.1/auth/tokens/fdbce076ae2ad0b86f07fe3eccb6bbbc
X-Runtime: 1ms
X-Scanii-Host-Id: 613a7f69
X-Scanii-Request-Id: 37318898-b374-46f5-b006-4515d17f24de
Content-Length: 145
Connection: keep-alive

{
  "id" : "fdbce076ae2ad0b86f07fe3eccb6bbbc",
  "creation_date" : "2015-05-29T07:13:16.902Z",
  "expiration_date" : "2015-05-29T07:13:36.902Z"
}
DELETE https://api.scanii.com/v2.1/auth/tokens/{id}

Deletes a temporary authentication token

  • Authenticated: Yes
  • Consumes: *
  • Produces: application/json

Example:

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 -X DELETE  https://api.scanii.com/v2.1/auth/tokens/fdbce076ae2ad0b86f07fe3eccb6bbbc
HTTP/1.1 204 No Content
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: *
Connection: keep-alive

Ping

Test resource, you ping, we pong.

GET https://api.scanii.com/v2.1/ping

  • Authenticated: Yes
  • Consumes: *
  • Produces: application/json

Example:

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 https://api.scanii.com/v2.1/ping
HTTP/1.1 200 OK
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: *
Content-Type: application/json
Content-Length: 70
Connection: keep-alive

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

Account

Retrieves account related information

GET https://api.scanii.com/v2.1/account.json

Retrieves account related information 

  • Authenticated: Yes
  • Consumes: *
  • Produces: application/json

Example:

$ curl -i -u 8eb05c68f386421db2dd4929fc4f77ad:12345678 https://api.scanii.com/v2.1/account.json
HTTP/2 200 
content-type: application/json
content-length: 4517
Connection: keep-alive

{
  "name" : "ACME INC",
  "balance" : 777,
  "starting_balance" : 500,
  "billing_email" : "admin@uvasoftware.com",
  "subscription" : "Plus monthly",
  "creation_date" : "2012-03-25T23:18:10Z",
  "modification_date" : "2018-09-16T18:42:04Z",
  "users" : {
    "bob@acme.com" : {
      "creation_date" : "2010-11-29T02:37:58Z",
      "last_login_date" : "2018-09-05T01:58:51Z"
    }
  },
  "keys" : {
    "46f034dd034741bdac75415f2ffa7b2a" : {
      "active" : true,
      "detection_categories_enabled" : [ "NSFW_LANGUAGE", "MALWARE", "NSFW_IMAGE" ],
      "last_seen_date" : "2018-05-12T21:01:53Z",
      "creation_date" : "2012-01-10T14:12:28Z",
      "tags" : [ "general", "production" ]
    },
    "cb8b66725c5b4f72b225345357a3bce2" : {
      "active" : true,
      "detection_categories_enabled" : [ "NSFW_LANGUAGE", "MALWARE", "NSFW_IMAGE" ],
      "last_seen_date" : "2018-05-13T08:05:35Z",
      "creation_date" : "2012-01-27T09:33:27Z",
      "tags" : [ "lambda" ]
    }
  }
}
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

Related Articles