Connio

The Connio API Developer Hub

Welcome to the Connio API developer hub. You'll find comprehensive guides and documentation to help you start working with Connio API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

API Basics

 

The Connio platform includes two sets of APIs: Admin Services API and Data Services API. While Admin Services API is used to manage your Connio account, and wire your IoT solutions, Data Services API is used to exchange data among devices, api clients and the Connio platform.

All API access is through the api.connio.com domain using HTTPS. Hence all URLs referenced in the documentation have the following base: https://api.connio.com/v3.

We use entity nouns as labels for the resources:

  • /devices
  • /devices/:id

The first URL is for a resource collection; the second is for an instance resource in the collection.

All Connio entities have both an id, a globally unique identifier, and a given name, a contextually unique identifier. All instance resources can be accessed either by their id or their contextual name within the proper context as shown below:

https://api.connio.com/v3/apps/_app_223341111738008347
https://api.connio.com/v3/apps/default

Note that sub entity names are unique only under their owner's context. This requires you to provide full path when querying them. For example, if you like to access to a property called temperature defined under a device profile called temperature_sensor, you should provide the following path:

https://api.connio.com/v3/deviceprofiles/temperature_sensor/properties/temperature

This referencing scheme is required since property name temperature is only unique within the temperature_sensor device profile context. Alternatively you would access it by its id as shown below:

https://api.connio.com/v3/properties/_prp_123541189738008332

Usage of {ref} Placeholder

As stated earlier, except for sub entities (i.e. properties, methods, alerts etc..), id and name identifiers can be used interchangeably within almost all API paths to reference resource instances. Note that we will use {ref} throughout this document as a placeholder to remind the reader that both id or name identifiers can be used interchangeably.

We operate on the resources with HTTP verbs. Our HTTP verbs are POST, GET, PUT, and DELETE. You can think of them as mapping to the acronym CRUD (Create-Retrieve-Update-Delete).

Creating a resource instance involves performing an HTTP POST to a resource collection URL. Updating a resource instance involves performing an HTTP PUT to its URL. We stay true to the spirit of POST & PUT semantics. Use PUT if you know the URL of the resource, or if you are the authority to assign its URL.

Note that all delete operations except batch operations return the following object with a success code (200). The number of items deleted can be 0 if nothing found to delete.

{ 
  "nrOfItems": <number of items deleted> 
}

In some rare occasions we use verbs as resource labels to represent pure actions. Use POST to operate on them.

All requests to the API require you to authenticate using basic authentication.

All data is sent and received as JSON. Every string passed to and from the Connio API must be UTF-8 encoded.

All timestamps values are stored in UTC with milliseconds precision. Transferred timestamps are expected to be formatted according to ISO 8601 (e.g. 2015-08-24T10:53:32.674-0800)

Since some lightweight HTTP clients do not support methods PUT and DELETE, you can simulate them via POST by appending the query string parameter _method (underscore method) to a resource URL. Valid values for this parameter are PUT and DELETE.

Errors are returned using standard HTTP error code syntax. Any additional info is included in the response body in JSON format.

API calls are subject to rate limiting. Exceeding any rate limits will result in all endpoints returning a status code of 429 (Too Many Requests).

If you think you can help us improve our API or documentation, drop us a line at feedback@connio.com, or make a suggestion on this site (see Suggest Edits button on far right hand side).

Suggest Edits

Authentication

 

When you first signup with Connio, the system automatically creates a Master account and an admin user with the sign-in credentials consisting of your email address and your password as specified at the signup. As an admin user, you get the privileges to fully manage this newly created account.

Every user on the system gets an automatically generated API access key. API keys represent an API Key Id and Secret pair. You can use access keys to make secure REST requests to any Connio API.

API access keys uniquely identifies an entity (i.e. user, device, or api client) that is allowed to make REST requests within an account context. All requests to Connio API require the caller to authenticate using HTTP Basic Auth to convey his identity. You must provide the API key id as basic auth username, and Secret as password. For example if you are accessing the Connio API via cURL, the following command would authenticate you if you replace apikey_id with your user's API key id, and replace apikey_secret with your API key secret values.

curl -u {apikey_id}:{apikey_secret} https://api.connio.com/v3/accounts/_this_

All RESTful API requests done with API key credentials must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

Security Warning

Note that your admin user API access key credentials carries many privileges (admin privileges to be exact), so make sure to keep it secret! It is not recommended to share your credentials with other parties, or distribute it in your devices.

Connio introduces a different set of credentials specifically designed to send and retrieve data from clients, connected devices, or other data sources securely called device and apiclient API access keys. For more information see Devices , Api Clients and Api Keys resource sections.

Suggest Edits

API Access

 

An API Key instance sub resource represents an api key entity. API keys allows external or internal entities to interact with the Connio platform securely. Every transaction of API keys are recorded to be used for audit and billing purposes.

Note that API keys do not exist by their own; instead they are always created automatically under a parent entity such as user, device or apiclient. We call these keys User Key, Device Key, and Client Key respectively.

Resource Attributes

Attribute Description
Context It consists of type and ids fields. type can be one of the following account, app, and device. The ids field contains a set of entity ids matching the given context type.
Scope Scopes let you specify exactly what type of access you need. Scopes limit access for api keys. See the scope table below for more information.
RateLimit As its name suggests, it limits the transaction rate of this api key. Default value for this attribute is defined by the account type, and cannot be changed by the user. Can be unlimited (-1) or x number of calls per minute.
{
  "id": "_key_924201752433266229",
  "secret": "85f0b8497fab4244b63439b23fe148d0",
  "ownerId": "_usr_924201603387295292",
  "accountId": "_acc_923380065327020781",
  "context": {
    "type": "account",
    "ids": [
        "_acc_923380065327020781"
    ]
  },
  "scope": [
    "app:read-data",
    "device:read-data",
    "deviceprofile:read",
    "device:read",
    "device:modify",
    "device:write-data",
    "subaccount:read",
    "appprofile:modify",
    "deviceprofile:modify",
    "app:modify",
    "account:read",
    "app:read",
    "appprofile:read",
    "apiclient:read"
  ],
  "rateLimit": 60,
  "dateCreated": "2017-06-29T03:43:54.309Z",
  "dateModified": "2017-06-29T03:43:54.309Z"
}

Context

Context defines the context that this api key will be applicable. For example if the context is set to app with ids field ['_app_156238482748283274'], and the scope attribute is set to app:read, external system using this key can read the metadata of the app with the given id.

In some scenarios, devices do not get connected to the Connio platform directly. Instead, an external backend system exchange data with the Connio platform on behalf of these devices. In such cases, it is useful to provide a single api key to the external backend system instead of multiple keys. Below we show an example api client's key meeting the requirements of this scenario:

{
  "id": "_key_465924116351130803",
  "secret": "66b61659cd7a4885bec0756d9ef97ea4",
  "accountId": "_acc_466239243174908338",
  "context": { 
    "type": "device", 
    "ids": ['_dev_467084708689467300', '_dev_467084708689467301', '_dev_467084708689467302'] 
  },
  "scope": ['device:read', 'device:read-data', 'device:write-data', 'device:execute-method', 'device:modify'],
  "rateLimit": 120
}

Acceptable context types are:

Type Description
account Gives access to specific accounts for management. The owner account id or a set of sub accounts can be provided as id list. All user api keys runs in account context.
device Gives access to specific devices. This key can be used to read/write data from/to the specified devices. Each device gets an api key automatically when created, device being its context type containing all device related scopes.
app Gives access to specific apps. With proper scope, this key can be used to manage (i.e. add, remove properties etc.), and/or to read/write data from/to the specified apps.

Rule

Only devices generated from Gateway device profile can carry multiple device ids in their api keys. Other devices can have only single device id in their api key.

Tip

Api Client is generic entity that might represent any kind of external or internal agent that interacts with the Connio platform. It is the only entity that might have all three context types in it api keys (not at the same time off course). Like devices, each api client gets an api key automatically when created.

Scope

Scope defines the privileges given to a api key. Each context works with different sets of scopes. Valid scopes are:

Scope Description Context
(no scope) Grants read-only access to public information. all
subaccount:create Allows sub account creation. account
subaccount:read Grants read-only access to all sub account data. account
subaccount:modify Allows sub account data modification. account
subaccount:delete Allows sub account deletion. account
user:create Allows user creation. account
user:read Grants read-only access to all user data. account
user:modify Allows user data modification. account
user:delete Allows user deletion. account
apiclient:create Allows api client creation. account
apiclient:read Grants read-only access to all api client data. account
apiclient:modify Allows api client data modification. account
apiclient:delete Allows api client deletion. account
deviceprofile:create Allows device profile creation. account
deviceprofile:read Grants read-only access to all device profile data. account
deviceprofile:modify Allows device profile data modification. account
deviceprofile:delete Allows device profile deletion. account
device:create Allows device creation. account
device:read Grants read-only access to all device data. account, device, app
device:read-data* Allows reading device captured data from the time-series database and device state. account, device, app
device:write-data* Allows writing data to the platform on behalf of a device. device, app
device:execute Allows public method execution on the device. account, device, app
device:modify Allows device data modification. account, device
device:delete Allows device deletion. account
appprofile:create Allows app template creation. account
appprofile:read Grants read-only access to all app template data. account
appprofile:modify Allows app profile data modification. account
appprofile:delete Allows app profile deletion. account
app:create Allows app creation. account
app:read Grants read-only access to all app data. account, app
app:read-data Allows reading app captured data from the time-series database and app state. account, app
app:write-data Allows writing data into app properties. app
app:execute Allows public methods execution on the app. account, app
app:modify Allows app data modification. account, app
app:delete Allows app deletion. account

(*) If the key's is a API Client or User key, it can access only to public properties of the device for reading and writing. If the key's owner entity is a device, it can access to all its properties including private and public ones.

Device, and User keys

API Keys that are automatically generated for device, and user entities are called Device Keys, and User Keys respectively.

Device Key allows any physical device or data source to:

  • Read device state including the most recent property values
  • Read device metadata and historical data
  • Write device data to the platform
  • Execute device methods
  • Connect to the platform through one of the supported connection methods such as MQTT or WebSocket (read & write)

User Key allows account users to:

  • Managed the given account entities including sub accounts, apps, devices, device profiles, etc..

A fully privileged Api Client with App context allows any app client to:

  • Read app state including the most recent property values
  • Read app metadata and historical data
  • Execute app methods
  • Write app data to the platform
  • Connect to device mirrors
  • Read device state including the most recent property values
  • Read device historical data
  • Execute device methods

User roles

For convenience, when creating new users, roles can be specified. Connio API supports 3 predefined roles as such:

Role Description Scopes
admin Full system administration privileges -
power Power user. Full system administration privileges minus account closing, user creation, modification , deletion and api key regeneration -
user Regular user. Mostly read-only access to account entities -
guest Very limited access -

Api Key Usage

The following Data Services endpoints can be used with the following api keys.

Device Key

Operation HTTP Verb Endpoint Shortcut
Write POST data/devices/_this_/properties /data/properties
Write POST data/devices/_this_/properties/{ref} /data/properties/{ref}
Read GET data/devices/_this_ /data
Read GET data/devices/_this_/properties/{ref} /data/properties/{ref}
Exec PUT data/devices/_this_/methods/{ref} /data/methods/{ref}

ref can be id or name

_this_ is a special keyword to refer to the device associated with the given device key, without using device id or name.

API Client Key (Generic Key) with App context and full app access privilege

Operation HTTP Verb Endpoint Shortcut/Notes
Write POST data/apps/{ref}/properties None
Write POST data/apps/{ref}/properties/{ref} None
Read GET data/apps/{ref} None
Exec PUT data/apps/{ref}/methods/{ref} None
Write POST data/devices/{ref}/properties Send command to a plugged device
Write POST data/devices/{ref}/properties/{ref} None
Read GET data/devices/{ref} Read plugged device state
Read GET data/devices/{ref}/properties/{ref} Read plugged device property
Exec PUT data/devices/{ref}/methods/{ref} Execute plugged device method

App keys can only access to the devices plugged into this app. ref can be id or name

API Client Key (Generic Key) with Device context and full device access priviledge

Operation HTTP Verb Endpoint Shortcut/Notes
Write POST data/devices/{ref}/properties Send command to a plugged device
Write POST data/devices/{ref}/properties/{ref} None
Read GET data/devices/{ref} Read plugged device state
Read GET data/devices/{ref}/properties/{ref} Read plugged device property
Exec PUT data/devices/{ref}/methods/{ref} Execute plugged device method

Tip

Generic api keys created with Device context can act on behalf on the devices listed in the ids array.

Suggest Edits

Pagination

 

Almost all queries returning a collection in Admin API services are resulted in paginated form as shown below:

Attribute Description
total Total number of items found.
itemCount Number of items in this response entity.
numOfPages Total number of pages.
pageNo Current page no.
skip Number of items skipped from the beginning of the page.
results List of the items.

Example:

GET ../v3/devices

{
  "total": 5000,
  "itemCount": 80,
  "numOfPages": 63,
  "pageNo": 1,
  "skip": 0,
  "results": [
    { ... }
  ]
}

Pagination Related Params

Param Example
The number of items per page ?pageSize={number}
The requested page no ?pageNo={number}
The number of page items to be skipped ?skip={number}
Suggest Edits

Error Handling

 

You should expect to handle the following status codes to manage your application logic.

Possible Response Status Codes

Status Code Description
200 OK. Request has succeeded.
202 Data write request has been accepted for processing, but the processing will be completed asynchronously. You receive this response code only when writing data to the Connio platform.
400 Bad request (e.g. missing a required object attribute).
401 Unauthorized. Authentication is possible but has failed or key credentials do not allow this operation.
403 Forbidden. The request was a legal request, but the server is refusing to respond to it (e.g. device is disabled).
404 Not Found. The requested resource could not be found or provided credentials do not match to any account.
409 Conflict. The request could not be processed due to domain constraints.
429 Too Many Requests. The client has sent too many requests in a given period of time.
500 Server Error. Something went wrong in the Connio server while processing the request.
503 Not implemented. This feature has not been implemented yet.

