Skip to content API Overview

The API allows you to programmatically access all your devices, venues, configs, etc. in the Cloud.

You can change beacon properties, assign devices to venues or managers, and perform a lot other operations. The REST API is aimed at developers who want to manage all their Cloud interactions using standalone or web applications.

The Kio Cloud is an example of an application that leverage the API to provide easy access to devices management, among other things.

API reference

This document shows you how to prepare a valid API request. For a list of all available resources please visit the API version 10 Reference.

Accessing the REST API

When you received your first shipment from and created your account, all your ordered devices, beacons, Cloud Beacons etc, were added to your account with their shipped configurations. This account is your company's SUPERUSER manager account.

You can access your cloud account using the Cloud, or programmatically using the REST API resources detailed in this guide.

Authentication & Security

All authentications & authorizations in the API are done by sending a secret API key in the Api-Key HTTP header.

The key is a unique string assigned to each manager. The API key for your SUPERUSER manager has access to all resources for your Company.

You can find the API Key in the Kio Cloud.

This API key is in effect your password to access your beacons and other devices via the API. It's important you keep this private and use HTTPS to access the REST API. resource URL

All resources can be accessed over HTTPS from the domain -


You cannot access this domain without supplying the appropriate HTTP headers - you will receive a 401 - requires authentication response if you try.

HTTP Headers

Header Value
Accept 1 application/;version=10
Api-Key your personalized API key
Content-Type 2 application/x-www-form-urlencoded
User-Agent 3 Client software identifier

1 Accept header is required. Version parameter is optional but strongly recommended
2 Only required for POST requests
3 We strongly suggest that you supply a value for the User-Agent in the header.

Accept header version parameter

The version parameter is optional but we strongly recommend that you supply it. If it is not specified, you will access the latest stable release by default.

POST parameters

POST parameters should be URL-encoded in the request body, like in the example below:

curl -X "POST" "" \
     -H 'Api-Key: yourSuperSecretAPIKey' \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     -H 'Accept: application/;version=10' \
     --data-urlencode "major=123" \
     --data-urlencode "uniqueId=098C" \
     --data-urlencode "deviceType=beacon"


Most resources will return data in JSON format, and exceptions to this rule are indicated accordingly in the API Reference.

Status codes

Our API uses standard HTTP status codes for communicating with the client.


Status code Description
200 Request has been valid and successful
201 Entity has been created successfully


Status code Description
303 Request has been valid, but needed to be redirected elsewhere


Status code Description
400 Request contains invalid values or is in invalid format
401 Unauthorized access. Most likely Api-Key hasn't been sent
403 Forbidden. Tried to access a resource that isn't theirs
404 Resource not found
409 Conflict. Will return information as to the cause
415 Version or Mediatype not found
422 Parameters validation error

Your can find more about HTTP protocol in the RFC 2616 document.

Caching REST API calls

The Proximity REST API supports entity tag (ETag) caching.

When you submit a successful GET method an ETag value will be returned in the HTTP response header.

In subsequent requests for the same resource, you can add a If-None-Match header field and supply the ETag value that you received in the last call. If the results have not changed since your last call, then you will receive an HTTP response code of 304 (Not Modified) and no JSON will be returned.

Let's look at an example GET to retrieve a list of all our Triggers:

GET /trigger

We'll get the normal http response 200 successful. If we inspect the HTTP headers, you'll see something like the following:

Access-Control-Allow-Headers -> Content-Type
Access-Control-Allow-Methods -> GET, POST, DELETE, PUT
Access-Control-Allow-Origin -> *
Connection -> keep-alive
Content-Length -> 2643
Content-Type -> application/;version=8;charset=UTF-8
Date -> Tue, 24 Feb 2015 08:26:36 GMT
ETag -> "05915ba01193dd4cf307a308a15330893"
Server -> Apache-Coyote/1.1

And our full JSON response containing a list of our Triggers:

  "triggers": [
      "throttle": 30,
      "activityId": [
      "executor": "CLOUD",
      "name": "test123",
      "context": {
        "sourceId": "7ed6de42ca37fc602b310cc6bbdbcfdc",
        "proximity": "NEAR",
        "proximityUuid": "30183e7e-330c-4678-84da-e2f83744f0c3"
      "id": "48148fc4-d674-4787-a83c-3a50e530b76c",
      "type": "BEACON_DETECTED"
  "searchMeta": {
    "filter": "",
    "startIndex": 0,
    "maxResult": 50,
    "prevResults": "",
    "count": null,
    "orderBy": "created",
    "nextResults": "",
    "queryType": "NORMAL",
    "order": "ASC"

The http header contains the ETag value for our call:

ETag -> "05915ba01193dd4cf307a308a15330893" 

If we repeat the same call, adding a If-None-Match header with the ETag value returned by the last call:

If-None-Match: "05915ba01193dd4cf307a308a15330893"

Then we will receive a full response as in our first call only if the list of devices has changed in any way. But if the response is unchanged, we will simply receive an HTTP response of 304 not modified and no JSON response will be returned.

Nested parameters

Some API resources are represented not as a simple, flat list of parameters, but instead they contain nested objects to encapsulate related parameters. A good example is the Activity with the context parameter.

Since API requires URL-encoded parameters for POST calls, e.g. creating a new Activity requires a proper encoding of these nested objects. In general, each value that you want to provide has to be provided separately, with the full path to the parameter separated with dots (.).

Example (highlighted lines):

curl -X "POST" ""
     -H 'Api-Key: yourSuperSecretAPIKey'
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8'
     -H 'Accept: application/;version=10'
     --data-urlencode "name=Test1"
     --data-urlencode "type=SEND_HTTP_REQUEST"
     --data-urlencode "context.httpMethod=POST"
     --data-urlencode "context.params.customParam=xxxxxxxxxxxx"
     --data-urlencode "context.headers.content-type=application/json"
     --data-urlencode "context.url="