Error Response Object

Connio APIs might return multiple errors for a single request. More information about each specific error is included in the body of each response in the following format:

Attribute Description
code Numeric error code.
message Plain text explanation of the problem for the developer.
friendlyMessage User friendly version of the same error message to be used in web and mobile apps.
moreInfoUrl A link that will take you to the error documentation and community site.
[
  {
    "code": "1001",
    "message": "Illegal argument detected: period",
    "friendlyMessage": "Period must be a positive integer or zero.",
    "moreInfoUrl": "https://docs.connio.com/v3/docs/err1001"
  }
]
Suggest Edits

Naming Your Entities

 

The following rules apply to entity names:

  1. Names are case insensitive, i.e. "WindTurbine.Rotation" will be equal to "windturbine.rotation"
  2. Whitespace is not allowed
  3. Only alphanumeric characters, period “.”, dash “-”, and underscore “_” are allowed
  4. Must start with a letter
  5. Names can be maximum 64 characters long though you should try to keep the values fairly short

Exception

Method names cannot contain period “.”

For example the following property names are considered valid:

  • Ambient.Temp
  • Ambient_Temp
  • Ambient.Temp01

The following property names are not valid:

  • Ambient Temp Sensor
  • 0_Ambient.Temp
  • _Ambient.Temp
  • Ambient:temp:Sensor

For example the following method names are considered valid:

  • convertTempTo_F
  • setDeviceState

The following method names are not valid:

  • convert.Temp.F
  • _setDeviceState
 

Admin Services API provides all the functionality to build your Internet of Things solutions using Connio entities. Each Connio entity corresponds to a resource instance within the Admin Services API context.

All Admin Services API endpoints start with https://api.connio.com/v3 base URL. Every call against the base URL with your account's api keys (i.e. user keys) are executed within the scope of your master account.

 

An Account instance resource represents a single account entity.

A system account can be master or sub account depending on its location in the account hierarchy.

Sub accounts are created under a master or another sub account. Unlike master accounts, sub accounts have ownerId attribute in their resource definition. Owner account's administrator can access to all resources (e.g. devices, users, etc..) of their sub accounts for administrative purposes.

Rule

Master accounts cannot be created using Admin Services API. You must use Connio portal in order to create your master account and get a user api key. Sub accounts on the other hand can be created using Admin Services API.

Resource Attributes

Attribute Description
id A 23 to 26 characters long string that uniquely identifies this account.
name A user selected name (as specified at the signup) that uniquely identifies this account.
friendlyName Display name of the account.
ownerId Optional. Id of the owner account, if any.
plan The plan type of the account. Either trial or one of the paid plans.
status The status of this account. Usually open, but can be closed and suspended.
organization Optional. Details of the organization that this account is related to.
description Optional. Account description.
tags Optional. The list of the tags associated with the account.
balance The current balance of the account in US dollars, if paid plan.
locked Locked account cannot be deleted, modified, new sub elements (e.g. sub accounts, devices, etc..) cannot be added, or existing sub elements cannot be removed; but its sub elements can be modified.
dateCreated The date that this account was created in ISO 8601 format.
dateModified The date that this account was last modified in ISO 8601 format.

Below is a fully populated Account instance resource.

{
  "id": "_acc_833847694816627075",
  "name": "Inbiza",
  "friendlyName": "Inbiza Technology Solutions",
  "plan": {
    "type": "trial",
    "expiresAt": "2017-12-31T23:59:59Z"
  },
  "status": "open",
  "organization": {
    "name": "Inbiza Technology Solutions Ltd.",
    "websiteUrl": "http://www.inbiza.com",
    "imageUrl": "http://www.inbiza.com/images/logo.jpg"
  },
  "description": "Inbiza is a technology consulting company specialized in Cloud computing, embedded systems, and IoT solutions.",
  "tags": ["canada", "system integrator"],
  "balance": {
    "amount": 0
  },
  "locked": false,
  "dateCreated": "2017-02-24T11:46:31.293Z",
  "dateModified": "2017-04-24T01:13:21.346Z"
}

Api key credentials allow Connio to infer requester's identity. For example if you are using your account's admin user's api key credentials, you can simply use _this_ placeholder to refer to your account. On the other hand, if you want to operate on a sub account, you need to specify a reference (i.e id or name) explicitly.

Sub Account Brief View

When an owner account query for its sub accounts, the following response object returned from the system. Response object provides a brief view of the sub accounts instead of providing all account attributes. You should query the sub account using its id in order to access its full view.

Response object consists of the following attributes:

Attribute Description
id A 23 character string that uniquely identifies this account.
name A user selected name (as specified at the signup) that uniquely identifies this account.
ownerId Id of the owner account.
plan The plan type of the account. Either trial or one of the paid plans.
status The status of this account. Usually open, but can be closed and suspended.
balance The balance of the account if paid plan.
locked Restricted or fully accessible.
dateCreated The date that this account was created in ISO 8601 format.
Suggest Edits

View my account details

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/accounts/_this_
curl --request GET \
  --url https://api.connio.com/v3/accounts/_this_
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/accounts/_this_' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/accounts/_this_")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/accounts/_this_");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/accounts/_this_"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "id": "_acc_922546713945946481",
 "name": "inbiza",
 "friendlyName": "Inbiza Tech Solutions",
 "plan": {
   "type": "paidPlanA"
 },
 "status": "open",
 "organization": {
   "name": "Inbiza Tech Solutions Ltd.",
   "websiteUrl": "http://www.inbiza.com",
   "imageUrl": "http://www.inbiza.com/l.png"
  },
 "description": "Demo account",
 "balance": {
   "amount": 0
 },
 "tags": ["system-integrator"],
 "locked": false,
 "dateCreated": "2017-06-26T20:55:39.434Z",
 "dateModified": "2017-06-27T20:57:52.833Z"
}
 

Api Key Authorization

Required Fields Values
Context type Account
Scopes account:read
Suggest Edits

Modify my account

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.connio.com/v3/accounts/_this_
curl --request PUT \
  --url https://api.connio.com/v3/accounts/_this_
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.connio.com/v3/accounts/_this_' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/accounts/_this_")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.connio.com/v3/accounts/_this_");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/accounts/_this_"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "id": "_acc_922546713945946481",
 "name": "inbiza",
 "friendlyName": "Inbiza Technologies",
 "plan": {
   "type": "paidPlanA"
 },
 "status": "open",
 "organization": {
   "name": "Inbiza Technology Solutions Ltd."
  },
 "description": "Modified account",
 "balance": {
   "amount": 0
 },
 "tags": ["system-integrator", "Canada"],
 "locked": false,
 "dateCreated": "2017-06-26T20:55:39.434Z",
 "dateModified": "2017-06-27T20:59:52.833Z"
}

Body Params

friendlyName
string

Display name of the account.

organization
object

Details of the organization related to this account.

 
organization.name
string
required

Organization name

organization.websiteUrl
string
organization.imageUrl
string

Some url to fetch organization logo

description
string

Account description.

tags
array of strings

The list of the tags associated with this account.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes account:modify

Tip

You can remove optional fields from your account by setting them to tags=[], description="" and organization={}.

Suggest Edits

Create sub account

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/accounts
curl --request POST \
  --url https://api.connio.com/v3/accounts
var request = require("request");

var options = { method: 'POST', url: 'https://api.connio.com/v3/accounts' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.connio.com/v3/accounts");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/accounts"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "id": "_acc_923260950895420040",
 "name": "my_sub_account",
 "ownerId": "_acc_922546713945946481",
 "plan": {
  "type": "trial",
  "expiresAt": "2017-12-01T00:00:00.000Z"
 },
 "status": "created",
 "balance": {
   "amount": 0
 },
 "locked": false,
 "dateCreated": "2017-06-27T20:34:42.026Z"
}

Body Params

name
string
required

New sub account's name.

plan
object

The plan type of the account. Either trial or one of the paid plans.

 
plan.type
string
required

trial, paidPlanA, or paidPlanB

plan.expiresAt
yyyy-mm-dd

Required if plan type is "trial", should be in ISO 8601 format

user
object

Invite user for the newly created sub account.

 
user.fullName
string

Full name of the user

user.email
string

Email address that will be used as username

user.role
string

The role assigned to the user. Can be either admin, user (regular user), power (power user), guest, and custom.

 

Rule

Sub accounts can be created with or without users. When created with user, the system sends a confirmation email to the user's email address automatically.

Api Key Authorization

Required Fields Values
Context type Account
Scopes account:modify, subaccount:create
Suggest Edits

List sub accounts

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/accounts
curl --request GET \
  --url https://api.connio.com/v3/accounts
var request = require("request");

var options = { method: 'GET', url: 'https://api.connio.com/v3/accounts' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/accounts");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/accounts"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "total": 1,
 "itemCount": 1,
 "numOfPages": 1,
 "pageNo": 1,
 "skip": 0,
 "results": [
  {
   "id": "_acc_923226478420405879",
   "name": "sub_account",
   "ownerId": "_acc_922546713945946481",
   "plan": {
     "type": "paidPlanA"
   },
   "status": "open",
   "balance": {
     "amount": 0
   },
   "locked": false,
   "dateCreated": "2017-06-27T19:26:12.587Z"
  }
 ]
}

Query Params

status
string

Filters sub accounts by status.

tags
string

Filters sub accounts by tag. Comma separated list of tags.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes subaccount:read
Suggest Edits

View sub account details

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/accounts/ref
curl --request GET \
  --url https://api.connio.com/v3/accounts/ref
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/accounts/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/accounts/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/accounts/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/accounts/ref"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

ref
string
required

Sub account name or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes subaccount:read

Security

If a user tries to access sub account information without having proper credentials (e.g. GET .../v3/accounts/{ref}/users), the system returns Resource Not Found error instead of Unauthorized error. This is intended security measure in order to prevent unwanted account id and name lookups.

Suggest Edits

Modify sub account

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.connio.com/v3/accounts/ref
curl --request PUT \
  --url https://api.connio.com/v3/accounts/ref
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.connio.com/v3/accounts/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/accounts/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.connio.com/v3/accounts/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/accounts/ref"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

ref
string
required

id or name of the sub account.

Body Params

friendlyName
string

Display name of the account.

plan
object

The plan type of the account. Either trial or one of the paid plans.

 
plan.type
string
required

trial, paidPlanA, or paidPlanB

plan.expiresAt
yyyy-mm-dd

Required if plan type is "trial", should be in ISO 8601 format

status
string

The status of this account. Usually open, but can be closed and suspended.

balance
object

The current balance of the account in US dollars, if paid plan.

 
balance.amount
double

Balance due in US dollars.

organization
object

Details of the organization that this account is related to.

 
organization.name
string
required

Organization name

organization.websiteUrl
string
organization.imageUrl
string

Some url to fetch organization logo

description
string

Account description.

tags
array of strings

The list of the tags associated with the account.

locked
boolean

Locked account cannot be deleted, modified, new sub elements (e.g. sub accounts, devices, etc..) cannot be added, or existing sub elements cannot be removed; but its sub elements can be modified.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes subaccount:modify
Suggest Edits

Closing sub account

 

Basic Auth

 Authentication is required for this endpoint.
deletehttps://api.connio.com/v3/accounts/ref
curl --request DELETE \
  --url https://api.connio.com/v3/accounts/ref
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.connio.com/v3/accounts/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/accounts/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.connio.com/v3/accounts/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/accounts/ref"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "id": {
  "id": "_acc_923296852111316066",
  "name": "my_sub_account",
  "ownerId": "_acc_922546713945946481",
  "plan": {
   "type": "paidPlanA"
  },
  "status": "closed",
  "balance": {
   "amount": 0
  },
  "locked": false,
  "dateCreated": "2017-06-27T21:46:01.784Z"
 }
}

Path Params

ref
string
required

id or name of the sub account.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes account:modify, subaccount:delete

An User instance resource represents a single user entity.

Tip

System users are personas who interact with the platform in order to develop an IIoT solution or monitor the system. System users should not be confused with users typically defined by your solution's domain.

Resource Attributes

Attribute Description
id A 23 to 26 characters long string that uniquely identifies this user.
accountId The unique id of the account that created this user.
email The email address of the user. Since emails must be unique across the system, email can be used as entity name in URL paths like .../users/luke.skye@acme-systems.com.
name Full name of the user.
status The status of this user. Can be either invited, confirmed and disabled. Users with invited and disabled status cannot access to the platform.
role The role assigned to the user. Can be either admin, user (regular user), power (power user), guest, and custom.
description Optional. Some description about this user.
tags Optional. The list of the tags associated with the user.
avatarUrl Optional. URL for the avatar image.
timezone Optional. The time zone for this user in [City] UTC±[hh][mm] format.
locale Optional. Preferred language and locale for this user in [language code]-[country] format.
locked if locked, entity cannot be modified, deleted.
dateCreated The date that this user was created in ISO 8601 format.
dateModified The date that this user was last modified in ISO 8601 format.
{
  "id": "_usr_587617400839897384",
  "accountId": "_acc_587617399162687551",
  "email": "mike.stevenson@acme-systems.com",
  "name": "Michael Stevenson",
  "status": "confirmed",
  "role": "admin",  
  "description": "Account owner",
  "tags": ["r&d", "developer"],
  "avatarUrl": "http://s3.content.avatars.com/images/minime.jpg",
  "timezone": "Vancouver UTC-08:00",
  "locale": "en-ca",
  "dateCreated": "2016-03-21T18:10:52.882Z",
  "dateModified": "2016-03-23T19:32:38.681Z"
}
Suggest Edits

Invite new user

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/users
curl --request POST \
  --url https://api.connio.com/v3/users
var request = require("request");

var options = { method: 'POST', url: 'https://api.connio.com/v3/users' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.connio.com/v3/users");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/users"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "token": "548de5dde9f048959c0b6d2e29d67a8a"
}

Body Params

email
string
required

User's email. Should be unique across the Connio platform.

role
string
required

The role assigned to the user. Can be either admin, user (regular user), power (power user), guest, and custom.

name
string

User's full name.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes user:create

Rule

Only users with admin role can invite new users. Therefore you must use an Api Key belongs to an admin user in order to complete this operation successfully.

Suggest Edits

List users

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/users
curl --request GET \
  --url https://api.connio.com/v3/users
var request = require("request");

var options = { method: 'GET', url: 'https://api.connio.com/v3/users' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/users");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/users"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "total": 1,
  "itemCount": 1,
  "numOfPages": 1,
  "pageNo": 1,
  "skip": 0,
  "results": [
    {
      "id": "_usr_922546713954222783",
      "accountId": "_acc_922546713945946481",
      "name": "mike",
      "email": "mike@inbiza.com",
      "role": "admin",
      "status": "confirmed",
      "locked": false,
      "dateCreated": "2017-06-26T20:55:41.388Z",
      "dateModified": "2017-06-26T20:59:39.434Z"
    }
  ]
}

Query Params

role
string

Filters users by role.

tags
string

Filters users by tag. Comma separated list of tags.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes user:read
Suggest Edits

View user details

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/users/ref
curl --request GET \
  --url https://api.connio.com/v3/users/ref
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/users/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/users/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/users/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/users/ref"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_usr_922546713954222783",
  "accountId": "_acc_922546713945946481",
  "name": "mike",
  "email": "mike@inbiza.com",
  "role": "admin",
  "status": "confirmed",
  "locked": false,
  "dateCreated": "2017-06-26T20:55:41.388Z",
  "dateModified": "2017-06-26T21:35:40.131Z"
}

Path Params

ref
string
required

User's email or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes user:read for viewing other users
Suggest Edits

Modify user

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.connio.com/v3/users/ref
curl --request PUT \
  --url https://api.connio.com/v3/users/ref
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.connio.com/v3/users/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/users/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.connio.com/v3/users/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/users/ref"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_usr_922546713954222783",
  "accountId": "_acc_922546713945946481",
  "name": "Mike S.",
  "email": "mike@inbiza.com",
  "role": "admin",
  "status": "confirmed",
  "description": "2nd admin",
  "locale": "en-CA",
  "timezone": "Vancouver UTC-08:00",
  "locked": false,
  "dateCreated": "2017-06-28T00:15:34.561Z",
  "dateModified": "2017-06-26T20:55:39.434Z"
}

Path Params

ref
string
required

User's email or id.

Body Params

name
string

Full name of the user.

password
string

User's password.

description
string

Some description about this user.

tags
array of strings

The list of the tags associated with the user.

timezone
string

The time zone for this user in [City] UTC±[hh][mm] format.

locale
string

Preferred language and locale for this user in [language code]-[country] format.

avatarUrl
string

URL for the avatar image.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes user:modify for modifying other users

Tip

You can remove optional fields by setting them to tags=[], description="", timezone="", locale="" and avatarUrl="".

Suggest Edits

Delete user

 

Basic Auth

 Authentication is required for this endpoint.
deletehttps://api.connio.com/v3/users/ref
curl --request DELETE \
  --url https://api.connio.com/v3/users/ref
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.connio.com/v3/users/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/users/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.connio.com/v3/users/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/users/ref"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "nrOfItems": 1
}

Path Params

ref
string
required

User's email or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes user:delete

Rule

Each master account needs at least one admin user. Note that it is ok to have no users for sub accounts, but not for master accounts.

Suggest Edits

Regenerate user key

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/users/id/apikey
curl --request POST \
  --url https://api.connio.com/v3/users/id/apikey
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.connio.com/v3/users/id/apikey' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/users/id/apikey")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.connio.com/v3/users/id/apikey");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/users/id/apikey"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_key_862757926445830619",
  "secret": "63ccd7444b904e6190f1ade86d542796",
  "ownerId": "_usr_862756285715893305",
  "accountId": "_acc_862483848610897332",
  "context": {
    "type": "account",
    "ids": [
      "_acc_862483848610897332"
    ]
  },
  "scope": [
    "subaccount:modify",
    "device:create",
    "app:read-data",
    "device:read-data",
    "deviceprofile:read",
    "device:read",
    "apiclient:delete",
    "subaccount:create",
    "device:modify",
    "subaccount:read",
    "app:create",
    "subaccount:delete",
    "device:delete",
    "appprofile:delete",
    "account:close",
    "user:read",
    "appprofile:modify",
    "deviceprofile:create",
    "account:modify",
    "deviceprofile:modify",
    "app:modify",
    "user:delete",
    "account:read",
    "app:read",
    "appprofile:create",
    "apiclient:create",
    "user:create",
    "appprofile:read",
    "apiclient:modify",
    "user:modify",
    "deviceprofile:delete",
    "apiclient:read",
    "app:delete"
  ],
  "rateLimit": 60,
  "dateCreated": "2017-04-05T09:05:59.465Z",
  "dateModified": "2017-04-05T09:05:59.465Z"
}

Path Params

id
string
required

User's id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes User can execute this operation only on himself. Only admins can regenerate other users' api keys.
Suggest Edits

View user key

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/users/id/apikey
curl --request GET \
  --url https://api.connio.com/v3/users/id/apikey
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/users/id/apikey' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/users/id/apikey")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/users/id/apikey");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/users/id/apikey"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_key_862757926445830619",
  "secret": "63ccd7444b904e6190f1ade86d542796",
  "ownerId": "_usr_862756285715893305",
  "accountId": "_acc_862483848610897332",
  "context": {
    "type": "account",
    "ids": [
      "_acc_862483848610897332"
    ]
  },
  "scope": [
    "subaccount:modify",
    "device:create",
    "app:read-data",
    "device:read-data",
    "deviceprofile:read",
    "device:read",
    "apiclient:delete",
    "subaccount:create",
    "device:modify",
    "subaccount:read",
    "app:create",
    "subaccount:delete",
    "device:delete",
    "appprofile:delete",
    "account:close",
    "user:read",
    "appprofile:modify",
    "deviceprofile:create",
    "account:modify",
    "deviceprofile:modify",
    "app:modify",
    "user:delete",
    "account:read",
    "app:read",
    "appprofile:create",
    "apiclient:create",
    "user:create",
    "appprofile:read",
    "apiclient:modify",
    "user:modify",
    "deviceprofile:delete",
    "apiclient:read",
    "app:delete"
  ],
  "rateLimit": 60,
  "dateCreated": "2017-04-05T09:05:59.465Z",
  "dateModified": "2017-04-05T09:05:59.465Z"
}

Path Params

id
string
required

User's id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes User can execute this operation only on himself.
Suggest Edits

Api Clients

 

An Api Client instance resource represents a single api client entity.

Resource Attributes

Attribute Description
id A 23 to 26 characters long string that uniquely identifies this api client.
accountId The unique id of the account that created this api client.
name Account wide unique, URL friendly name of the api client.
friendlyName Human friendly name of the api client.
description Optional. Api client description.
tags Optional. Tags associated with this api client.
locked if locked, entity cannot be modified, deleted.
dateCreated The date that this api client was created in ISO 8601 format.
dateModified The date that this api client was modified in ISO 8601 format.
{
  "id": "_api_530976712669455460",
  "accountId": "_acc_530308970920181397",
  "name": "atm_data_reader",
  "friendlyName": "ATM Monitor Reader",
  "description": "This api client reads data from devices plugged into the atm-monitoring app.",
  "tags": [
    "test"
  ],
  "locked": false,
  "dateCreated": "2017-04-29T12:54:40.010Z",
  "dateModified": "2017-04-29T12:54:40.010Z"
}
Suggest Edits

Create api client

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/apiclients
curl --request POST \
  --url https://api.connio.com/v3/apiclients
var request = require("request");

var options = { method: 'POST', url: 'https://api.connio.com/v3/apiclients' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apiclients")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.connio.com/v3/apiclients");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apiclients"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "id": "_api_923416040660421637",
 "accountId": "_acc_923380065327020781",
 "name": "Provisioning",
 "friendlyName": "Provisioning",
 "description": "Device provisioning key",
 "tags": [
     "provisioning"
 ],
 "locked": false,
 "dateCreated": "2017-06-28T01:42:50.166Z",
 "dateModified": "2017-06-28T01:42:50.166Z"
}

Body Params

context
object
required

Operation context of the api client's key. See Api Key section for details.

 
context.type
string

Either account, app or device

context.ids
array of strings

Set of the entity ids that will be accessible to the owner of the api key. Entity types should match context type.

scope
array of strings
required

Scope of the api client's key. See Api Key section for details.

name
string

Account wide unique, URL friendly name of the api client.

friendlyName
string

Human friendly name of the api client.

description
string

Api client description.

tags
array of strings

The list of the tags associated with the api client.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes apiclient:create
Suggest Edits

List api clients

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/apiclients
curl --request GET \
  --url https://api.connio.com/v3/apiclients
var request = require("request");

var options = { method: 'GET', url: 'https://api.connio.com/v3/apiclients' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apiclients")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/apiclients");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apiclients"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "total": 1,
  "itemCount": 1,
  "numOfPages": 1,
  "pageNo": 1,
  "skip": 0,
  "results": [
   {
    "id": "_api_923380135323678165",
    "accountId": "_acc_923380065327020781",
    "name": "DeviceDataReader",
    "friendlyName": "DeviceDataReader",
    "locked": false,
    "dateCreated": "2017-06-28T00:31:29.917Z",
    "dateModified": "2017-06-28T00:31:29.917Z"
   }
  ]
}

Query Params

tags
string

Filters api clients by tag. Comma separated list of tags.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes apiclient:read
Suggest Edits

View api client details

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/apiclients/ref
curl --request GET \
  --url https://api.connio.com/v3/apiclients/ref
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/apiclients/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apiclients/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/apiclients/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apiclients/ref"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_api_923380135323678165",
  "accountId": "_acc_923380065327020781",
  "name": "DeviceDataReader",
  "friendlyName": "Device data reader client",
  "locked": false,
  "dateCreated": "2017-06-28T00:31:29.917Z",
  "dateModified": "2017-06-28T00:31:29.917Z"
}

Path Params

ref
string
required

Api client's name or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes apiclient:read
Suggest Edits

Modify api client

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.connio.com/v3/apiclients/ref
curl --request PUT \
  --url https://api.connio.com/v3/apiclients/ref
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.connio.com/v3/apiclients/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apiclients/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.connio.com/v3/apiclients/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apiclients/ref"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_api_923380135323678165",
  "accountId": "_acc_923380065327020781",
  "name": "DeviceDataReader",
  "friendlyName": "Device data reader client",
  "locked": false,
  "dateCreated": "2017-06-28T00:31:29.917Z",
  "dateModified": "2017-06-28T00:31:29.917Z"
}

Path Params

ref
string
required

Api client's name or id.

Body Params

name
string

Account wide unique, URL friendly name of the api client.

friendlyName
string

Human friendly name of the api client.

description
string

Api client description.

tags
array of strings

The list of the tags associated with the api client.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes apiclient:modify

Tip

You can remove optional fields by setting them to tags=[], and description="".

Suggest Edits

Delete api client

 

Basic Auth

 Authentication is required for this endpoint.
deletehttps://api.connio.com/v3/apiclients/ref
curl --request DELETE \
  --url https://api.connio.com/v3/apiclients/ref
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.connio.com/v3/apiclients/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apiclients/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.connio.com/v3/apiclients/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apiclients/ref"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "nrOfItems": 1
}

Path Params

ref
string
required

Api client's name or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes apiclient:delete
Suggest Edits

Regenerate api client key

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/apiclients/id/apikey
curl --request POST \
  --url https://api.connio.com/v3/apiclients/id/apikey
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.connio.com/v3/apiclients/id/apikey' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apiclients/id/apikey")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.connio.com/v3/apiclients/id/apikey");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apiclients/id/apikey"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_key_862757926445830619",
  "secret": "63ccd7444b904e6190f1ade86d542796",
  "ownerId": "_api_530976712669455460",
  "accountId": "_acc_862483848610897332",
  "context": {
    "type": "app",
    "ids": [
      "_app_865398009039773695"
    ]
  },
  "scope": [
    "device:read-data", 
    "app-write-data"
  ],
  "rateLimit": 60,
  "dateCreated": "2017-04-05T09:05:59.465Z",
  "dateModified": "2017-04-05T09:05:59.465Z"
}

Path Params

id
string
required

Api client's id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes apiclient:modify
Suggest Edits

View api client key

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/apiclients/id/apikey
curl --request GET \
  --url https://api.connio.com/v3/apiclients/id/apikey
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/apiclients/id/apikey' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apiclients/id/apikey")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/apiclients/id/apikey");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apiclients/id/apikey"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_key_862757926445830619",
  "secret": "63ccd7444b904e6190f1ade86d542796",
  "ownerId": "_api_530976712669455460",
  "accountId": "_acc_862483848610897332",
  "context": {
    "type": "app",
    "ids": [
      "_app_865398009039773695"
    ]
  },
  "scope": [
    "device:read-data", 
    "app-write-data"
  ],
  "rateLimit": 60,
  "dateCreated": "2017-04-05T09:05:59.465Z",
  "dateModified": "2017-04-05T09:05:59.465Z"
}

Path Params

id
string
required

Api client's id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes apiclient:read
Suggest Edits

Device Profiles

 

A Device Profile instance resource represents a single device profile entity.

Resource Attributes

Attribute Description
id A 23 to 26 characters long string that uniquely identifies this device profile.
accountId The unique id of the account that created this device profile.
name Account wide unique, URL friendly name of the device profile.
friendlyName Human friendly name of the device profile.
baseProfileId The id of the base device profile, if any.
description Optional. Device profile description.
tags Optional. Tags associated with this device profile.
deviceClass Optional. The class of the devices that are generated from this profile.
productName Optional. The product name, if any.
vendorName Optional. The vendor of the device.
imageUrl Optional. URL for the device image.
locked Locked device profile cannot be deleted, modified, new sub resources (e.g. properties) cannot be added, or existing sub resources cannot be removed; but unless they are locked individually, sub resources can be modified.
dateCreated The date that this device profile was created in ISO 8601 format.
dateModified The date that this device profile entity was modified in ISO 8601 format.
{
  "id": "_dpf_587631821175935749",
  "accountId": "_acc_587617399162687551",
  "name": "TestDevice",
  "friendlyName": "Test Device",
  "description": "A new sensor device for testing",
  "deviceClass": "sensor",
  "vendorName": "Acme Co.",
  "productName": "Prod-101",
  "imageUrl": "http://s3.content.na.connio.com/images/minime.jpg",
  "tags": [
    "acustic",
    "test"
  ],
  "locked": false,
  "dateCreated": "2017-03-21T18:39:31.924Z",
  "dateModified": "2017-03-23T20:05:36.095Z"
}
Suggest Edits

Create device profile

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/deviceprofiles
curl --request POST \
  --url https://api.connio.com/v3/deviceprofiles
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.connio.com/v3/deviceprofiles' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/deviceprofiles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.connio.com/v3/deviceprofiles");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/deviceprofiles"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_dpf_923448436680086057",
  "accountId": "_acc_923380065327020781",
  "name": "TJ-001",
  "friendlyName": "Test jig Model 001",
  "description": "Test jig",
  "tags": [
    "testing"
  ],
  "baseProfileId": "_dpf_923380075974273081",
  "deviceClass": "jig",
  "locked": false,
  "dateCreated": "2017-06-28T02:47:12.073Z",
  "dateModified": "2017-06-28T02:47:12.073Z"
}

Body Params

name
string
required

Account wide unique, URL friendly name of the device profile.

friendlyName
string

Human friendly name of the device profile.

description
string

Device profile description.

tags
array of strings

The list of the tags associated with the device profile.

baseProfile
string

Base device profile id or name. If specified, the newly created device profile inherits all the properties and methods of the base device profile, also copy the values of its tags, vendorName, productName and deviceClass attributes. Alerts are not inherited.

deviceClass
string

Device/Equipment class.

vendorName
string

Vendor or manufacturer of the product.

productName
string

Name of the actual product.

imageUrl
string

Link to physical device's image, illustration, etc.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes deviceprofile:create
Suggest Edits

List device profiles

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/deviceprofiles
curl --request GET \
  --url https://api.connio.com/v3/deviceprofiles
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/deviceprofiles' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/deviceprofiles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/deviceprofiles");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/deviceprofiles"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "total": 2,
  "itemCount": 2,
  "numOfPages": 1,
  "pageNo": 1,
  "skip": 0,
  "results": [
   {
     "id": "_dpf_923380075973163517",
     "accountId": "_acc_923380065327020781",
     "name": "Gateway",
     "friendlyName": "Gateway",
     "description": "Gateway",
     "tags": [
         "gateway"
     ],
     "baseProfileId": "_dpf_923380075974273081",
     "locked": true,
     "dateCreated": "2017-06-28T00:31:24.274Z",
     "dateModified": "2017-06-28T00:31:24.274Z"
    },
    {
      "id": "_dpf_923380075978526830",
      "accountId": "_acc_923380065327020781",
      "name": "Device",
      "friendlyName": "Device",
      "locked": true,
      "dateCreated": "2017-06-28T00:31:24.273Z",
      "dateModified": "2017-06-28T00:31:24.273Z"
     }
  ]
}

Query Params

tags
array of strings

Filters device profiles by tag.

base
string

Finds all device profiles immediately inherited from base profile given by id or name.

class
string

Filters device profiles by device class.

vendor
string

Filters device profiles by vendor name.

product
string

Filters device profiles by product name.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes deviceprofile:read
Suggest Edits

View device profile details

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/deviceprofiles/ref
curl --request GET \
  --url https://api.connio.com/v3/deviceprofiles/ref
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/deviceprofiles/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/deviceprofiles/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/deviceprofiles/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/deviceprofiles/ref"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_dpf_923380075973163517",
  "accountId": "_acc_923380065327020781",
  "name": "Gateway",
  "friendlyName": "Gateway",
  "description": "Gateway",
  "tags": [
      "gateway"
  ],
  "baseProfileId": "_dpf_923380075974273081",
  "locked": true,
  "dateCreated": "2017-06-28T00:31:24.274Z",
  "dateModified": "2017-06-28T00:31:24.274Z"
}

Path Params

ref
string
required

Device profile's name or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes deviceprofile:read
Suggest Edits

Modify device profile

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.connio.com/v3/deviceprofiles/ref
curl --request PUT \
  --url https://api.connio.com/v3/deviceprofiles/ref
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.connio.com/v3/deviceprofiles/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/deviceprofiles/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.connio.com/v3/deviceprofiles/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/deviceprofiles/ref"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_dpf_923448436680086057",
  "accountId": "_acc_923380065327020781",
  "name": "TJ-001",
  "friendlyName": "Test jig Model 001",
  "description": "Test jig",
  "tags": [
    "testing"
  ],
  "baseProfileId": "_dpf_923380075974273081",
  "deviceClass": "jig",
  "locked": false,
  "dateCreated": "2017-06-28T02:47:12.073Z",
  "dateModified": "2017-06-28T02:47:12.073Z"
}

Path Params

ref
string
required

Device profile's name or id.

Body Params

name
string

Account wide unique, URL friendly name of the device profile.

friendlyName
string

Human friendly name of the device profile.

description
string

Device profile description.

tags
array of strings

The list of the tags associated with the device profile.

deviceClass
string

Device/Equipment class.

vendorName
string

Vendor or manufacturer of the product.

productName
string

Name of the actual product.

imageUrl
string

Link to physical device's image, illustration, etc.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes deviceprofile:modify

Tip

You can remove optional fields by setting them to tags=[], description="", deviceClass="", vendorName="", productName="", and imageUrl="".

Suggest Edits

Delete device profile

 

Basic Auth

 Authentication is required for this endpoint.
deletehttps://api.connio.com/v3/deviceprofiles/ref
curl --request DELETE \
  --url https://api.connio.com/v3/deviceprofiles/ref
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.connio.com/v3/deviceprofiles/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/deviceprofiles/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.connio.com/v3/deviceprofiles/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/deviceprofiles/ref"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "nrOfItems": 1
}

Path Params

ref
string
required

Device profile's name or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes deviceprofile:delete

Rule

  • You cannot delete a base device profile with child. You must delete the child first.
  • You cannot delete a device profile with existing devices generated from it. You must delete the device first.
 

A Device instance resource represents a single device entity.

Resource Attributes

Attribute Description
id A 23 to 26 characters long string that uniquely identifies this device.
accountId The unique id of the account that created this device.
name Account wide unique, URL friendly name of the device.
friendlyName Human friendly name of the device.
profileId Id of the device profile that this device is generated from.
apps Id list of the apps that this device plugged into. Can be empty.
description Optional. Device description, maintenance notes, etc.
tags Optional. Device tags.
status Can be enabled, disabled and debug. All incoming and outgoing data are rejected for disabled devices. Disabled devices cannot connect to Connio via MQTT. Default value is enabled.
period Number of seconds that is the expected reporting period of the device. This attribute helps Connio to determine whether a device is active and communicating as expected. 0 can be set to disable this feature. Default is 0. See predefined device profiles tutorial for advanced usage of this attribute.
customIds Optional. Map of user defined identifiers. Supported custom id types are sn, mac, imei, and esn.
timezone Optional. The time zone of this device to be used when visualizing device data.
annotateWithLoc if true, each incoming data point is annotated with device location info. Default value is false.
annotateWithMeta if true, each incoming data point is annotated with device meta data such as device profile tags, device tags, device class, product name, custom ids etc. Default value is false.
location Optional. Location of the device.
locked if locked, entity cannot be modified, deleted.
dateCreated The date that this device was created, in ISO 8601 format.
dateModified The date that this device entity was modified in ISO 8601 format.

Rule

Note that all custom ids are case sensitive. They must be account wide unique; otherwise device won't be located. Max length of a custom id value can be 64 ASCII character long.

Tip

debug status is a feature designed to provide more visibility into device backend's behaviour. When in debugmode, device backends log unexpected events such as data point rejections, out of bounds conditions, etc.

As its name suggests it should not be used in production due to performance implications. When set, the following internal errors and events are written into the device log:

  • Data rejections caused by property type and boundaries
  • Invalid / malformed data feeds
  • Every web hook calls done by alert notification mechanism
  • Provisioning attempts
  • Errors related to methods

Tip

When annotateWithLoc attribute is true, all data points written by the device is automatically enriched by the device location at the server. This feature eliminates the need to set location information in each data point sent over wire and helps users to better control the size of the payload.

{
  "id": "_dev_867347085435988080",
  "accountId": "_acc_865397927566828278",
  "name": "factory3.floor4.forklift4",
  "friendlyName": "Fork lift 001-0023904",
  "profileId": "_dpf_865412173101628139",
  "apps": ["_app_865398009039773695"],
  "description": "Maintenance cycle: every 1,000 km",
  "tags": [
    "forklift",
    "ford"
  ],
  "status": "enabled",
  "period": 60,
  "customIds": {
    "sn": "SN-001-0023904"
  },
  "timezone": "Vancouver UTC-08:00",
  "annotateWithLoc": false,
  "annotateWithMeta": false,
  "location": {
    "zone": "vancouver-facility",
    "geo": {
      "lat": 41.0296287,
      "lon": 28.6232202,
      "alt": 0
    }
  },
  "locked": false,
  "dateCreated": "2017-03-23T08:12:16.597Z",
  "dateModified": "2016-03-23T08:12:16.597Z"
}
Suggest Edits

Create device

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/devices
{
  "name": "factory3.floor4.forklift11",
  "friendlyName": "Forklift #11",
  "profile": "Forklift",
  "status": "enabled",
  "customIds": {
        "mac": "3c:15:d2:ec:ab:30"       
    },
  "period": 0,    
  "description": "Maintenance cycle: every 1,000 miles",
  "tags": ["forklift", "test"],
  "location": {"zone": "factory3.floor4", "geo": { "lat": 49.58695, "lon": -123.59685} },
  "timezone": "Vancouver UTC-08:00",
  "annotateWithLoc": true,
  "annotateWithMeta": true
}
A binary file was returned

You couldn't be authenticated

{
    "id": "_dev_328184799038728992",
    "accountId": "_acc_324009581078777334",
    "name": "factory3.floor4.forklift11",
    "friendlyName": "Forklift #11",
    "profileId": "_dpf_328184504565481065",
    "apps": [],
    "description": "Maintenance cycle: every 1,000 miles",
    "tags": [
        "forklift",
        "test"
    ],
    "status": "enabled",
    "period": 0,
    "customIds": {
        "mac": "3c:15:d2:ec:ab:30"
    },
    "timezone": "Vancouver UTC-08:00",
    "annotateWithLoc": true,
    "annotateWithMeta": true,
    "location": {
        "zone": "factory3.floor4",
        "geo": {
            "lat": 49.58695,
            "lon": -123.59685
        }
    },
    "locked": false,
    "dateCreated": "2018-03-29T19:24:36.734Z",
    "dateModified": "2018-03-29T19:24:36.734Z"
}

Body Params

name
string

Account wide unique, URL friendly name of the device.

friendlyName
string

Human friendly name of the device.

profile
string
required

Id or name of the device profile that this device will be generated from.

apps
string

Comma separated list of ids or names of the apps that this device will be plugged into.

status
string

Can be enabled, disabled and debug.

description
string

Description, maintenance notes, etc...

tags
array of strings

The list of the tags associated with the device.

period
int32

Expected communication frequency of the device, in seconds.

customIds
object

User defined identifiers assigned to the device.

 
customIds.cid
string

Customer set identifier.

customIds.sn
string

Device serial number.

customIds.mac
string

Device mac address.

customIds.imei
string

IMEI if device GSM based.

customIds.esn
string

ESN of the device.

annotateWithLoc
boolean

Annotate data point with device location before store.

annotateWithMeta
boolean

Annotate data point with device meta data (e.g. class, vendor name etc...) before store.

location
object

Location of the device if device is stationary.

 
location.zone
string

A zone name.

location.geo
object

Geo coordinates.

 
timezone
string

The time zone of this device to be used when visualizing device data.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes device:create

Creating multiple devices

Simply make your request within an array element:

[ 
  {
  "name": "factory3.floor4.forklift5",
  "friendlyName": "Forklift #5",
  "profile": "Forklift",
  "status": "enabled",
  "customIds": {
        "mac": "3c:15:d2:ec:ab:30"       
    },
  "period": 0,    
  "description": "Maintenance cycle: every 1,000 miles",
  "tags": ["forklift", "test"],
  "location": {"zone": "plant3.floor4", "geo": { "lat": 49.58695, "lon": -123.59685} },
  "timezone": "Vancouver UTC-08:00",
  "annotateWithLoc": true,
  "annotateWithMeta": true
  },
 {
  "name": "factory3.floor4.forklift6",
  "friendlyName": "Forklift #6",
  "profile": "Forklift",
  "status": "enabled",
  "customIds": {
        "mac": "dd:15:00:ec:aa:30"       
    },
  "period": 0,    
  "description": "Maintenance cycle: every 1,000 miles",
  "tags": ["forklift", "test"],
  "location": {"zone": "plant3.floor4", "geo": { "lat": 49.58695, "lon": -123.59685} },
  "timezone": "Vancouver UTC-08:00",
  "annotateWithLoc": true,
  "annotateWithMeta": true
  }
]
Suggest Edits

List devices

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/devices
curl --request GET \
  --url https://api.connio.com/v3/devices
var request = require("request");

var options = { method: 'GET', url: 'https://api.connio.com/v3/devices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/devices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/devices");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/devices"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "total": 2,
  "itemCount": 2,
  "numOfPages": 1,
  "pageNo": 1,
  "skip": 0,
  "results": [
   {
     "id": "_dev_924329922537879076",
     "accountId": "_acc_924329848168362343",
     "name": "Temp.Sensor.1",
     "friendlyName": "My Test Device",
     "profileId": "_dpf_924329907144716043",
     "apps": ["_app_924329872562001427"],
     "description": "A new device profile for testing",
     "tags": [
         "kitchen",
         "plug",
         "toast_machine"
     ],
     "status": "debug",
     "period": 40,
     "customIds": {
         "sn": "SN-001-0023904"
     },
     "annotateWithLoc": false,
     "annotateWithMeta": false,
     "location": {
         "zone": "facility_1"
     },
     "locked": false,
     "dateCreated": "2017-06-29T07:58:33.378Z",
     "dateModified": "2017-07-05T07:39:14.978Z"
   },
   {
     "id": "_dev_924401715989737243",
     "accountId": "_acc_924329848168362343",
     "name": "Test.Device.2",
     "friendlyName": "Test.Device.1",
     "profileId": "_dpf_924329872560735560",
     "apps": ["_app_924329872562001427"],
     "status": "debug",
     "period": 0,
     "customIds": {
         "sn": "111111"
     },
     "timezone": "(UTC-10:00) Hawaii",
     "annotateWithLoc": false,
     "annotateWithMeta": false,
     "location": {
         "zone": "Zone.1",
         "geo": {
             "lat": 45.4215296,
             "lon": -75.69719309999999
         }
     },
     "locked": false,
     "dateCreated": "2017-06-29T10:21:11.822Z",
     "dateModified": "2017-07-04T09:16:19.117Z"
    }
  ]
}

Query Params

name
string

Find device by name.

tags
string

Filters devices by tag. Comma separated list of tags.

profile
string

Finds all devices immediately inherited from device profile given by id or name.

profiles
string

Finds all devices inherited from device profile given by id or name.

apps
string

Finds all devices plugged into apps given by id or name. Provide a comma separated list for multiple apps.

status
string

Filters devices by status.

cid
string

Finds device by customer id.

sn
string

Finds device by serial number.

mac
string

Finds device by MAC address.

imei
string

Finds device by IMEI.

esn
string

Finds device by ESN.

zone
string

Filters devices by zone.

perimeter
string

Finds all devices within the given perimeter. Perimeter should be supplied as a comma separated list of latitude, longitude and radius in Km.

prop
string

Filters devices by property values. Property value must be provided as a comma separated list of name, comparison operator, and value. Multiple property comparison can be provided.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes device:read

Filtering by CUSTOM ID and DEVICE NAME

"Custom id" and "Name" filter always return single or no result. When mixed with other filters, other filters will be automatically ignored. Custom id value is always case sensitive; Name value is case insensitive.

All filters except "Custom id" and "Name" can be mixed. Mixed queries are applied to the device set in the order shown above starting from "Device Profile" filter.

Filtering by TAG

You can use logical operator for tag filtering. If you add "-" operator in front of a tag, it implies a NEGATE; if you add "^" operator to the end of a tag, it implies an OR.

For example, if you like to see all the devices tagged as "house", and tagged as either "kitchen", "bathroom", or "bedroom" but not tagged as "mansion" you should set a tag filter as:

?tags=house, kitchen^, bathroom^, bedroom^, -mansion

Filtering by PROPERTY VALUES

You can use both property name or qualified name within property value filters.

For example:
?prop=connecteddevice$connectionstatus,eq,online and ?prop=connectionstatus,eq,online considered same.

Property value comparison operator could be one of the following eq, neq, lt, lte, gte, gt, and match (for case insensitive text comparison).

Note that private properties, Waypoint, Object, Blob and File type properties cannot be used in property value filters.

Filtering by ConnectionStatus Property

When a device with ConnectionStatus property is created, this property is set to undefined until it connects to the system via MQTT. If you query the device before the first connection you are not going to get any result from both ?prop=connectionstatus,eq,online and
?prop=connectionstatus,eq,offline queries.

Suggest Edits

View device details

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/devices/ref
curl --request GET \
  --url https://api.connio.com/v3/devices/ref
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/devices/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/devices/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/devices/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/devices/ref"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_dev_923380113809517513",
  "accountId": "_acc_923380065327020781",
  "name": "Temp.Sensor.1",
  "friendlyName": "My Test Device",
  "profileId": "_dpf_923380102384393533",
  "apps": ["_app_923380075974051984"],
  "description": "A new device profile for testing",
  "tags": [
    "house",
    "plug",
    "toast_machine"
  ],
  "status": "enabled",
  "period": 10,
  "customIds": {
    "sn": "SN-001-0023904"
  },
  "annotateWithLoc": false,
  "annotateWithMeta": false,
  "location": {
    "zone": "factory_1",
    "geo": {
        "lat": 41.0296287,
        "lon": 28.6232202,
        "alt": 0
    }
  },
  "locked": false,
  "dateCreated": "2017-06-28T00:31:27.352Z",
  "dateModified": "2017-06-28T06:15:48.884Z"
}

Path Params

ref
string
required

Device's name or id.

Query Params

is_a
string

Device profile reference to make sure that the device is a given type. Returns 404 if not belong to this type.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes device:read
Suggest Edits

View device logs

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/devices/ref/logs
curl --request GET \
  --url https://api.connio.com/v3/devices/ref/logs
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/devices/ref/logs' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/devices/ref/logs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/devices/ref/logs");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/devices/ref/logs"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

[ 
  {
    "logTime": "2017-08-23T16:08:50.567Z",
    "message": "Email notification sent to mike.spikes@acmeco.com",
    "type": "info"
  }
]

Path Params

ref
string
required

Device's name or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes device:read

Tip

Log type can be warning, error, info, fatal, debug, and alert.

Suggest Edits

Modify device

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.connio.com/v3/devices/ref
curl --request PUT \
  --url https://api.connio.com/v3/devices/ref
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.connio.com/v3/devices/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/devices/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.connio.com/v3/devices/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/devices/ref"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_dev_923380113809517513",
  "accountId": "_acc_923380065327020781",
  "name": "Temp.Sensor.1",
  "friendlyName": "My Test Device",
  "profileId": "_dpf_923380102384393533",
  "apps": ["_app_923380075974051984"],
  "status": "enabled",
  "period": 10,
  "annotateWithLoc": false,
  "annotateWithMeta": false,
  "location": {
    "zone": "factory_1",
    "geo": {
        "lat": 41.0296287,
        "lon": 28.6232202,
        "alt": 0
    }
  },
  "locked": false,
  "dateCreated": "2017-06-28T00:31:27.352Z",
  "dateModified": "2017-06-28T06:15:48.884Z"
}

Path Params

ref
string
required

Device's name or id.

Body Params

name
string

Account wide unique, URL friendly name of the device.

friendlyName
string

Human friendly name of the device.

apps
string

Comma separated list of ids or names of the apps that this device will be plugged into.

status
string

Can be enabled, disabled and debug.

description
string

Description, maintenance notes, etc...

tags
array of strings

The list of the tags associated with the device.

period
int32

Expected communication frequency of the device, in seconds.

customIds
object

User defined identifiers assigned to the device.

 
customIds.cid
string

Customer set identifier.

customIds.sn
string

Device serial number.

customIds.mac
string

Device mac address.

customIds.imei
string

IMEI if device GSM based.

customIds.esn
string

ESN of the device.

annotateWithLoc
boolean

Annotate data point with device location before store.

annotateWithMeta
boolean

Annotate data point with device meta data (e.g. class, vendor name etc...) before store.

location
object

Location of the device if device is stationary.

 
location.zone
string

A zone name.

location.geo
object

Geo coordinates.

 
timezone
string

The time zone of this device to be used when visualizing device data.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes device:modify

Tip

You can remove optional fields by setting them to tags=[], description="", timezone="", customIds={}, and location={}.

Suggest Edits

Delete device

 

Basic Auth

 Authentication is required for this endpoint.
deletehttps://api.connio.com/v3/devices/ref
curl --request DELETE \
  --url https://api.connio.com/v3/devices/ref
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.connio.com/v3/devices/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/devices/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.connio.com/v3/devices/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/devices/ref"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "nrOfItems": 1
}

Path Params

ref
string
required

Device's name or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes device:delete
Suggest Edits

Regenerate device key

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/devices/id/apikey
curl --request POST \
  --url https://api.connio.com/v3/devices/id/apikey
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.connio.com/v3/devices/id/apikey' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/devices/id/apikey")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.connio.com/v3/devices/id/apikey");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/devices/id/apikey"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_key_862757926445830619",
  "secret": "63ccd7444b904e6190f1ade86d542796",
  "ownerId": "_dev_865398009039773695",
  "accountId": "_acc_862483848610897332",
  "context": {
    "type": "device",
    "ids": [
      "_dev_865398009039773695"
    ]
  },
  "scope": [
    "device:read-data", 
    "device:write-data", 
  ],
  "rateLimit": 60,
  "dateCreated": "2017-04-05T09:05:59.465Z",
  "dateModified": "2017-04-05T09:05:59.465Z"
}

Path Params

id
string
required

Device's id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes device:modify
Suggest Edits

View device key

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/devices/id/apikey
curl --request GET \
  --url https://api.connio.com/v3/devices/id/apikey
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/devices/id/apikey' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/devices/id/apikey")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/devices/id/apikey");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/devices/id/apikey"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_key_862757926445830619",
  "secret": "63ccd7444b904e6190f1ade86d542796",
  "ownerId": "_dev_865398009039773695",
  "accountId": "_acc_862483848610897332",
  "context": {
    "type": "device",
    "ids": [
      "_dev_865398009039773695"
    ]
  },
  "scope": [
    "device:read-data", 
    "device:write-data", 
  ],
  "rateLimit": 60,
  "dateCreated": "2017-04-05T09:05:59.465Z",
  "dateModified": "2017-04-05T09:05:59.465Z"
}

Path Params

id
string
required

Device's id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes device:read
Suggest Edits

App Profiles

 

An App Profile instance resource represents a single app profile entity.

Resource Attributes

Attribute Description
id A 23 to 26 characters long string that uniquely identifies this app profile.
accountId The unique id of the account that created this app profile.
name Account wide unique, URL friendly name of the app profile.
friendlyName Human friendly name of the app profile.
baseProfileId The id of the base app profile, if any.
description Optional. A brief about this app profile.
tags Optional. Tags associated with this app profile.
version Optional. The version of this app profile.
productName Optional. The product name, if any.
vendorName Optional. The vendor of the app profile.
imageUrl Optional. URL for the device image.
system The device system this app profile will be working with. [] means all types.
locked Locked app profile cannot be deleted, modified, new sub resources (e.g. properties) cannot be added, or existing sub resources cannot be removed; but unless they are locked individually, sub resources can be modified.
dateCreated The date that this app profile was created in ISO 8601 format.
dateModified The date that this app profile entity was modified in ISO 8601 format.
{
  "id": "_apf_873053802870285130",
  "accountId": "_acc_873046106083527769",
  "name": "Vending_Machine",
  "friendlyName": "Vending Machine Monitoring",
  "description": "My demo vending machine monitoring app",
  "tags": [
    "test"
  ],
  "version": "1.0",
  "vendorName": "Acme co.",
  "productName": "VendingMac Monitor",
  "system": [
    {
      "deviceProfileId": "_dpf_873048732840926433",
      "cardinality": 2
    }
  ],
  "locked": false,
  "dateCreated": "2017-04-19T14:02:03.579Z",
  "dateModified": "2017-04-19T14:02:03.579Z"
}

System Object

It defines the device system that this app profile will be working with. It makes this definition in term of device profile types and their unit cardinalities. For example, you can create an app profile to remotely monitor vending machines and define a system with 1 temperature sensor, 1 humidity sensor and 1 voltage meter. All apps generated from this profile are bound to this system.

Attribute Description
deviceProfileId Id of the device profile.
cardinality The maximum number of units of this device profile that can be incorporated into this system. It should be a positive integer number or -1 to denote multiple.
Suggest Edits

Create app profile

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/appprofiles
curl --request POST \
  --url https://api.connio.com/v3/appprofiles
var request = require("request");

var options = { method: 'POST', url: 'https://api.connio.com/v3/appprofiles' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/appprofiles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.connio.com/v3/appprofiles");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/appprofiles"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_apf_923984090658849546",
  "accountId": "_acc_923380065327020781",
  "name": "FireWeatherControl",
  "friendlyName": "Fire Weather Control App",
  "description": "Tracks the fire weather using multiple weather stations and drones.",
  "tags": [
    "fire",
    "weather",
    "critical"
  ],
  "version": "1.0",
  "vendorName": "FTS",
  "productName": "FL001",
  "system": [],
  "locked": false,
  "dateCreated": "2017-06-28T20:31:27.003Z",
  "dateModified": "2017-06-28T20:31:27.003Z"
}

Body Params

name
string
required

Account wide unique, URL friendly name of the app profile.

friendlyName
string

Human friendly name of the app profile.

description
string

App profile description.

tags
array of strings

The list of the tags associated with the app profile.

baseProfile
string

Base app profile id or name. If specified, the newly created app profile inherits all the properties and methods of the base app profile, also copy the values of its tags, vendorName, and productName attributes. Alerts and system are not inherited.

version
string

App version.

vendorName
string

Vendor or developer of the solution.

productName
string

Name of the actual solution/product.

imageUrl
string

Link to app logo.

system
array of objects

Device system that will be used by the instance of this profile.

deviceProfileId
cardinality
 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:create
Suggest Edits

List app profiles

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/appprofiles
curl --request GET \
  --url https://api.connio.com/v3/appprofiles
var request = require("request");

var options = { method: 'GET', url: 'https://api.connio.com/v3/appprofiles' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/appprofiles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/appprofiles");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/appprofiles"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "total": 2,
  "itemCount": 2,
  "numOfPages": 1,
  "pageNo": 1,
  "skip": 0,
  "results": [
    {
      "id": "_apf_923984090658849546",
      "accountId": "_acc_923380065327020781",
      "name": "FireWeatherControl",
      "friendlyName": "Fire Weather Control App",
      "description": "Tracks the fire weather using multiple weather stations and drones.",
      "tags": [
        "fire",
        "weather",
        "critical"
      ],
      "version": "1.0",
      "vendorName": "FTS",
      "productName": "FL001",
      "system": [],
      "locked": false,
      "dateCreated": "2017-06-28T20:31:27.003Z",
      "dateModified": "2017-06-28T20:31:27.003Z"
    },
    {
      "id": "_apf_923380075976645455",
      "accountId": "_acc_923380065327020781",
      "name": "Default",
      "friendlyName": "Default app profile",
      "description": "Account's default app profile",
      "system": [],
      "locked": true,
      "dateCreated": "2017-06-28T00:31:24.272Z",
      "dateModified": "2017-06-28T00:31:24.272Z"
    }
  ]
}

Query Params

tags
array of strings

Filters app profiles by tag.

base
string

Finds all app profiles immediately inherited from base profile given by id or name.

version
string

Filters app profiles by version.

vendor
string

Filters app profiles by vendor name.

product
string

Filters app profiles by product name.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:read
Suggest Edits

View app profile details

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/appprofiles/ref
curl --request GET \
  --url https://api.connio.com/v3/appprofiles/ref
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/appprofiles/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/appprofiles/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/appprofiles/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/appprofiles/ref"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_apf_923984090658849546",
  "accountId": "_acc_923380065327020781",
  "name": "FireWeatherControl",
  "friendlyName": "Fire Weather Control App",
  "description": "Tracks the fire weather using multiple weather stations and drones.",
  "tags": [
    "fire",
    "weather",
    "critical"
  ],
  "version": "1.0",
  "vendorName": "FTS",
  "productName": "FL001",
  "system": [],
  "locked": false,
  "dateCreated": "2017-06-28T20:31:27.003Z",
  "dateModified": "2017-06-28T20:31:27.003Z"
}

Path Params

ref
string
required

App profile's name or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:read
Suggest Edits

Modify app profile

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.connio.com/v3/appprofiles/ref
curl --request PUT \
  --url https://api.connio.com/v3/appprofiles/ref
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.connio.com/v3/appprofiles/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/appprofiles/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.connio.com/v3/appprofiles/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/appprofiles/ref"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_apf_923984090658849546",
  "accountId": "_acc_923380065327020781",
  "name": "FireWeatherControl",
  "friendlyName": "Fire/Weather Control Center",
  "description": "Fire weather control",
  "tags": [
    "demo"
  ],
  "version": "1.1",
  "vendorName": "FTS",
  "productName": "KLT01",
  "system": [],
  "locked": false,
  "dateCreated": "2017-06-28T20:31:27.003Z",
  "dateModified": "2017-06-28T20:42:53.694Z"
}

Path Params

ref
string
required

App profile's name or id.

Body Params

name
string

Account wide unique, URL friendly name of the app profile.

friendlyName
string

Human friendly name of the app profile.

description
string

App profile description.

tags
array of strings

The list of the tags associated with the app profile.

version
string

App version.

vendorName
string

Vendor or developer of the solution.

productName
string

Name of the actual solution/product.

imageUrl
string

Link to app logo.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:modify

Tip

You can remove optional fields by setting them to tags=[], description="", version="", vendorName="", productName="", and imageUrl="".

Suggest Edits

Delete app profile

 

Basic Auth

 Authentication is required for this endpoint.
deletehttps://api.connio.com/v3/appprofiles/ref
curl --request DELETE \
  --url https://api.connio.com/v3/appprofiles/ref
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.connio.com/v3/appprofiles/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/appprofiles/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.connio.com/v3/appprofiles/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/appprofiles/ref"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "nrOfItems": 1
}

Path Params

ref
string
required

App profile's name or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:delete

Rule

  • You cannot delete a base app profile with child. You must delete the child first.
  • You cannot delete a app profile with existing devices generated from it. You must delete the app first.

An App instance resource represents a single app entity.

Resource Attributes

Attribute Description
id A 23 to 26 characters long string that uniquely identifies this app.
accountId The unique id of the account that created this app.
name Account wide unique, URL friendly name of the app.
friendlyName Human friendly name of the app.
profileId Id of the app profile that this app is generated from.
description Optional. A brief about this app.
tags Optional. Tags associated with this app.
dataStore Optional. App specific, customer managed external data store information to stream app data.
locked if locked, entity cannot be modified, deleted.
dateCreated The date that this api client was created in ISO 8601 format.
dateModified The date that this api client was modified in ISO 8601 format.
{
  "id": "_app_530976712669455460",
  "accountId": "_acc_530308970920181397",
  "name": "atm-monitor",
  "friendlyName": "ATM Monitoring App",
  "profileId": "_apf_923380075976645455",
  "description": "Remotely monitor connected ATMs.",
  "tags": [
    "test"
  ],
  "locked": false,
  "dateCreated": "2017-04-29T12:54:40.010Z",
  "dateModified": "2017-04-29T12:54:40.010Z"
}
Suggest Edits

Create app

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/apps
curl --request POST \
  --url https://api.connio.com/v3/apps
var request = require("request");

var options = { method: 'POST', url: 'https://api.connio.com/v3/apps' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apps")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.connio.com/v3/apps");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apps"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_app_923380075974051984",
  "accountId": "_acc_923380065327020781",
  "name": "FireWeatherControl",
  "friendlyName": "Fire Weather Control System",
  "profileId": "_apf_923380075976645455",
  "description": "",
  "locked": true,
  "dateCreated": "2017-06-28T00:31:24.273Z",
  "dateModified": "2017-06-28T00:31:24.273Z"
}

Body Params

name
string
required

Account wide unique, URL friendly name of the app.

friendlyName
string

Human friendly name of the app.

profile
string
required

Id or name of the app profile that this app will be generated from.

description
string

Description, notes, etc...

tags
array of strings

The list of the tags associated with the app.

dataStore
object

App specific, customer managed external data store information.

 
 

Api Key Authorization

Required Fields Values
Context type Account
Scopes app:create
Suggest Edits

List apps

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/apps
curl --request GET \
  --url https://api.connio.com/v3/apps
var request = require("request");

var options = { method: 'GET', url: 'https://api.connio.com/v3/apps' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apps")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/apps");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apps"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "total": 2,
  "itemCount": 2,
  "numOfPages": 1,
  "pageNo": 1,
  "skip": 0,
  "results": [
    {
      "id": "_app_923380075974051984",
      "accountId": "_acc_923380065327020781",
      "name": "Default",
      "friendlyName": "Default app",
      "profileId": "_apf_923380075976645455",
      "description": "Account's default app. All newly created devices will be plugged into this app by default.",
      "locked": true,
      "dateCreated": "2017-06-28T00:31:24.273Z",
      "dateModified": "2017-06-28T00:31:24.273Z"
    },
    {
      "id": "_app_924010331560692480",
      "accountId": "_acc_923380065327020781",
      "name": "FireWeatherControl",
      "friendlyName": "Fire Weather Control System",
      "profileId": "_apf_923984090658849546",
      "locked": false,
      "dateCreated": "2017-06-28T21:23:35.162Z",
      "dateModified": "2017-06-28T21:23:35.162Z"
    }
  ]
}

Query Params

tags
string

Filters apps by tag. Comma separated list of tags.

profile
string

Finds all apps immediately inherited from app profile given by id or name.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes app:read

Tip

You can use logical operator for tag filtering. If you add "-" operator in front of a tag, it implies a NEGATE; if you add "^" operator to the end of a tag, it implies an OR.

For example, if you like to see all the devices tagged as "house", and tagged as either "kitchen", "bathroom", or "bedroom" but not tagged as "mansion" you should set a tag filter as:

?tags=house, kitchen^, bathroom^, bedroom^, -mansion

Suggest Edits

View app details

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/apps/ref
curl --request GET \
  --url https://api.connio.com/v3/apps/ref
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/apps/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apps/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/apps/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apps/ref"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_app_924010331560692480",
  "accountId": "_acc_923380065327020781",
  "name": "FireWeatherControl",
  "friendlyName": "Fire Weather Control System",
  "profileId": "_apf_923984090658849546",
  "locked": false,
  "dateCreated": "2017-06-28T21:23:35.162Z",
  "dateModified": "2017-06-28T21:23:35.162Z"
}

Path Params

ref
string
required

App's name or id.

Query Params

is_a
string

App profile reference to make sure that the app is a given type. Returns 404 if not belong to this type.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes app:read
Suggest Edits

Modify app

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.connio.com/v3/apps/ref
curl --request PUT \
  --url https://api.connio.com/v3/apps/ref
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.connio.com/v3/apps/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apps/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.connio.com/v3/apps/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apps/ref"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_app_924010331560692480",
  "accountId": "_acc_923380065327020781",
  "name": "FireWeatherControl",
  "friendlyName": "Fire Weather Control System",
  "profileId": "_apf_923984090658849546",
  "description": "Demo app",
  "tags": [
    "demo"
  ],
  "locked": false,
  "dateCreated": "2017-06-28T21:23:35.162Z",
  "dateModified": "2017-06-28T21:40:00.387Z"
}

Path Params

ref
string
required

App's name or id.

Body Params

name
string

Account wide unique, URL friendly name of the app.

friendlyName
string

Human friendly name of the app.

description
string

Description, notes, etc...

tags
array of strings

The list of the tags associated with the app.

dataStore
string

User defined identifiers assigned to the app.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes app:modify

Tip

You can remove optional fields by setting them to tags=[], description="", and datastore={}.

Rule

Normally locked apps (e.g. Default app) cannot be modified. As a convenience, Connio v3 API allow users to modify only the datastore field of Default app.

Suggest Edits

Delete app

 

Basic Auth

 Authentication is required for this endpoint.
deletehttps://api.connio.com/v3/apps/ref
curl --request DELETE \
  --url https://api.connio.com/v3/apps/ref
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.connio.com/v3/apps/ref' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/apps/ref")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.connio.com/v3/apps/ref");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/apps/ref"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "nrOfItems": 1
}

Path Params

ref
string
required

App's name or id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes app:delete

Rule

Default app cannot be deleted.

Suggest Edits

Properties

 

A Property instance resource represents a single property entity. Since properties always belong to some owner entity (i.e. app profile or device profile), they are usually accessed through their parent's path (you can access a property resource directly by id for some operations; see operations section).

Admin vs Data API

Properties resource represents different meanings when used from Admin and Data services APIs.

When used from Admin Services API, it represents the definition or metadata of a property. The user can create new properties, modify and delete existing ones through this service.

When used from Data Services API, it represents the data value stored within a property. The user can read and write data from/into properties through this service.

Please note that when we say property we refer to the property definition created within a profile entity which is uniquely identified by an id. On the other had, when we say device or app property, we refer to the instance of this property created under an object which is uniquely identified by both its parent object's id and its definition's id.

Resource Attributes

Attribute Description
id A 23 to 26 characters long string that uniquely identifies this property.
accountId The unique id of the account that created this property.
name A name that uniquely identifies the property among its siblings. Unlike other resources, property name cannot be used as slug since the name is only context sensitive.
friendlyName Human friendly name of the property.
ownerId The entity owning the property definition. Owner entity can be device profile, or app profile.
type Defines the data type this property can store. Can be number, waypoint, boolean, string, enum, object, file or blob. See supported data types table for details.
access Can be one of the following private, protected and public. See the access types section below for details.
publish Can be always, changed or never. When always, this property value is published back to the device if set/written using an external API key (i.e not device key). When changed, it is published only when the value is changed. You can create server-side and device-side properties using this attribute. All properties with publish value set to never are considered server-side attribute.
inherited true or false. Device and app profiles can be based on other profiles (of their type) when created. The properties of the base profile show up as inherited under the child profile.
qualifiedName A name that uniquely identifies this property within its owner account context. Qualified name is used in object property queries to eliminate name ambiguity.
measurement Optional. Measurement is a convenience for numeric properties (number type). When set, it enriches the visualization and conversion capabilities of the property.
locked if locked, entity cannot be modified, deleted.
dateCreated The date that this property was created in ISO 8601 format.
dateModified The date that this property was modified in ISO 8601 format.

Access Types Explained

It is very important to understand the role of Api Keys when interacting with properties. Api keys convey the identity of the requesters. When a requester interacts with a device property using the device key, the requester is given full privilege - requester is considered the device itself. Otherwise it is considered an external client and has to abide by the access rules. Same rule applies to app properties as well.

Private Property

This type property can be only be only read and written by device key. This access level should be used to store device confidential data on the platform securely. It cannot be set to publish = true. All device methods can access private properties and use them.

Protected Property (read-only)

All api client and user keys with device:read-data scope are allowed to read this property. It can only be written using device key. Can be set to publish=true.

Public Property (read-write)

All api client and user keys with device:read-data scope can read this property and all client and user keys with device:write-data scope can write into this property. When written by external entities (i.e. other than the device itself) the value automatically sent to the physical device if connected to Connio MQTT broker. Can be set to publish=true.

Important

MQTT broker does not cache the commands sent to devices if the device is not online at the time of transmission. If your data is mission critical, we suggest to establish a custom feedback mechanism to make sure that your data arrived to its destination. A custom feedback mechanism can be easily built using additional properties and some edge device logic.

Supported Data Types

Type Purpose Max Size
Number It stores numeric values including integers and doubles. N/A
Waypoint It is a special case of data point where the data value is a geo-coordinate. This type is used to store trips. Designed to be used for asset tracking applications. zone field is limited with String data type limit.
Boolean It stores boolean values, i.e. true, false. N/A
String It stores textual data. Maximum 1 KiB.
Enum It stores numeric or textual predefined values such as states (e.g. "Started", "Stopped"). It can contain maximum 100 items, each textual item can be max 64 char long.
(Json) Object It stores composite data in JSON format. It can hold any user defined valid JSON structure. Mostly used for storing configuration values or complex data objects where simple data types are not enough. Maximum 500 KiB.
File It stores files in any format. File size can be maximum 256 MiB.
Blob It stores binary data in base64 format. Maximum 1 MiB.
{
  "id": "_prp_875223872477401419",
  "accountId": "_acc_873046106083527769",
  "ownerId": "_dpf_873048732840926433",
  "name": "Temperature",
  "friendlyName": "Temperature",
  "tags": [
    "test"
  ],
  "type": "number",
  "access": "protected",
  "publish": "always",
  "measurement": {
    "type": "temperature",
    "unit": {
      "label": "Temperature",
      "symbol": "ºC"
    }
  },
  "retention": {    
    "type": "historical",
    "lifetime": "3months",
    "capacity": 100000,
    "condition": {
      "when": "always"
    }
  },
  "boundaries": {   
      "min": -25.5,
      "max": 65.5
  },
  "locked": false,
  "dateCreated": "2017-04-22T13:53:36.035Z",
  "dateModified": "2017-04-22T13:53:36.035Z"
}

Measurement

This attribute is used if and only if the property type is number. Its type attribute can be one of the following values:

Type Unit
custom unit object attribute can be freely set by the user.
time tbd
acceleration tbd
currency tbd
electricity tbd
fitnessEnergy tbd
weight tbd
lengthDistance tbd
relativeHumidity tbd
light tbd
pressure tbd
speed tbd
soundsLevel tbd
temperature tbd
percentage tbd

Boundaries

As its name suggests, boundaries defines the limits of values each property should expect. It is mainly used for data validation and/or data visualization. Boundaries are optional. A property might have zero or one boundaries.

For example, you can use boundaries to set the limits of a temperature sensor reading. Readings that are not within the given boundary values will be discarded by the system automatically. This will prevent the property data set from being corrupted by unexpected values when device malfunctions.

Attribute Description
Limit type Can be range, size, set, and geofence. Different limit types are used for different property types. See below for a full list.

Limit types per property types:

Property Type Limit Type Possible values Example
number range any numeric value in min and max attributes "min": 12.0, "max": 18981.238
string size any positive integer value in bytes "size": 250000
object size any positive integer value in bytes "size": 250000
enum set list of accepted string or numeric values "enum": { "set": ["start", "stop", "pause"] } or "enum": { "set": [1, 2, 3] }
waypoint geofence lat, lon, radius (in Km), inside (true or false) { "lat":34.7587, "lon": 49.9999, "radius": 50, "inside": true }
blob size any positive integer value, in bytes "size": 20000000
file size any positive integer value, in bytes "size": 20000000

If no boundaries is set, default property boundaries takes effect. See Supported Data Types above.

Retention Policy

Retention policy governs the rules around the retention of property values. It defines when and how long incoming data should be persisted. Unlike boundaries, each property must have at least one retention i.e. default retention policy. Default retention policy cannot be deleted.

It consists of the following attributes:

Attribute Description
type historical- store data in the system time-series database, mostrecent - store only the most recent value. A retention policy can be set along with historical types.
lifetime Used when type is historical. Must match with the following pattern: unlimited or n+ days or n+months or n+years where n is a positive integer - e.g. 3months. All data points older than this value will be deleted automatically to save space.
capacity Used when type is historical. It specifies the maximum number of data points this property can store. Can be 0 for unlimited or any positive integer. Default value is 100000.
condition Used when type is historical to indicate when the value will be stored. It consists of when and value attributes. when can be always, changed or changedx for numeric values only. If when is set to changedx, value is set to a percentage value between 1 to 100.

Default retention policy at Property creation:

{
  "type": "historical",
  "lifetime": "3months",
  "capacity": 100000,
  "condition": {
    "when": "always"
  }
}

Another example:

{
"retention": {
	"type": "historical",
	"lifetime": "12months",
	"capacity": 3000000,
	"condition": {
	  "when": "changedx",
	  "value": 41
	}
}
Suggest Edits

Create property

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/properties
curl --request POST \
  --url https://api.connio.com/v3/properties
var request = require("request");

var options = { method: 'POST', url: 'https://api.connio.com/v3/properties' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/properties")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.connio.com/v3/properties");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/properties"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_prp_928387658325088963",
  "accountId": "_acc_924329848168362343",
  "ownerId": "_dpf_924329907144716043",
  "name": "PersonCount",
  "friendlyName": "Person Counter",
  "inherited": false,
  "qualifiedName": "sample$personcount",
  "tags": [
      "test"
  ],
  "type": "number",
  "access": "protected",
  "publish": "always",
  "retention": {      
      "type": "historical",
      "lifetime": "3months",
      "capacity": 100000,
      "condition": {
          "when": "always"
      }
  },
  "boundaries": {
    "min": 0,
    "max": 9999
  },
  "locked": false,
  "dateCreated": "2017-07-04T22:20:33.176Z",
  "dateModified": "2017-07-04T22:20:33.176Z"
}

Body Params

name
string
required

Profile wide unique, URL friendly name of the app.

friendlyName
string

Human friendly name of the property for display purposes.

ownerId
string
required

Id of the profile that the new property will be added to.

type
string
required

Property type.

access
string
required

Access designator of the property. Can be private, protected and public.

publish
string
required

Publish property value to device/app mirror. Can be always, never or changed.

description
string

Description, notes, etc...

tags
array of strings

The list of the tags associated with the property.

boundaries
object

Property boundaries.

 
retention
object

Property retention.

 
measurement
object

Engineering measurement type.

 
 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:modify, or deviceprofile:modify

Tip

Alternatively you can create properties as follows:

POST .../deviceprofiles/{ref}/properties
POST .../appprofiles/{ref}/properties

Suggest Edits

List properties

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/properties
curl --request GET \
  --url 'https://api.connio.com/v3/properties?ownerId=ownerId'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/properties',
  qs: { ownerId: 'ownerId' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/properties?ownerId=ownerId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/properties?ownerId=ownerId");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/properties"

querystring = {"ownerId":"ownerId"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "total": 4,
  "itemCount": 4,
  "numOfPages": 1,
  "pageNo": 1,
  "skip": 0,
  "results": [
    {
      "id": "_prp_924329914680031017",
      "accountId": "_acc_924329848168362343",
      "ownerId": "_dpf_924329907144716043",
      "name": "Temperature",
      "friendlyName": "Temperature",
      "inherited": false,
      "qualifiedName": "sample$temperature",
      "tags": [
        "test"
      ],
      "type": "number",
      "access": "protected",
      "publish": "always",
      "measurement": {
        "type": "temperature",
        "unit": {
          "label": "Temperature",
          "symbol": "ºC"
        }
      },
      "retention": {        
        "type": "historical",
        "lifetime": "3months",
        "capacity": 100000,
        "condition": {
          "when": "always"
        }
      },
      "boundaries": {
        "range": {
          "min": -25.5,
          "max": 65.5
        }
      },
      "locked": false,
      "dateCreated": "2017-06-29T07:58:32.439Z",
      "dateModified": "2017-06-29T07:58:32.439Z"
    },
    {
      "id": "_prp_924329872563934767",
      "accountId": "_acc_924329848168362343",
      "ownerId": "_dpf_924329872560735560",
      "name": "LastOut",
      "friendlyName": "Last Outgoing Data",
      "inherited": false,
      "qualifiedName": "device$lastout",
      "description": "Last property updated with outgoing data (platform->device)",
      "type": "string",
      "access": "protected",
      "publish": "changed",
      "retention": {
        "context": {
          "type": "default",
          "id": ""
        },
        "type": "mostrecent",
        "condition": {
          "when": "always"
        }
      },
      "locked": false,
      "dateCreated": "2017-07-02T17:24:13.973Z",
      "dateModified": "2017-07-02T17:24:13.973Z"
    },
    {
      "id": "_prp_924329872558288999",
      "accountId": "_acc_924329848168362343",
      "ownerId": "_dpf_924329872560735560",
      "name": "LastIn",
      "friendlyName": "Last Incoming Data",
      "inherited": false,
      "qualifiedName": "device$lastin",
      "description": "Last property updated with incoming data (device->platform)",
      "type": "string",
      "access": "protected",
      "publish": "changed",
      "retention": {
        "context": {
          "type": "default",
          "id": ""
        },
        "type": "mostrecent",
        "condition": {
          "when": "always"
        }
      },
      "locked": false,
      "dateCreated": "2017-07-02T17:24:13.969Z",
      "dateModified": "2017-07-02T17:24:13.969Z"
    },
    {
      "id": "_prp_924329872563120846",
      "accountId": "_acc_924329848168362343",
      "ownerId": "_dpf_924329872560735560",
      "name": "Active",
      "friendlyName": "Activity Status",
      "inherited": false,
      "qualifiedName": "device$active",
      "type": "enum",
      "access": "protected",
      "publish": "changed",
      "retention": {
        "context": {
          "type": "default",
          "id": ""
        },
        "type": "historical",
        "lifetime": "3months",
        "capacity": 100000,
        "condition": {
          "when": "always"
        }
      },
      "boundaries": {
        "set": [
          "active",
          "inactive",
          "unknown"
        ]
      },
      "locked": false,
      "dateCreated": "2017-07-02T17:24:13.934Z",
      "dateModified": "2017-07-02T17:24:13.934Z"
    }
  ]
}

Query Params

ownerId
string
required

Owner entity id (e.g. device profile).

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:read or deviceprofile:read

Tip

Alternatively you can list properties as follows:

GET .../deviceprofiles/{ref}/properties
GET .../appprofiles/{ref}/properties

Suggest Edits

View property details

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/properties/id
curl --request GET \
  --url https://api.connio.com/v3/properties/id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/properties/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/properties/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/properties/id");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/properties/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "_prp_924329872557368571",
    "accountId": "_acc_924329848168362343",
    "ownerId": "_dpf_924329872556787818",
    "name": "ConnectionStatus",
    "friendlyName": "Connectivity Status",
    "qualifiedName": "connecteddevice$connectionstatus",
    "type": "enum",
    "access": "protected",
    "publish": "changed",
    "retention": {        
      "type": "historical",
      "lifetime": "3months",
      "capacity": 100000,
      "condition": {
          "when": "always"
      }
    },
    "boundaries": {
      "set": [
          "online",
          "offline"
      ]
    },
    "locked": false,
    "dateCreated": "2017-07-02T17:24:13.975Z",
    "dateModified": "2017-07-02T17:24:13.975Z"
}

Path Params

id
string
required

Property's id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:read or deviceprofile:read
Suggest Edits

Modify property

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.connio.com/v3/properties/id
curl --request PUT \
  --url https://api.connio.com/v3/properties/id
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.connio.com/v3/properties/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/properties/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.connio.com/v3/properties/id");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/properties/id"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_prp_928387658325088963",
  "accountId": "_acc_924329848168362343",
  "ownerId": "_dpf_924329907144716043",
  "name": "PersonCount",
  "friendlyName": "Person Counter",
  "inherited": false,
  "qualifiedName": "sample$personcount",
  "tags": [
      "test"
  ],
  "type": "number",
  "access": "protected",
  "publish": "always",
  "retention": {      
      "type": "historical",
      "lifetime": "3months",
      "capacity": 100000,
      "condition": {
          "when": "always"
      }
  },
  "boundaries": {
      "range": {
          "min": 0,
          "max": 9999
      }
  },
  "locked": false,
  "dateCreated": "2017-07-04T22:20:33.176Z",
  "dateModified": "2017-07-04T22:20:33.176Z"
}

Path Params

id
string
required

Property's id.

Body Params

name
string

Profile wide unique, URL friendly name of the app.

friendlyName
string

Human friendly name of the property for display purposes.

access
string

Access designator of the property. Can be private, protected and public.

publish
string

Publish property value to device/app mirror. Can be always, never or changed.

description
string

Description, notes, etc...

tags
array of strings

The list of the tags associated with the property.

boundaries
object

Property boundaries.

 
retention
object

Property retention.

 
measurement
object

Engineering measurement type.

 
 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:modify, or deviceprofile:modify

Tip

You can remove optional fields by setting them to tags=null, description=null, retention=null, boundaries=null, and measurements=null.

Suggest Edits

Delete property

 

Basic Auth

 Authentication is required for this endpoint.
deletehttps://api.connio.com/v3/properties/id
curl --request DELETE \
  --url https://api.connio.com/v3/properties/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.connio.com/v3/properties/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/properties/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.connio.com/v3/properties/id");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/properties/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "nrOfItems": 1
}

Path Params

id
string
required

Property's id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:modify, or deviceprofile:modify
 

A Method instance sub resource represents a method entity. Since methods always belong to some owner entity (i.e. app profile or device profile), they are usually accessed through their parent's path (you can access a property resource directly by id for some operations; see methods section).

Admin vs Data API

Methods resource represents different meanings when used from Admin and Data services APIs.

When used from Admin Services API, it represents the definition or metadata of a method. The user can create new methods, modify and delete existing ones through this service.

When used from Data Services API, it provides information about the execution performance of the device or app method - see Device State object.

Please note that when we say method we refer to the method definition created within a profile entity which is uniquely identified by an id. On the other had, when we say device or app method, we refer to the instance of this method created under an object which is uniquely identified by both its parent object's id and its definition's id.

Resource Attributes

Attribute Description
id A 23 to 26 characters long string that uniquely identifies this property.
accountId The unique id of the account that created this method.
name A name that uniquely identifies the method among its siblings. Unlike other resources, method name cannot be used as slug since the name is only context sensitive.
friendlyName Human friendly name of the method.
ownerId The entity owning the method definition. Owner entity can be device profile, or app profile.
access Can be either private, protected, or public. See the access types section below for details.
methodImpl Method implementation object. See below.
inherited true or false. Device and app profiles can be based on other profiles (of their type) when created. The methods of the base entity show up as inherited under the new entity.
qualifiedName A name that uniquely identifies this method within its owner account context. Qualified name is used in object method queries to eliminate name ambiguity.
locked if locked, entity cannot be modified, deleted.
dateCreated The date that this method was created in ISO 8601 format.
dateModified The date that this method was modified in ISO 8601 format.
{
    "id": "_mtd_933649803812708268",
    "accountId": "_acc_924329848168362343",
    "ownerId": "_dev_924329922537879076",
    "name": "getOperationStatus",
    "friendlyName": "getOperationStatus",
    "inherited": false,
    "qualifiedName": "temp.sensor.1$getoperationstatus",
    "access": "public",
    "methodImpl": {       
      "funcBody": "done(null, value == 1 ? \"running\" : \"stopped\");",
      "script": "javascript"
    },
    "locked": false,
    "dateCreated": "2017-07-12T04:35:29.801Z",
    "dateModified": "2017-07-12T04:35:29.801Z"
}

methodImpl object

Defines the implementation of the method. Currently only JavaScript implementations are accepted. Each method has at least one implementation.

Attribute Description
funcBody Methods are standard JavaScript functions with the following signature: function <method name>(value) { <func body> }. This attribute holds the function body segment. Function body is the place where the developer implements its device logic. Function signature on the other hand cannot be modified.
script Script language type. Connio only supports JavaScript language (ECMAScript ECMA-262) at the moment; this attribute must be set to javascript.

See Writing Method Implementations for details.

Access Types Explained

Methods can be called from other methods, public methods can be called from external clients.

Private Method

A private method can be accessed from the methods of the same object. Child object cannot call its parent's private methods. It cannot be overriden by child object, nor be called by external clients.

Protected Method

A protected method can be accessed from the methods of the same object. Child object can call its parent's protected methods. It can be overriden by child object, but it cannot be called by external clients.

Public Method

A public method can be accessed from the methods of the same object and its child. It can be overriden by child object. It can be executed by any external client with device:execute scope.

Public methods can be called remotely to send commands to devices, or get aggregate data about the devices (e.g. dashboard).

Max Method Execution Time

Default method execution time is set to 5 seconds for standard accounts. If a method takes longer than the allowed time, or throws an exception, the method instance is automatically quarantined / disabled for its owning device or app. In such case you need to explicitly enable it to continue working. All method errors are listed under device/app log. Note that you can get more visibility about your method's sanity in the device/app log by turning your device/app status to debug while testing.

Suggest Edits

Create method

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.connio.com/v3/methods
curl --request POST \
  --url https://api.connio.com/v3/methods
var request = require("request");

var options = { method: 'POST', url: 'https://api.connio.com/v3/methods' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/methods")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.connio.com/v3/methods");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/methods"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "_mtd_935196559560581731",
    "accountId": "_acc_924329848168362343",
    "ownerId": "_dpf_935003384677437527",
    "name": "getOperationStatus",
    "friendlyName": "getOperationStatus",
    "inherited": false,
    "qualifiedName": "keiffel$getoperationstatus",
    "access": "public",
    "methodImpl": {        
        "funcBody": "done(null, value);",
        "script": "javascript"
    },
    "locked": false,
    "dateCreated": "2017-07-14T07:48:37.455Z",
    "dateModified": "2017-07-14T07:48:37.455Z"
}

Body Params

name
string
required

Profile wide unique, URL friendly name of the method.

friendlyName
string

Human friendly name of the method for display purposes.

ownerId
string
required

Id of the profile that the new method will be added to.

access
string
required

Access designator of the method. Can be private, protected and public.

description
string

Description, notes, etc...

tags
array of strings

The list of the tags associated with the method.

methodImpl
object

Method implementation.

 
 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:modify, or deviceprofile:modify

Tip

Alternatively you can create methods as follows:

POST .../deviceprofiles/{ref}/methods
POST .../appprofiles/{ref}/methods

Suggest Edits

List methods

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/methods
curl --request GET \
  --url 'https://api.connio.com/v3/methods?ownerId=ownerId'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/methods',
  qs: { ownerId: 'ownerId' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/methods?ownerId=ownerId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/methods?ownerId=ownerId");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/methods"

querystring = {"ownerId":"ownerId"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "total": 1,
  "itemCount": 1,
  "numOfPages": 1,
  "pageNo": 1,
  "skip": 0,
  "results": [
    {
      "id": "_mtd_935196559560581731",
      "accountId": "_acc_924329848168362343",
      "ownerId": "_dpf_935003384677437527",
      "name": "getOperationStatus",
      "friendlyName": "getOperationStatus",
      "inherited": false,
      "qualifiedName": "keiffel$getoperationstatus",
      "access": "public",
      "methodImpl": {
          "funcBody": "return value;",
          "script": "javascript"
      },
      "locked": false,
      "dateCreated": "2017-07-14T07:48:37.455Z",
      "dateModified": "2017-07-14T07:48:37.455Z"
    }
  ]
}

Query Params

ownerId
string
required

Owner profile id or name.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:read or deviceprofile:read

Tip

Alternatively you can list methods as follows:

GET .../deviceprofiles/{ref}/methods
GET .../appprofiles/{ref}/methods

Suggest Edits

View method details

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.connio.com/v3/methods/id
curl --request GET \
  --url https://api.connio.com/v3/methods/id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.connio.com/v3/methods/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/methods/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.connio.com/v3/methods/id");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/methods/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_mtd_935196559560581731",
  "accountId": "_acc_924329848168362343",
  "ownerId": "_dpf_935003384677437527",
  "name": "getOperationStatus",
  "friendlyName": "getOperationStatus",
  "inherited": false,
  "qualifiedName": "keiffel$getoperationstatus",
  "access": "public",
  "methodImpl": {   
    "funcBody": "return value;",
    "script": "javascript"
  },
  "locked": false,
  "dateCreated": "2017-07-14T07:48:37.455Z",
  "dateModified": "2017-07-14T07:48:37.455Z"
}

Path Params

id
string
required

Method's id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:read or deviceprofile:read
Suggest Edits

Modify method

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.connio.com/v3/methods/id
curl --request PUT \
  --url https://api.connio.com/v3/methods/id
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.connio.com/v3/methods/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/methods/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.connio.com/v3/methods/id");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/methods/id"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "_mtd_935196559560581731",
  "accountId": "_acc_924329848168362343",
  "ownerId": "_dpf_935003384677437527",
  "name": "getOperationStatus",
  "friendlyName": "getOperationStatus",
  "inherited": false,
  "qualifiedName": "keiffel$getoperationstatus",
  "access": "public",
  "methodImpl": {        
      "funcBody": "return value;",
      "script": "javascript"
  },
  "locked": false,
  "dateCreated": "2017-07-14T07:48:37.455Z",
  "dateModified": "2017-07-14T07:48:37.455Z"
}

Path Params

id
string
required

Method's id.

Body Params

name
string

Profile wide unique, URL friendly name of the method.

friendlyName
string

Human friendly name of the method for display purposes.

access
string

Access designator of the method. Can be private, protected and public.

description
string

Description, notes, etc...

tags
array of strings

The list of the tags associated with the method.

methodImpl
object

Method implementation.

 
 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:modify, or deviceprofile:modify

Tip

You can remove optional fields by setting them to tags=null, description=null, and methodImpl=null.

Suggest Edits

Delete method

 

Basic Auth

 Authentication is required for this endpoint.
deletehttps://api.connio.com/v3/methods/id
curl --request DELETE \
  --url https://api.connio.com/v3/methods/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.connio.com/v3/methods/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.connio.com/v3/methods/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.connio.com/v3/methods/id");

xhr.send(data);
import requests

url = "https://api.connio.com/v3/methods/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "nrOfItems": 1
}

Path Params

id
string
required

Method's id.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes appprofile:modify, or deviceprofile:modify
Suggest Edits

Enable/Disable device method

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.connio.com/v3/devices/device_ref/methods/method_ref
{
    "disabled": false
}
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

device_ref
string
required

Device reference.

method_ref
string
required

Method reference.

 

Api Key Authorization

Required Fields Values
Context type Account
Scopes device:modify

Allows you to alert involving parties when device or app level anomalies arise such as device went offline, temperature is above 35°C. Like similar mechanisms, Alert consists of events, checks/conditions and actions.

Alerts can be created at device, app, app profile or device profile level. When created at profile level, all devices and apps generated from this profile automatically gets a copy of the alert definition.

Unlike property and method, alert is not considered a pure element of the object model, therefore it cannot be inherited by child profiles.

See Alert Entity for details.

Resource Attributes

Attribute Description
id A 23 to 26 characters long string that uniquely identifies this alert.
name A name that uniquely identifies the alert among its siblings. Unlike other resources, alert name cannot be used as slug since the name is only context sensitive.
friendlyName Human friendly name of the alert.
ownerId The entity owning the method. Owner entity can be device profile or device.
description Description of this alert. Optional.
tags Tags attached to this alert.
triggerId Id of the property that this alert is bound to.
ttl Time-to-live period for the data point that will trigger the alert. For example if TTL is 30s then the system raise the alert if and only if the incoming data point's source time (or capture time) is within 30 seconds time window. Possible units are d for day, h for hour, min for minute, s for second, and ms for millisecond.
status Can be enabled and disabled. Default enabled.
metric Metric calculation formula. Simple property value (i.e "value"), or aggregators such as avg(), count(), min(), max(), and sum() over a period can be used to calculate its value. If the property type is waypoint, it is possible to use geoFence() function to create, well, a geo-fence. Metric is used in combination with condition object expression to trigger the alert. You can find usage samples below.
conditions List of conditions that will trigger the alert. see Conditon object below.
recover Single alert handler that will be executed after alert is recovered.
notifications List of notifications that will notify the related parties. see Notification object below
locked if locked, entity cannot be modified, deleted.
dateCreated The date that this alert was created in ISO 8601 format.
dateModified The date that this alert was modified in ISO 8601 format.

Aggregate Functions

Aggregators can be used if and only if the given property's retention policy is historical.

{
    "id": "_ale_392736003857137341",
    "accountId": "_acc_392726790711190051",
    "ownerId": "_dpf_392727069718560420",
    "name": "machine.temperature.alert",
    "friendlyName": "Machine temperature alert",
    "description": "Raised when the machine temperature average reaches to certain threshold over 16 minute period",
    "tags": [
        "temperature"
    ],
    "triggerId": "_prp_392727127019887390",
    "status": "enabled",
    "metric": "avg(16min)",
    "recover": {
        "key": "H0",
        "notification": "back_to_normal"
    },
    "conditions": [
        {
            "severity": "warning",
            "expression": {
                "operation": "gt",
                "value": 45.2
            },
            "handlers": [
                {
                    "key": "H1",
                    "notification": "logme",
                    "next": "H2",
                    "timeout": "1 minute"
                },
                {
                    "key": "H2",
                    "notification": "emailme",
                    "next": "H1",
                    "timeout": "1 minute"
                }
            ]
        },
        {
            "severity": "critical",
            "expression": {
                "operation": "gt",
                "value": 65.1
            },
            "handlers": [
                {
                    "key": "H1",
                    "notification": "logme",
                    "next": "H2",
                    "timeout": "1 minute"
                },
                {
                    "key": "H2",
                    "notification": "turnoff",
                    "next": "H1",
                    "timeout": "1 minute"
                }
            ]
        }
    ],
    "notifications": [
        {
            "action": "log",
            "name": "logme",
            "level": "info",
            "message": "${device.name}'s temperature exceeded its limit"
        },
        {
            "action": "email",
            "name": "emailme",
            "to": "admin@test.com",
            "subject": "${property.name} property on device ${device.name} is above 45°C",
            "message": "Current ${property.name} value is ${value}°C; it was ${last_value}°C before. Shutdown the engine if goes above 65°C."
        },
        {
            "action": "method",
            "name": "turnoff",
            "method": "_mtd_392727204042600572",
            "parameter": "stop"
        },
        {
            "action": "email",
            "name": "back_to_normal",
            "to": "admin@test.com",
            "subject": "${alert.name} incident is recovered",
            "message": "Everything back to normal for ${device.name}"
        }
    ],
    "locked": false,
    "dateCreated": "2018-06-26T20:56:20Z",
    "dateModified": "2018-06-26T20:56:20Z"
}

Condition Object

A condition is a value object and consists of the following attributes:

Attribute Description
severity Can be critical, warning, and notification.
expression Contains an expression that yields a scalar or boolean value. Non zero scalar values and true executes the given notifications. Consists of operation and value fields. operation fields can be eq, lt, lte, gte, gt, and match (for case insensitive text comparison). value holds the threshold value that will be compared to the metric value using the comparison operator specified in operation field. For example, if metric is avg(15min) for a temperature property, and expression is gt with value 50.0, then the full expression should be evaluated by the system as average(temperature, 15min) > 50.0.
handlers Sequence of notifications will be used by this condition to alert. The given notifications should exist in the alert notification list.

See Alert Entity for alert mechanism internals.

Notification Object

A notification is a value object and consists of the following attributes:

Attribute Description
name Alert wide unique name of the notification.
action Can be email, sms, method, webhook, or log.
message Message of the notification. Can contain variables.
.... Notification type specific attributes will follow. See below.

Possible notification types are:

...
"notifications": [
	{
    "name": "Email-Notif-Sample",
    "action": "email",
    "to": "myemail@mydomain.com",
    "subject": "${alert.name} is triggered",
    "message": "Hello world!"
  }
]
...
...
"notifications": [
	{
    "name": "SMS-Notif-Sample",
    "action": "sms",
    "to": "+1 604 2592423, +17789974545",
    "message": "${alert.name} is raised for ${device.name}"
  }
]
...

Telephone numbers must contain a country and area code.

...
"notifications": [
	{
    "name": "Method-Notif-Sample",
    "action": "method",
    "method": "_mtd_392727204042600572",
    "parameter": "off"
  }
]
...

Can be any type of public method belongs to the alert's object.

...
"notifications": [
	{
    "name": "Logging-Notif-Sample",
    "logLevel": "info",
    "action": "log",
    "message": "${device.name}'s 5 minutes temperature average is ${value}°C."
  }
]
...
...
"notifications": [
  { 
    "name": "slack", 
    "action": "webhook", 
    "message": "{ \"text\": \"${device.name} used ${value} KiB of data\" }", 
    "method": "post", "url": "https://hooks.slack.com/services/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"  
      }
]
...

Method can be either post, put and get. Message attribute holds the payload. If your payload is in JSON, all " characters should be escaped.

SECURITY

Alternatively you can include an attribute to your webhook notification called signatureKey. if this attribute is specified, then the header x-connio-signature will be included to the call (both get, post and put). As we're always sending text of json payloads (not post forms) we're concatenating the url with the payload and computing HMAC-SHA1 with the given signatureKey attribute as the key. Finally we encode the result in Base64 and this becomes the value of this header.