Suggest Edits

Xively platform APIs

 

The Xively platform is a collection of services that provide the essential building blocks for you to run a connected product business. This API guide outlines the components of the Xively platform that will power your IoT products.

The HTTP APIs described below are accessible to both you (an admin in a Xively account), and the end-users in your system (at a very scoped down level of access, documented in End-user role).

The HTTP APIs below allow you as a Xively admin to:

  • model the templates from which your devices, end-users and organizations will inherit their custom fields
  • create, manage, and provision credentials for devices and end-users
  • update the permission map between end-users and devices using organizations
  • retrieve and search device logs, regarding the operational health of your connected devices
  • retrieve timeseries messages that were sent over the MQTT broker with copies stored in Xively
  • send MQTT messages, logs, and timeseries messages over HTTP (though these operations are usually performed by devices and users, they are available to you over HTTP)

These APIs also allow your end-users to:

  • register themselves (and reset passwords) as users in your system through apps you build and control
  • log in through those apps to retrieve credentials with automatic access control over the appropriate devices and resources you've defined
  • autonomously claim permissions over devices that they've bought or received using association workflows
  • autonomously manage users, devices, and permissions that are placed under their scope of control by you as an administrator, using organizations

Looking for details on the message broker?

Your credentials also allow you, your end-users, and devices to communicate over Xively's best-in-class MQTT messaging service - but details on using the MQTT messaging service are documented over here.

Suggest Edits

Authentication

 

The HTTP APIs use a JSON web token (JWT), that are renewed during each API call and expire after 20 minutes of inactivity. Expiry times can be configured for your application, and this and much more on the deeper details are documented in Using JWTs.

For authenticating users via applications, the platform provides features to manage user access, eliminating the work of developing authentication and authorization features yourself. This includes login, ID storage (either email & password or OAuth token), password reset flows, and federated authentication using OpenID connect.

So how do I get my API access token?

When making platform API calls, authentication for admins and end-users is JWT-based.

JWTs are generated by the Xively Identity service, using the Identity service's /auth/login or /oauth2/callback endpoints. JWTs are further described in the docs.

You can use the following API calls in your own applications or services to perform the function of logging in an existing user identity and retrieving their management API (HTTP) credentials.

posthttps://id.xively.com/api/v1/auth/login-user
curl --request POST \
  --url https://id.xively.com/api/v1/auth/login-user \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://id.xively.com/api/v1/auth/login-user',
  headers: { 'content-type': 'application/json' } };

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

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

url = URI("https://id.xively.com/api/v1/auth/login-user")

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

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'

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://id.xively.com/api/v1/auth/login-user");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://id.xively.com/api/v1/auth/login-user"

headers = {'content-type': 'application/json'}

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

print(response.text)
A binary file was returned

You couldn't be authenticated

{"csrfToken":"eXF6cWJDeEtoUC9TYm1NS1ZIMkl3UT09","jwt":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJleHBpcmVzIjoxNDc2NjU5NzQ5Mjg2LCJyZW5ld2FsS2V5Ijoidzl2T0x2MTM2RDN6cC9UcE1EQ1hmZz09IiwicmVuZXdhbEV4cCI6MTQ3Nzg2ODE0OTI4NiwiY29va2llUHJvcGVydGllcyI6eyJtYXhBZ2UiOjEyMDk2MDAwMDAsImRvbWFpbiI6Ii54aXZlbHkuY29tIiwic2VjdXJlIjp0cnVlLCJodHRwT25seSI6dHJ1ZX0sImlkIjoiNGI4ZGNlODQtMDgzYy00NDEyLWE3NzEtMzcwYjE2OWFkNDM5IiwidXNlcklkIjoiMTUwMzNiMTYtOTA5NS00MjljLWIwZjgtMGJiNjUxNmVjNzgxIiwiYWNjb3VudElkIjoiZjg1ZTRmZGEtODI3ZC00NmZmLTk1MzctZDRiNDUzYjI3Y2RlIiwicm9sZXMiOltdLCJjZXJ0IjoiMmFiNzE5MGUtNWZiNy00NDNlLWI3ZTYtY2U5NjEyMDI5MGQxIn0.YN4eFK9h1u4mscRLkRo0tRsyP-DJ0L2TD__MvPhzAVOpZO91bw_7f8am3TzOuESu2WMzMy5iekfD7UKrSjUIRw_CIa8rkrfZFc910_7dftWkEGEX9Po6lw8q6SDMMhmh4QnGB3iPP5oHEFJvKMLr81qbbEPjYQBMnGGExFBSdtxXF4dcWCIYDrupUePDzr4K7M3J7t8d5ZrzRrAmW8prGYgSo_T1I1VOcYdkYMGom3zSlrRWxWKeDwk6hyFg_W6pb3gCMZL4txbnF6suPbEhNWxrfhIQ-9pMBZEUYbB04N0yTmnFGijHNFA71-Od-kLS-2Xq9lK2blnV8Q4DIWBpNg"}
{"statusCode":401,"error":"Unauthorized","message":"Invalid credentials.","attributes":{"errorCode":"InvalidCredentialsError","error":"Invalid credentials."}}

Body Params

emailAddress
string
required

The user's email.

password
string
required

The user's password.

accountId
string
required

The GUID id of your account.

renewalType
string

The length of time you want this session to last before requiring a new login. Accepts short (30 minutes), remembered (7 days), extended (100 days). Defaults to 14 days.

Headers

Content-Type
string
required

Specifies that your request is a JSON object.

 

This is your API key

The HTTP APIs use an "authorization" header. The value must contain the word "Bearer", followed by a space, followed by the access token (JWT) of the entity making the call.

Don't forget Content-Type

You also have to provide a Content-Type header to specify that your request will supply JSON object. (See an example request header below).

{
  "Content-Type": "application/json",
  "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJleHBpcmVzIjoxNDc2NjU5NzQ5Mjg2LCJyZW5ld2FsS2V5Ijoidzl2T0x2MTM2RDN6cC9UcE1EQ1hmZz09IiwicmVuZXdhbEV4cCI6MTQ3Nzg2ODE0OTI4NiwiY29va2llUHJvcGVydGllcyI6eyJtYXhBZ2UiOjEyMDk2MDAwMDAsImRvbWFpbiI6Ii54aXZlbHkuY29tIiwic2VjdXJlIjp0cnVlLCJodHRwT25seSI6dHJ1ZX0sImlkIjoiNGI4ZGNlODQtMDgzYy00NDEyLWE3NzEtMzcwYjE2OWFkNDM5IiwidXNlcklkIjoiMTUwMzNiMTYtOTA5NS00MjljLWIwZjgtMGJiNjUxNmVjNzgxIiwiYWNjb3VudElkIjoiZjg1ZTRmZGEtODI3ZC00NmZmLTk1MzctZDRiNDUzYjI3Y2RlIiwicm9sZXMiOltdLCJjZXJ0IjoiMmFiNzE5MGUtNWZiNy00NDNlLWI3ZTYtY2U5NjEyMDI5MGQxIn0.YN4eFK9h1u4mscRLkRo0tRsyP-DJ0L2TD__MvPhzAVOpZO91bw_7f8am3TzOuESu2WMzMy5iekfD7UKrSjUIRw_CIa8rkrfZFc910_7dftWkEGEX9Po6lw8q6SDMMhmh4QnGB3iPP5oHEFJvKMLr81qbbEPjYQBMnGGExFBSdtxXF4dcWCIYDrupUePDzr4K7M3J7t8d5ZrzRrAmW8prGYgSo_T1I1VOcYdkYMGom3zSlrRWxWKeDwk6hyFg_W6pb3gCMZL4txbnF6suPbEhNWxrfhIQ-9pMBZEUYbB04N0yTmnFGijHNFA71-Od-kLS-2Xq9lK2blnV8Q4DIWBpNg"
}
Suggest Edits

Multi-factor authentication trigger

 
posthttps://id.xively.com/api/v1/auth/mfa-trigger-auth
curl --request POST \
  --url https://id.xively.com/api/v1/auth/mfa-trigger-auth \
  --header 'xively-mfa-token: xively-mfa-token'
var request = require("request");

var options = { method: 'POST',
  url: 'https://id.xively.com/api/v1/auth/mfa-trigger-auth',
  headers: { 'xively-mfa-token': 'xively-mfa-token' } };

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

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

url = URI("https://id.xively.com/api/v1/auth/mfa-trigger-auth")

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

request = Net::HTTP::Post.new(url)
request["xively-mfa-token"] = 'xively-mfa-token'

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://id.xively.com/api/v1/auth/mfa-trigger-auth");
xhr.setRequestHeader("xively-mfa-token", "xively-mfa-token");

xhr.send(data);
import requests

url = "https://id.xively.com/api/v1/auth/mfa-trigger-auth"

headers = {'xively-mfa-token': 'xively-mfa-token'}

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

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "status": "poll"
}

Body Params

mfaMethod
string
required

Name of the authentication method. The only accepted value is sms.

Headers

xively-mfa-token
string
required

The GUID mfaToken that identifies this session. For a user with MFA set up, the token is returned in a successful response from the /auth/login-user endpoint.

 

Use this API to request a text message verification code for a user with multi-factor authentication (MFA) set up.

{
    url: "https://id.xively.com/api/v1/auth/mfa-trigger-auth",
    method: "post",
    body: {
        "mfaMethod": "sms"
    },
    headers: {
        "xively-mfa-token": "<user's mfa token>"
    }
}
Suggest Edits

Log in with MFA code

 
posthttps://id.xively.com/api/v1/auth/mfa-login-user
curl --request POST \
  --url https://id.xively.com/api/v1/auth/mfa-login-user \
  --header 'xively-mfa-token: xively-mfa-token'
var request = require("request");

var options = { method: 'POST',
  url: 'https://id.xively.com/api/v1/auth/mfa-login-user',
  headers: { 'xively-mfa-token': 'xively-mfa-token' } };

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

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

url = URI("https://id.xively.com/api/v1/auth/mfa-login-user")

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

request = Net::HTTP::Post.new(url)
request["xively-mfa-token"] = 'xively-mfa-token'

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://id.xively.com/api/v1/auth/mfa-login-user");
xhr.setRequestHeader("xively-mfa-token", "xively-mfa-token");

xhr.send(data);
import requests

url = "https://id.xively.com/api/v1/auth/mfa-login-user"

headers = {'xively-mfa-token': 'xively-mfa-token'}

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

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

mfaMethod
string
required

Name of the authentication method. For a code generated by LastPass Authenticator, use totp. For a code received in a text message, use sms.

code
string
required

User's verification code generated by LastPass Authenticator or received in a text message.

Headers

xively-mfa-token
string
required

The GUID mfaToken that identifies this session. For a user with MFA set up, the token is returned in a successful response from the /auth/login-user endpoint.

 

Use this API to log in a user for whom MFA has been set up.

{
    url: "https://id.xively.com/api/v1/auth/mfa-login-user",
    method: "post",
    body: {
        "mfaMethod": "<set to totp or sms depending on the verification method>",
        "code": "<user's verification code generated by LastPass Authenticator or received in a text message>"
    },
    headers: {
        "xively-mfa-token": "<user's mfa token>"
    }
}
 

Header Auth

 Authentication is required for this endpoint.
posthttps://id.xively.com/api/v1/sessions/logout
{
  url: "https://id.xively.com/api/v1/sessions/logout",
  method: "post", 
  header: {
    "authorization": "Bearer <your-JWT-here>" 
  }
}
A binary file was returned

You couldn't be authenticated

{
  "success": true,
  "message": "Successfully logged out"
}
 

Use this API to log out from the session. Logging out works the same for users and applications.
Examples below show how to use the logout API in JavaScript using Node.js and in Python using the Requests package.

request({
    url: "https://id.xively.com/api/v1/sessions/logout",
    method: "post",
    headers: {
        "authorization": "Bearer <your-JWT-here>"
    }
})
import requests
requests.post("https://id.xively.com/api/v1/sessions/logout", headers = {
            "authorization": "Bearer <your-JWT-here>”})

Xively uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an action failed, etc.), and codes in the 5xx range indicate an error with Xively's servers (these are rare).

Code	Description
100	The given item does not exist
102	The entity an identifying parameter references does not exist
103	The provided etag header is invalid
104	The given entity could not be deleted because it would violate certain constraints on the entity
105	The given organization would violate the maximum organization nesting depth (5)
106	The provided value for a parameter was invalid or would violate uniqueness constraints
107	The given entity is deleted
108	The provided version does not match the latest version of the entity
109	The requested page is outside the range of results
110	The given userId already exists as a user in the system
30	Invalid basic authentication credentials were provided in this request
31	Invalid use of IAM credentials for this request
20	Basic authorization access is forbidden for this request
21	Authorization is forbidden for this request for the given credentials
-199	Generic server error

HTTP Status codes

Status code
Description

200 OK

The request responded normally

204 OK

The request responded normally, with no response data

400 Bad Request

The request failed due to missing or invalid request parameters

401 Unauthorized

The given authentication credentials were missing or invalid

403 Forbidden

The authenticated credentials are not permitted to make the given request

404 Not Found

The given endpoint or entity does not exist or you do not have permission to access it

410 Gone

The given entity is deleted

412 Precondition Failed

The etag presented in the headers does not match the latest version on the entity

416 Requested Range Not Satisfiable

The requested page is outside the range of results

500 Internal Server Error

An error occurred, but the server was not prepared to handle it

Suggest Edits

Pagination

 

For efficient handling of queries returning large arrays of JSON objects, the API supports pagination. On a query, the request parameters indicate the number of objects desired in the result set. The result JSON includes metadata in a meta object, indicating the total number of JSON objects meeting the query criteria. Applications written to the platform can use this metadata to determine whether additional calls are needed to obtain the next page of results or the entire result set.

Pagination parameters

"meta": {
      "count": 1,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
Param
Description

count

Number of entities total that match this query.

page

Which page of results was returned.

pageSize

How many items are included in this page (max 1000, defaults to 10 if not specified in the request).

sortOrder

asc or desc

 

A device is the digital representation of a physical internet-connected device. Devices are generally created in Blueprint when they are created in reality.

Suggest Edits

The device object

 

Header Auth

 Authentication is required for this endpoint.
optionshttps://blueprint.xively.com/api/v1/devices
Attributes of the device object are as follows
A binary file was returned

You couldn't be authenticated

Body Params

created
date

The ISO 8601 formatted date on which this device was created. System created, not editable.

createdById
string

The GUID userId of the actor that created this device. System created, not editable.

lastModified
date

The ISO 8601 formatted date on which this device was last modified. This does not include MQTT messages or updates to its template or channels - only its properties and custom fields. System created, not editable.

lastModifiedById
string

The GUID userId of the actor that last modified this device. System created, not editable.

version
string

The unique string that represents the most recent state of this device (optimistic concurrency version). Must be included in API calls to update or delete a device, in order to prove that the client is aware of the device's most recent state prior to modifying it. System created, not editable.

id
string

The GUID that identifies this device in all Xively API calls. System created, not editable, searchable.

accountId
string

The GUID that identifies your Xively Account.

deviceTemplateId
string

The GUID that identifies the device template that this device stems from. Not editable after creation, searchable.

organizationId
string

The GUID that identifies the organization in which this device is held. The device can be manually moved with sufficient permission, or moved programmatically by end users via the association APIs. Searchable.

serialNumber
string

The serial number you want to use for this device. Within the API, the device will be referred to by its id, not its serialNumber - this property exists to link a serial you may use in your manufacturing or records to the device in Xively. Searchable with partial string matches.

provisioningState
string

One of 3 defined states that represent the device's progress through the provisioning lifecycle: defined (Device has been created in the Xively platform); activated (Device has been issued a password); associated (Device has been associated with an organization via the association APIs). System created, not editable, searchable.

firmwareVersion
string

Device firmware version. This field can be manually updated, and is updated whenever new file packages are delivered to devices using the platforms file and firmware delivery capabilities. System updated, editable, searchable with partial string matches.

latitude
string

The device's latitude. Must be a number between -90 and 90. Searchable.

longitude
string

The device's longitude. Must be a number between -180 and 180. Searchable.

connected
boolean

Whether the device is currently connected to the messaging broker. Searchable.

lastConnected
date

ISO 8601 formatted date when the device was last connected to the messaging broker. Searchable.

externalIp
string

The device's external IP address when it last connected to the messaging broker. Searchable.

geoIpLatitude
string

An estimation of the device's latitude based on its most recent externalIp. This value is populated by Xively as a rough approximation, often accurate to within 100 ft. System updated, not editable, searchable.

geoIpLongitude
string

An estimation of the device's longitude based on its most recent externalIp. This value is populated by Xively as a rough approximation, often accurate to within 100 ft. System updated, not editable, searchable.

reverseDns
string

The device's hostname, based on a reverse DNS lookup from externalIp. System updated, not editable, searchable.

channels
array

The channels that this device has. These are determined by the device's template - adding and removing channels from its template will remove them from this device immediately. See channels for more information.

 
Suggest Edits

Create a device

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/devices
{
  "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
  "deviceTemplateId": "9e26b2f7-4775-4151-930a-e3b2ddc3d5d4",
  "serialNumber": "Example device"
}
https://blueprint.xively.com:443/api/v1/devices
A binary file was returned

You couldn't be authenticated

{
  "device": {
    "created": "2016-10-16T00:14:04.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T00:14:04.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "Xq",
    "id": "e8df5e10-c041-4d52-8d9c-81c8a25dedee",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "deviceTemplateId": "9e26b2f7-4775-4151-930a-e3b2ddc3d5d4",
    "organizationId": null,
    "serialNumber": "Example device",
    "provisioningState": "defined",
    "firmwareVersion": null,
    "latitude": null,
    "longitude": null,
    "connected": false,
    "lastConnected": null,
    "externalIp": null,
    "geoIpLatitude": null,
    "geoIpLongitude": null,
    "reverseDns": null,
    "deviceVersion": null,
    "location": null,
    "name": null,
    "purchaseDate": null,
    "channels": [
      {
        "channelTemplateId": "9d1fe8ee-6eed-425a-89c1-de65ecf17cd2",
        "channelTemplateName": "_log",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/f85e4fda-827d-46ff-9537-d4b453b27cde/d/e8df5e10-c041-4d52-8d9c-81c8a25dedee/_log",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      }
    ]
  }
}

Body Params

accountId
string
required

The GUID that identifies your Xively Account.

deviceTemplateId
string

The GUID that identifies the device template that this device stems from. If not specified, the default device template will be used. Not editable after creation.

organizationId
string

The GUID that identifies the organization in which this device is held. The device can be manually moved with sufficient permission, or moved programmatically by end users via the association APIs. If not specified, the device will be created outside of any organization.

serialNumber
string
required

The serial number you want to use for this device. Within the API, the device will be referred to by its id, not its serialNumber - this property exists to link a serial you may use in your manufacturing or records to the device in Xively.

firmwareVersion
string

Device firmware version. This field can be manually updated, and is updated whenever new file packages are delivered to devices using the platforms file and firmware delivery capabilities.

latitude
string

The device's latitude. Must be a number between -90 and 90.

longitude
string

The device's longitude. Must be a number between -180 and 180.

externalIp
string

The device's external IP address when it last connected to the messaging broker.

reverseDns
string

The device's hostname, based on a reverse DNS lookup from externalIp. System updated

 
Suggest Edits

Get a device

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/devices/id
https://blueprint.xively.com:443/api/v1/devices/e8df5e10-c041-4d52-8d9c-81c8a25dedee
A binary file was returned

You couldn't be authenticated

{
  "device": {
    "created": "2016-10-16T00:14:04.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T00:14:04.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "Xq",
    "id": "e8df5e10-c041-4d52-8d9c-81c8a25dedee",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "deviceTemplateId": "9e26b2f7-4775-4151-930a-e3b2ddc3d5d4",
    "organizationId": null,
    "serialNumber": "Example device",
    "provisioningState": "defined",
    "firmwareVersion": null,
    "latitude": null,
    "longitude": null,
    "connected": false,
    "lastConnected": null,
    "externalIp": null,
    "geoIpLatitude": null,
    "geoIpLongitude": null,
    "reverseDns": null,
    "deviceVersion": null,
    "location": null,
    "name": null,
    "purchaseDate": null,
    "channels": [
      {
        "channelTemplateId": "9d1fe8ee-6eed-425a-89c1-de65ecf17cd2",
        "channelTemplateName": "_log",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/f85e4fda-827d-46ff-9537-d4b453b27cde/d/e8df5e10-c041-4d52-8d9c-81c8a25dedee/_log",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      }
    ]
  }
}

Path Params

id
string
required

The GUID that identifies this device in all Xively API calls.

Query Params

expand
string

Expand parent references (account, device-template, organization). List parameters as a comma-separated list (e.g. "account,device-template"), to include multiple expanded references.

 
Suggest Edits

Update a device

 

Header Auth

 Authentication is required for this endpoint.
puthttps://blueprint.xively.com/api/v1/devices/id
{
  "organizationId": "c8e5f746-be71-46f7-8629-1ba153bac41e",
  "latitude": 42.3495918,
  "longitude": -71.0504417
}
https://blueprint.xively.com:443/api/v1/devices/e8df5e10-c041-4d52-8d9c-81c8a25dedee
A binary file was returned

You couldn't be authenticated

{
  "device": {
    "created": "2016-10-16T00:14:04.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T01:05:22.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "8W",
    "id": "e8df5e10-c041-4d52-8d9c-81c8a25dedee",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "deviceTemplateId": "9e26b2f7-4775-4151-930a-e3b2ddc3d5d4",
    "organizationId": "c8e5f746-be71-46f7-8629-1ba153bac41e",
    "serialNumber": "Example device (updated)",
    "provisioningState": "defined",
    "firmwareVersion": null,
    "latitude": 42.3495918,
    "longitude": -71.0504417,
    "connected": false,
    "lastConnected": null,
    "externalIp": null,
    "geoIpLatitude": null,
    "geoIpLongitude": null,
    "reverseDns": null,
    "deviceVersion": null,
    "location": null,
    "name": null,
    "purchaseDate": null,
    "channels": [
      {
        "channelTemplateId": "9d1fe8ee-6eed-425a-89c1-de65ecf17cd2",
        "channelTemplateName": "_log",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/f85e4fda-827d-46ff-9537-d4b453b27cde/d/e8df5e10-c041-4d52-8d9c-81c8a25dedee/_log",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      }
    ]
  }
}

Path Params

id
string
required

The GUID that identifies this device in all Xively API calls.

Body Params

organizationId
string

The GUID that identifies the organization in which this device is held. The device can be manually moved with sufficient permission, or moved programmatically by end users via the association APIs. If not specified, the device will be created outside of any organization.

firmwareVersion
string

Device firmware version. This field can be manually updated, and is updated whenever new file packages are delivered to devices using the platforms file and firmware delivery capabilities.

latitude
string

The device's latitude. Must be a number between -90 and 90.

longitude
string

The device's longitude. Must be a number between -180 and 180.

externalIp
string

The device's external IP address when it last connected to the messaging broker.

reverseDns
string

The device's hostname, based on a reverse DNS lookup from externalIp. System updated

Headers

etag
string
required

The unique string (version) that represents the most recent state of this device (optimistic concurrency version). Must be included in API calls to update or delete a device, in order to prove that the client is aware of the device's most recent state prior to modifying it.

 

Did you catch that?

In the example request above, the device's organizationId was updated. This moved the device into a new organization, which would have immediate effects on which users had permission over it.

Devices can be manually moved between organizations in this way by admins and backend applications, but far more commonly, they are moved between organizations by end-users through the use of the association APIs.

The association APIs prevent the need for a backend system that manually moves devices around as your end-users claim and share permissions over them, and instead makes it possible for end-users to securely manage their devices autonomously, keeping your code (and the association process) simple to set up if you use Xively.

Suggest Edits

Delete a device

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://blueprint.xively.com/api/v1/devices/id
https://blueprint.xively.com:443/api/v1/devices/e8df5e10-c041-4d52-8d9c-81c8a25dedee
A binary file was returned

You couldn't be authenticated

Path Params

id
string
required

The GUID that identifies this device in all Xively API calls.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this device (optimistic concurrency version). Must be included in API calls to update or delete a device, in order to prove that the client is aware of the device's most recent state prior to modifying it.

 
Suggest Edits

Recover a device

First, you must retrieve the version number of the device you need to recover.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/api/v1/trash/devices/id/recover
https://blueprint.xively.com:443/api/v1/trash/devices/85144ced-790e-412f-88a8-334104cb6704/recover
{ 
    url: "https://blueprint.xively.com/api/v1/trash/devices/{id}/recover",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your channel template version>"
    }
}
A binary file was returned

You couldn't be authenticated

{
  "device": {
    "created": "2017-06-08T13:03:36.000Z",
    "createdById": "094cf5d2-48c9-430d-892b-a1144f467ea7",
    "lastModified": "2017-08-10T14:02:36.000Z",
    "lastModifiedById": "094cf5d2-48c9-430d-892b-a1144f467ea7",
    "version": "0g",
    "id": "85144ced-790e-412f-88a8-334104cb6704",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "deviceTemplateId": "6eee48f3-36db-42b2-9f84-469123451e64",
    "organizationId": "27272410-9c6b-44c2-bc94-fc00f01bac95",
    "serialNumber": "My Sample Ice Machine 01",
    "provisioningState": "activated",
    "firmwareVersion": null,
    "latitude": null,
    "longitude": null,
    "connected": false,
    "lastConnected": "2017-07-11T14:04:09.000Z",
    "externalIp": "195.56.119.18",
    "geoIpLatitude": 47.4996,
    "geoIpLongitude": 19.0574,
    "reverseDns": null,
    "deviceVersion": null,
    "location": null,
    "name": null,
    "purchaseDate": null,
    "channels": [
      {
        "channelTemplateId": "d47cab86-28b1-4a71-a833-fa62c3df3d66",
        "channelTemplateName": "Ice consumed",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/Ice consumed",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": false,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "e682e63f-e2c2-4e1b-9079-dcef6d5c9423",
        "channelTemplateName": "Ice Level",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/Ice Level",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": false,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "9b3a6547-8085-4def-b2ad-e4b30cec285a",
        "channelTemplateName": "power",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/power",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": false,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "db9acbf1-3513-4ae0-9838-b3ec73e9248c",
        "channelTemplateName": "Water filter level",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/Water filter level",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": false,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "0801cabd-aa76-43fe-961a-8c2427c04fb1",
        "channelTemplateName": "_rejected",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_rejected",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "8c12e4c9-897a-4668-8592-993df07766ba",
        "channelTemplateName": "_set/fields",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_set/fields",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "15a6ada4-5631-4693-ab5b-4e9496912700",
        "channelTemplateName": "_updates/fields",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_updates/fields",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "aa77a313-8442-41b6-b9b8-ed2517ba6497",
        "channelTemplateName": "TS",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": true
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/TS",
        "kinesisBridgeDelivery": 2,
        "serviceTopic": false,
        "persistenceType": "timeSeries"
      },
      {
        "channelTemplateId": "64255740-91cb-49d9-9075-3315aa8612bf",
        "channelTemplateName": "OtherChannel",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/OtherChannel",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": false,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "a64d00ef-493f-4c6b-ab65-b0737f10737e",
        "channelTemplateName": "_log",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_log",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      }
    ]
  }
}

Path Params

id
string
required

The GUID that identifies this device in all Xively API calls.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this device (optimistic concurrency version). Must be included in API calls to update or delete a device, in order to prove that the client is aware of the device's most recent state prior to modifying it.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve a single deleted device's version number

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/devices/id/
https://blueprint.xively.com:443/api/v1/trash/devices/85144ced-790e-412f-88a8-334104cb6704
A binary file was returned

You couldn't be authenticated

{
  "device": {
    "created": "2017-06-08T13:03:36.000Z",
    "createdById": "094cf5d2-48c9-430d-892b-a1144f467ea7",
    "lastModified": "2017-08-10T09:28:02.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "DJ",
    "id": "85144ced-790e-412f-88a8-334104cb6704",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "deviceTemplateId": "6eee48f3-36db-42b2-9f84-469123451e64",
    "organizationId": "27272410-9c6b-44c2-bc94-fc00f01bac95",
    "serialNumber": "My Sample Ice Machine 01",
    "provisioningState": "activated",
    "firmwareVersion": null,
    "latitude": null,
    "longitude": null,
    "connected": false,
    "lastConnected": "2017-07-11T14:04:09.000Z",
    "externalIp": "195.56.119.18",
    "geoIpLatitude": 47.4996,
    "geoIpLongitude": 19.0574,
    "reverseDns": null,
    "deviceVersion": null,
    "location": null,
    "name": null,
    "purchaseDate": null,
    "channels": [
      {
        "channelTemplateId": "d47cab86-28b1-4a71-a833-fa62c3df3d66",
        "channelTemplateName": "Ice consumed",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/Ice consumed",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": false,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "e682e63f-e2c2-4e1b-9079-dcef6d5c9423",
        "channelTemplateName": "Ice Level",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/Ice Level",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": false,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "9b3a6547-8085-4def-b2ad-e4b30cec285a",
        "channelTemplateName": "power",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/power",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": false,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "db9acbf1-3513-4ae0-9838-b3ec73e9248c",
        "channelTemplateName": "Water filter level",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/Water filter level",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": false,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "0801cabd-aa76-43fe-961a-8c2427c04fb1",
        "channelTemplateName": "_rejected",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_rejected",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "8c12e4c9-897a-4668-8592-993df07766ba",
        "channelTemplateName": "_set/fields",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_set/fields",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "15a6ada4-5631-4693-ab5b-4e9496912700",
        "channelTemplateName": "_updates/fields",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_updates/fields",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "aa77a313-8442-41b6-b9b8-ed2517ba6497",
        "channelTemplateName": "TS",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": true
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/TS",
        "kinesisBridgeDelivery": 2,
        "serviceTopic": false,
        "persistenceType": "timeSeries"
      },
      {
        "channelTemplateId": "64255740-91cb-49d9-9075-3315aa8612bf",
        "channelTemplateName": "OtherChannel",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/OtherChannel",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": false,
        "persistenceType": "simple"
      },
      {
        "channelTemplateId": "a64d00ef-493f-4c6b-ab65-b0737f10737e",
        "channelTemplateName": "_log",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_log",
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      }
    ]
  }
}

Path Params

id
string
required

The GUID that identifies this device in all Xively API calls.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve the version numbers of multiple deleted devices

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/devices/
https://blueprint.xively.com:443/api/v1/trash/devices?accountId=dcfad7c8-90a4-441c-bf9d-fbfafd614771&&&&&&&&&&&&&&meta=true&results=true&page=1&pageSize=10&&sortOrder=asc&
A binary file was returned

You couldn't be authenticated

{
  "devices": {
    "results": [
      {
        "created": "2017-06-08T13:03:36.000Z",
        "createdById": "094cf5d2-48c9-430d-892b-a1144f467ea7",
        "lastModified": "2017-08-10T09:28:02.000Z",
        "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "version": "DJ",
        "id": "85144ced-790e-412f-88a8-334104cb6704",
        "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
        "deviceTemplateId": "6eee48f3-36db-42b2-9f84-469123451e64",
        "organizationId": "27272410-9c6b-44c2-bc94-fc00f01bac95",
        "serialNumber": "My Sample Ice Machine 01",
        "provisioningState": "activated",
        "firmwareVersion": null,
        "latitude": null,
        "longitude": null,
        "connected": false,
        "lastConnected": "2017-07-11T14:04:09.000Z",
        "externalIp": "195.56.119.18",
        "geoIpLatitude": 47.4996,
        "geoIpLongitude": 19.0574,
        "reverseDns": null,
        "name": null,
        "purchaseDate": null,
        "location": null,
        "deviceVersion": null,
        "channels": [
          {
            "channelTemplateId": "d47cab86-28b1-4a71-a833-fa62c3df3d66",
            "channelTemplateName": "Ice consumed",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/Ice consumed",
            "kinesisBridgeDelivery": 0,
            "serviceTopic": false,
            "persistenceType": "simple"
          },
          {
            "channelTemplateId": "e682e63f-e2c2-4e1b-9079-dcef6d5c9423",
            "channelTemplateName": "Ice Level",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/Ice Level",
            "kinesisBridgeDelivery": 0,
            "serviceTopic": false,
            "persistenceType": "simple"
          },
          {
            "channelTemplateId": "9b3a6547-8085-4def-b2ad-e4b30cec285a",
            "channelTemplateName": "power",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/power",
            "kinesisBridgeDelivery": 0,
            "serviceTopic": false,
            "persistenceType": "simple"
          },
          {
            "channelTemplateId": "db9acbf1-3513-4ae0-9838-b3ec73e9248c",
            "channelTemplateName": "Water filter level",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/Water filter level",
            "kinesisBridgeDelivery": 0,
            "serviceTopic": false,
            "persistenceType": "simple"
          },
          {
            "channelTemplateId": "0801cabd-aa76-43fe-961a-8c2427c04fb1",
            "channelTemplateName": "_rejected",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_rejected",
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          },
          {
            "channelTemplateId": "8c12e4c9-897a-4668-8592-993df07766ba",
            "channelTemplateName": "_set/fields",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_set/fields",
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          },
          {
            "channelTemplateId": "15a6ada4-5631-4693-ab5b-4e9496912700",
            "channelTemplateName": "_updates/fields",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_updates/fields",
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          },
          {
            "channelTemplateId": "aa77a313-8442-41b6-b9b8-ed2517ba6497",
            "channelTemplateName": "TS",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": true
            },
            "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/TS",
            "kinesisBridgeDelivery": 2,
            "serviceTopic": false,
            "persistenceType": "timeSeries"
          },
          {
            "channelTemplateId": "64255740-91cb-49d9-9075-3315aa8612bf",
            "channelTemplateName": "OtherChannel",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/OtherChannel",
            "kinesisBridgeDelivery": 0,
            "serviceTopic": false,
            "persistenceType": "simple"
          },
          {
            "channelTemplateId": "a64d00ef-493f-4c6b-ab65-b0737f10737e",
            "channelTemplateName": "_log",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "channel": "xi/blue/v1/dcfad7c8-90a4-441c-bf9d-fbfafd614771/d/85144ced-790e-412f-88a8-334104cb6704/_log",
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          }
        ]
      }
    ],
    "meta": {
      "count": 1,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Path Params

accountID
string
required

The GUID that identifies your Xively account.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

List all devices

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/devices
https://blueprint.xively.com:443/api/v1/devices?accountId=f85e4fda-827d-46ff-9537-d4b453b27cde&meta=true&results=true&page=1&pageSize=10&sortOrder=asc&
A binary file was returned

You couldn't be authenticated

{
  "devices": {
    "results": [
      {
        "created": "2016-10-16T00:14:04.000Z",
        "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "lastModified": "2016-10-16T00:14:04.000Z",
        "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "version": "Xq",
        "id": "e8df5e10-c041-4d52-8d9c-81c8a25dedee",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "deviceTemplateId": "9e26b2f7-4775-4151-930a-e3b2ddc3d5d4",
        "organizationId": null,
        "serialNumber": "Example device",
        "provisioningState": "defined",
        "firmwareVersion": null,
        "latitude": null,
        "longitude": null,
        "connected": false,
        "lastConnected": null,
        "externalIp": null,
        "geoIpLatitude": null,
        "geoIpLongitude": null,
        "reverseDns": null,
        "name": null,
        "purchaseDate": null,
        "location": null,
        "deviceVersion": null,
        "channels": [
          {
            "channelTemplateId": "9d1fe8ee-6eed-425a-89c1-de65ecf17cd2",
            "channelTemplateName": "_log",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "channel": "xi/blue/v1/f85e4fda-827d-46ff-9537-d4b453b27cde/d/e8df5e10-c041-4d52-8d9c-81c8a25dedee/_log",
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          }
        ]
      }
    ],
    "meta": {
      "count": 1,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Query Params

accountId
string
required

The GUID that identifies your Xively Account.

deviceTemplateId
string

The GUID that identifies the device template that this device stems from.

organizationId
string

The GUID that identifies the organization in which this device is held. The device can be manually moved with sufficient permission, or moved programmatically by end users via the association APIs.

serialNumber
string

The serial number you want to use for this device. Within the API, the device will be referred to by its id, not its serialNumber - this property exists to link a serial you may use in your manufacturing or records to the device in Xively. Searchable with partial string matches.

provisioningState
string

One of 3 defined states that represent the device's progress through the provisioning lifecycle: defined (Device has been created in the Xively platform); activated (Device has been issued a password); associated (Device has been associated with an organization via the association APIs).

firmwareVersion
string

Device firmware version. This field can be manually updated, and is updated whenever new file packages are delivered to devices using the platforms file and firmware delivery capabilities. Searchable with partial string matches.

latitude
string

The device's latitude. Must be a number between -90 and 90.

longitude
string

The device's longitude. Must be a number between -180 and 180.

connected
boolean

Whether the device is currently connected to the messaging broker.

lastConnected
date

ISO 8601 formatted date when the device was last connected to the messaging broker.

externalIp
string

The device's external IP address when it last connected to the messaging broker.

geoIpLatitude
string

An estimation of the device's latitude based on its most recent externalIp. This value is populated by Xively as a rough approximation, often accurate to within 100 ft.

geoIpLongitude
string

An estimation of the device's longitude based on its most recent externalIp. This value is populated by Xively as a rough approximation, often accurate to within 100 ft.

reverseDns
string

The device's hostname, based on a reverse DNS lookup from externalIp.

meta
boolean

Whether or not to include meta-information in the response (count, page, pageSize, sortOrder)

results
boolean

Whether or not to include results in the response (vs. meta-information only).

page
int32

Which page of results to return.

pageSize
int32

How many items to return per page (max 1000).

sortBy
int32

Choose which query parameter to sort results by (created, lastModified, id, deviceTemplateId, organizationId, provisioningState, firmwareVersion). Defaults to serialNumber.

sortOrder
string

Sort direction (asc, desc). Defaults to asc.

expand
string

Expand parent references (account, device-template, organization). List parameters as a comma-separated list (e.g. "account,device-template"), to include multiple expanded references.

 
Suggest Edits

End users

 

An end-user is a customer, partner, installer, reseller that interacts with your devices.

End users have permission to take ownership of devices and to organize those devices themselves, so you don't have to manually keep permissions updated.

They can only make requests to the endpoints:

  • /end-users
  • /organizations
  • /devices.

They cannot modify anything else in the account.

End-users are also tied directly to a user identity, allowing them to log in and receive secure access tokens for the management APIs (HTTP). A user identity cannot be tied to both an Account User and an End User, however, it can be tied to multiple End Users, representing that that one real person has access to the multiple organizations and devices of those various End Users.

For more on the permissions that the End User has, refer to User Roles.

Suggest Edits

The end-user object

 

Header Auth

 Authentication is required for this endpoint.
optionshttps://blueprint.xively.com/api/v1/end-users
Attributes of the end-user object are as follows
A binary file was returned

You couldn't be authenticated

Body Params

created
date

The ISO 8601 formatted date on which this end-user was created. System created, not editable.

createdById
string

The GUID userId of the actor that created this end-user. System created, not editable.

lastModified
date

The ISO 8601 formatted date on which this end-user was last modified. This does not include logins or actions by this end-user, only updates to its fields. System created, not editable.

lastModifiedById
string

The GUID userId of the actor that last modified this end-user. System created, not editable.

version
string

The unique string that represents the most recent state of this end-user (optimistic concurrency version). Must be included in API calls to update or delete an end-user, in order to prove that the client is aware of the end-user's most recent state prior to modifying it. System created, not editable.

userId
string

The GUID that identifies this end-user in all Xively API calls. System created, not editable, searchable.

id
string

The GUID that identifies this end-user's identity object (email/password). Searchable

accountId
string

The GUID that identifies your Xively Account.

endUserTemplateId
string

The GUID that identifies the device template that this device stems from. Not editable after creation, searchable.

organizationId
string

The GUID that identifies the organization over which this end-user has control. The end-user can be manually moved with sufficient permission, and their control extends to all child organizations below the one identified by this field. Searchable.

 
Suggest Edits

Create an end-user

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/end-users
{
  "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
  "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
  "organizationId": "609db8d9-2c3f-46aa-a646-e58c078a73b4",
  "createIdmUser": "true",
  "idmUserEmail": "example-user@gmail.com",
  "idmUserPassword": "examplePassword"
}
https://blueprint.xively.com:443/api/v1/end-users
A binary file was returned

You couldn't be authenticated

{
  "endUser": {
    "created": "2016-10-16T06:41:08.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T06:41:08.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "AL",
    "userId": "0bcb5b23-ca34-424d-9f53-9b8a4d21c3ee",
    "id": "90ed4502-95b7-4a04-8873-d35330c67606",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
    "organizationId": "609db8d9-2c3f-46aa-a646-e58c078a73b4",
    "address": null,
    "city": null,
    "countryCode": null,
    "emailAddress": null,
    "name": null,
    "phoneNumber": null,
    "postalCode": null,
    "state": null
  }
}

Body Params

accountId
string
required

The GUID that identifies your Xively Account.

endUserTemplateId
string

The GUID that identifies the end-user template that this end-user stems from. If not specified, the default end-user template will be used. Not editable after creation.

organizationId
string
required

The GUID that identifies the organization over which this end-user will have control.

createIdmUser
boolean
required

Must be set to true.

idmUserEmail
string
required

The email address of the end-user being registered. This email will be stored in their identity object along with a hash of their password. Not editable after creation.

idmUserPassword
string
required

The password of the end-user being registered. Password must be a minimum of 8 chars, cannot contain the user's email, and cannot repeat a character more than 3 times in a row. This password will be stored in hashed form in their identity object, along with their email.

 

Watch that userId

The userId object returned here is the identifier of this user's identity object.

Every user has two IDs that are relevant to them:

  • A user's id refers to their entity in Blueprint, and is used to when they are moved among orgs and have fields updated.
  • A user's userId refers to their identity (username and password), and is used when they are logging in to get access tokens (JWTs) of their own, and resetting their password.
Suggest Edits

Get an end-user

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/end-users/id
https://blueprint.xively.com:443/api/v1/end-users/90ed4502-95b7-4a04-8873-d35330c67606
A binary file was returned

You couldn't be authenticated

{
  "endUser": {
    "created": "2016-10-16T06:41:08.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T06:41:08.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "AL",
    "userId": "0bcb5b23-ca34-424d-9f53-9b8a4d21c3ee",
    "id": "90ed4502-95b7-4a04-8873-d35330c67606",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
    "organizationId": "609db8d9-2c3f-46aa-a646-e58c078a73b4",
    "address": null,
    "city": null,
    "countryCode": null,
    "emailAddress": null,
    "name": null,
    "phoneNumber": null,
    "postalCode": null,
    "state": null
  }
}

Path Params

id
string
required

The GUID that identifies this end-user in all Xively API calls.

Query Params

expand
string

Expand parent references (account, end-user-template, organization). List parameters as a comma-separated list (e.g. "account,end-user-template"), to include multiple expanded references.

 
Suggest Edits

Update an end-user

 

Header Auth

 Authentication is required for this endpoint.
puthttps://blueprint.xively.com/api/v1/end-users/id
{
  "organizationId": "6e2a972a-1ab1-400e-a9d2-948cbd02e4d3"
}
https://blueprint.xively.com:443/api/v1/end-users/90ed4502-95b7-4a04-8873-d35330c67606
A binary file was returned

You couldn't be authenticated

{
  "endUser": {
    "created": "2016-10-16T07:01:08.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T07:01:39.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "5X",
    "userId": "a86e9ed6-1b91-4b12-bb6b-25b450fb5780",
    "id": "f9f69040-b53d-49c5-ab9b-b0433b430deb",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
    "organizationId": "6e2a972a-1ab1-400e-a9d2-948cbd02e4d3",
    "address": null,
    "city": null,
    "countryCode": null,
    "emailAddress": null,
    "name": null,
    "phoneNumber": null,
    "postalCode": null,
    "state": null
  }
}

Path Params

id
string
required

The GUID that identifies this end-user in all Xively API calls.

Body Params

organizationId
string
required

The GUID that identifies the organization over which this end-user will have control.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this end-user (optimistic concurrency version). Must be included in API calls to update or delete an end-user, in order to prove that the client is aware of the end-user's most recent state prior to modifying it.

 

Updating an end-user's password

You might have noticed that this API call does not allow you to update an end-user's password.

Emails and passwords are controlled with greater security, and have workflows specifically for managing them so that you don't have to build end user management - Xively has it right out of the box. For more on how to reset end-user passwords, see the tutorial on the topic.

Suggest Edits

Delete an end-user

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://blueprint.xively.com/api/v1/end-users/id
https://blueprint.xively.com:443/api/v1/end-users/f9f69040-b53d-49c5-ab9b-b0433b430deb
A binary file was returned

You couldn't be authenticated

Path Params

id
string
required

The GUID that identifies this end-user in all Xively API calls.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this end-user (optimistic concurrency version). Must be included in API calls to update or delete an end-user, in order to prove that the client is aware of the end-user's most recent state prior to modifying it.

 

One more step

Deleting a user via the Blueprint API does not delete their identity object (which is managed via the IDM API). This means that the email associated with that identity is still reserved, and cannot be used to register a new user.

In order to fully delete a user, admins and backend apps must also delete its associated identity with a DELETE call to https://id.xively.com/api/v1/internal/users/{userId}.

Suggest Edits

Recover an End-User

First, you must retrieve the version number of the End-User you need to recover.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/api/v1/trash/end-users/id/recover
{ 
    url: "https://blueprint.xively.com/api/v1/trash/end-users/{id}/recover",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your channel template version>"
    }
}
https://blueprint.xively.com:443/api/v1/trash/end-users/5d0de3e9-f48f-4280-8370-b0c89b644977/recover
A binary file was returned

You couldn't be authenticated

{
  "endUser": {
    "created": "2017-08-01T15:06:26.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-10T14:12:48.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "O1",
    "userId": "e1fd46cf-c913-4afd-ae53-4b9c0dc80b34",
    "id": "5d0de3e9-f48f-4280-8370-b0c89b644977",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "endUserTemplateId": "063b2bc9-72e5-4c66-a04d-3867a560c01c",
    "organizationId": "27272410-9c6b-44c2-bc94-fc00f01bac95",
    "address": null,
    "city": null,
    "countryCode": null,
    "Default Custom Field": null,
    "emailAddress": null,
    "name": null,
    "phoneNumber": null,
    "postalCode": null,
    "state": null
  }
}

Path Params

id
string
required

The GUID that identifies this end-user in all Xively API calls.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this end-user (optimistic concurrency version). Must be included in API calls to update or delete an end-user, in order to prove that the client is aware of the end-user's most recent state prior to modifying it.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve a single deleted End-User's version number

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/end-users/id
https://blueprint.xively.com:443/api/v1/trash/end-users/5d0de3e9-f48f-4280-8370-b0c89b644977
A binary file was returned

You couldn't be authenticated

{
  "endUser": {
    "created": "2017-08-01T15:06:26.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-10T14:04:49.000Z",
    "lastModifiedById": "094cf5d2-48c9-430d-892b-a1144f467ea7",
    "version": "Mn",
    "userId": "e1fd46cf-c913-4afd-ae53-4b9c0dc80b34",
    "id": "5d0de3e9-f48f-4280-8370-b0c89b644977",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "endUserTemplateId": "063b2bc9-72e5-4c66-a04d-3867a560c01c",
    "organizationId": "27272410-9c6b-44c2-bc94-fc00f01bac95",
    "address": null,
    "city": null,
    "countryCode": null,
    "Default Custom Field": null,
    "emailAddress": null,
    "name": null,
    "phoneNumber": null,
    "postalCode": null,
    "state": null
  }
}

Path Params

id
string
required

The GUID that identifies this end-user in all Xively API calls.

account ID
string
required

The ID of your Xively account

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve multiple version numbers for deleted End-Users

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/end-users/
https://blueprint.xively.com:443/api/v1/end-users/f9f69040-b53d-49c5-ab9b-b0433b430deb
A binary file was returned

You couldn't be authenticated

{
  "endUsers": {
    "results": [
      {
        "created": "2017-08-01T15:06:26.000Z",
        "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "lastModified": "2017-08-10T14:04:49.000Z",
        "lastModifiedById": "094cf5d2-48c9-430d-892b-a1144f467ea7",
        "version": "Mn",
        "userId": "e1fd46cf-c913-4afd-ae53-4b9c0dc80b34",
        "id": "5d0de3e9-f48f-4280-8370-b0c89b644977",
        "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
        "endUserTemplateId": "063b2bc9-72e5-4c66-a04d-3867a560c01c",
        "organizationId": "27272410-9c6b-44c2-bc94-fc00f01bac95",
        "name": null,
        "emailAddress": null,
        "phoneNumber": null,
        "address": null,
        "city": null,
        "state": null,
        "postalCode": null,
        "countryCode": null
      }
    ],
    "meta": {
      "count": 1,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Path Params

accountID
string
required

The ID of your Xively account

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

List all end-users

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/end-users
https://blueprint.xively.com:443/api/v1/end-users?accountId=f85e4fda-827d-46ff-9537-d4b453b27cde&meta=true&results=true&page=1&pageSize=10&&sortOrder=asc&
A binary file was returned

You couldn't be authenticated

{
  "endUsers": {
    "results": [
      {
        "created": "2016-10-16T06:41:08.000Z",
        "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "lastModified": "2016-10-16T06:41:08.000Z",
        "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "version": "AL",
        "userId": "0bcb5b23-ca34-424d-9f53-9b8a4d21c3ee",
        "id": "90ed4502-95b7-4a04-8873-d35330c67606",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
        "organizationId": "609db8d9-2c3f-46aa-a646-e58c078a73b4",
        "name": null,
        "emailAddress": null,
        "phoneNumber": null,
        "address": null,
        "city": null,
        "state": null,
        "postalCode": null,
        "countryCode": null
      }
    ],
    "meta": {
      "count": 1,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Query Params

accountId
string
required

The GUID that identifies your Xively Account.

endUserTemplateId
string

Filter by the GUID endUserTemplateId that the end-users stem from.

organizationId
string

Filter by the GUID id of an organization over which the end-users have permission.

meta
boolean

Whether or not to include meta-information in the response (count, page, pageSize, sortOrder)

results
boolean

Whether or not to include results in the response (vs. meta-information only).

page
int32

Which page of results to return.

pageSize
int32

How many items to return per page (max 1000).

sortBy
int32

Choose which query parameter to sort results by (created, lastModified, id, accountId, endUserTemplateId, organizationId). Defaults to created.

sortOrder
string

Sort direction (asc, desc). Defaults to asc.

expand
string

Expand parent references (account, end-user-template, organization). List parameters as a comma-separated list (e.g. "account,end-user-template"), to include multiple expanded references.

 
Suggest Edits

Organizations

 

An organization is a way to organize the account into smaller pieces, partitioning end users’ access to devices and organizing entities into logical groupings in the process.

Organizations from API endpoints are called "groups" in the Xively management app. Their functionality is the same, the difference is only in the naming convention.

Organizations can be nested up to five levels deep, in which case permissions cascade, giving members of parent organizations rights over the children.

A user attached to an organization can:

  • Add and delete sub-organizations
  • Modify fields of the organization and its sub-organizations
  • Query the organization and sub-organizations (structure and fields)
  • Add and delete users to the organization and sub-organizations
  • Modify fields of users and devices attached to the organization and sub-organizations (note: can modify other users)
  • Query users and devices (structure and fields)
  • Publish and subscribe to channels on devices attached to the organization or sub-organizations
Suggest Edits

The organization object

 

Header Auth

 Authentication is required for this endpoint.
optionshttps://blueprint.xively.com/api/v1/organizations
Attributes of the organization object are as follows
A binary file was returned

You couldn't be authenticated

Body Params

created
date

The ISO 8601 formatted date on which this organization was created. System created, not editable.

createdById
string

The GUID userId of the actor that created this organization. System created, not editable.

lastModified
date

The ISO 8601 formatted date on which this organization was last modified. This does not include devices and users being added or removed from this organization, only updates to its fields. System created, not editable.

lastModifiedById
string

The GUID userId of the actor that last modified this organization. System created, not editable.

version
string

The unique string that represents the most recent state of this organization (optimistic concurrency version). Must be included in API calls to update or delete an organization, in order to prove that the client is aware of the organization most recent state prior to modifying it. System created, not editable.

id
string

The GUID that identifies this organization in all Xively API calls. System created, not editable, searchable.

accountId
string

The GUID that identifies your Xively Account.

parentId
string

The parent organization of this organization (organizations can be nested up to 5 levels deep to facilitate hierarchical permission models).

organizationTemplateId
string

The GUID that identifies the organization template that this organization stems from. Not editable after creation, searchable.

name
string

The name of the organization.

deviceCount
int32

The number of devices in this organization.

endUserCount
int32

The number of end-users in this organization.

childCount
int32

The number of child organizations under this organization.

 
Suggest Edits

Create an organization

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/organizations
{
   url: "https://blueprint.xively.com/api/v1/organizations",
   method: "post",
   header: {
      "authorization": "Bearer <your-JWT-here>"
   },
   body: {
      "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
      "organizationTemplateId": "8fa6c04d-379f-4837-9053-275253fdba06",
      "name": "Example organization"
   }
}
// create an organization, a Blueprint user,
// and link this Blueprint user with the IDM user profile 
// of the user who makes the call
{
   url: "https://blueprint.xively.com/api/v1/organizations",
   method: "post",
   header: {
      "authorization": "Bearer <user's-JWT-here>"
   },
   body: {
      "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
      "organizationTemplateId": "8fa6c04d-379f-4837-9053-275253fdba06",
      "name": "A group created by an end-user",
      "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70"
   }
}
A binary file was returned

You couldn't be authenticated

{
  "organization": {
    "created": "2016-10-16T07:27:26.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T07:27:26.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "NG",
    "id": "169b06d2-290e-4f2f-87d9-809f56757c8c",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "parentId": null,
    "organizationTemplateId": "8fa6c04d-379f-4837-9053-275253fdba06",
    "name": "Example organization",
    "address": null,
    "city": null,
    "countryCode": null,
    "description": null,
    "industry": null,
    "organizationSize": null,
    "phoneNumber": null,
    "postalCode": null,
    "state": null,
    "websiteAddress": null
  }
}
{
  "organization": {
    "created": "2017-03-21T11:51:39.000Z",
    "createdById": "<userId of the user who made the call>",
    "lastModified": "2017-03-21T11:51:39.000Z",
    "lastModifiedById": "74fa7bec-fef9-4b6a-a729-03e1c4bd6c99",
    "version": "vk",
    "id": "ab9d7982-7572-46ec-957e-283f34d06294",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "parentId": null,
    "organizationTemplateId": "8fa6c04d-379f-4837-9053-275253fdba06",
    "name": "A group created by an end-user",
    "description": null,
    "phoneNumber": null,
    "address": null,
    "city": null,
    "state": null,
    "postalCode": null,
    "countryCode": null,
    "industry": null,
    "organizationSize": null,
    "websiteAddress": null,
    "defaultEndUser": {
      "created": "2017-03-21T11:51:39.000Z",
      "createdById": "<userId of the user who made the call>",
      "lastModified": "2017-03-21T11:51:39.000Z",
      "lastModifiedById": "74fa7bec-fef9-4b6a-a729-03e1c4bd6c99",
      "version": "kp",
      "userId": "<userId of the user who made the call>",
      "id": "e2f7d67f-d2c7-4e2a-ae18-f099fc11660f",
      "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
      "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
      "organizationId": "ab9d7982-7572-46ec-957e-283f34d06294",
      "First Name": null,
      "Last Name": null,
      "name": null,
      "emailAddress": null,
      "phoneNumber": null,
      "address": null,
      "city": null,
      "state": null,
      "postalCode": null,
      "countryCode": null
    }
  }
}

Body Params

accountId
string
required

The GUID that identifies your Xively Account.

parentId
string

The parent organization of this organization (organizations can be nested up to 5 levels deep to facilitate hierarchical permission models).

organizationTemplateId
string

The GUID that identifies the organization template that this organization stems from. If not specified, the default organization template will be used. Not editable after creation.

name
string
required

The name of the organization

endUserTemplateId
string

The GUID that identifies the end-user template that a default end-user will stem from. Use this parameter to create an end-user within this organization in one API call (e.g. for the end-user self signup workflow). If specified, the id of the end-user is returned. If not specified, the end-user will not be created. Not editable after creation.

description
string

Organization description

phoneNumber
string

Organization phone number

address
string

Organization address

city
string

City

state
string

State or province. The string must be less than or equal to 2 characters.

postalCode
string

Postal or zip code

countryCode
string

The ISO-3166-2 country code

industry
string

Industry

organizationSize
string

Size of the organization

websiteAddress
string

Organization web address

 

Watch that userId

The userId object returned here is the identifier of this user's identity object.

Every user has two IDs that are relevant to them:

  • A user's id refers to their entity in Blueprint, and is used to when they are moved among orgs and have fields updated.
  • A user's userId refers to their identity (username and password), and is used when they are logging in to get access tokens (JWTs) of their own, and resetting their password.
Suggest Edits

Get an organization

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/organizations/id
https://blueprint.xively.com:443/api/v1/organizations/169b06d2-290e-4f2f-87d9-809f56757c8c?count=devices%2Cend-users%2Cchildren&
A binary file was returned

You couldn't be authenticated

{
  "organization": {
    "created": "2016-10-16T07:27:26.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T07:27:26.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "NG",
    "id": "169b06d2-290e-4f2f-87d9-809f56757c8c",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "parentId": null,
    "organizationTemplateId": "8fa6c04d-379f-4837-9053-275253fdba06",
    "name": "Example organization",
    "deviceCount": 0,
    "endUserCount": 0,
    "childCount": 0,
    "address": null,
    "city": null,
    "countryCode": null,
    "description": null,
    "industry": null,
    "organizationSize": null,
    "phoneNumber": null,
    "postalCode": null,
    "state": null,
    "websiteAddress": null
  }
}

Path Params

id
string
required

The GUID id of the organization you are retrieving.

Query Params

expand
string

Expand parent references (account, parent, organization-template). List parameters as a comma-separated list (e.g. "account,parent"), to include multiple expanded references.

count
string

Shows counts of child entities (devices, end-users, children). List parameters as a comma-separated list (e.g. "devices,end-users,children"), to include multiple counts.

 
Suggest Edits

Update an organization

 

Header Auth

 Authentication is required for this endpoint.
puthttps://blueprint.xively.com/api/v1/organizations/id
{
  "name": "Example organization (updated)"
}
https://blueprint.xively.com:443/api/v1/organizations/169b06d2-290e-4f2f-87d9-809f56757c8c
A binary file was returned

You couldn't be authenticated

{
  "organization": {
    "created": "2016-10-16T07:27:26.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T07:45:38.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "mL",
    "id": "169b06d2-290e-4f2f-87d9-809f56757c8c",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "parentId": null,
    "organizationTemplateId": "8fa6c04d-379f-4837-9053-275253fdba06",
    "name": "Example organization (updated)",
    "address": null,
    "city": null,
    "countryCode": null,
    "description": null,
    "industry": null,
    "organizationSize": null,
    "phoneNumber": null,
    "postalCode": null,
    "state": null,
    "websiteAddress": null
  }
}

Path Params

id
string
required

The GUID id of the organization you are updating.

Body Params

name
string

The name of the organization.

parentId
string

The GUID that identifies the parent organization of this organization (organizations can be nested up to 5 levels deep to facilitate hierarchical permission models).

Headers

etag
string
required

The unique string (version) that represents the most recent state of this organization (optimistic concurrency version). Must be included in API calls to update or delete an organization, in order to prove that the client is aware of the organization's most recent state prior to modifying it.

 
Suggest Edits

Delete an organization

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://blueprint.xively.com/api/v1/organizations/id
https://blueprint.xively.com:443/api/v1/organizations/169b06d2-290e-4f2f-87d9-809f56757c8c
A binary file was returned

You couldn't be authenticated

Path Params

id
string
required

The GUID id of the organization you are deleting.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this organization (optimistic concurrency version). Must be included in API calls to update or delete an organization, in order to prove that the client is aware of the organization's most recent state prior to modifying it.

 
Suggest Edits

Recover an organization

First, you must retrieve the version number of the organization you need to recover.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/api/v1/trash/organizations/id/recover
https://blueprint.xively.com:443/api/v1/trash/organizations/e3edee64-7c26-4ae2-b664-3a75275c2c39/recover
{ 
    url: "https://blueprint.xively.com/api/v1/trash/organizations/{id}/recover",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your channel template version>"
    }
}
A binary file was returned

You couldn't be authenticated

{
  "organization": {
    "created": "2017-08-10T14:15:19.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-10T14:21:08.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "gW",
    "id": "e3edee64-7c26-4ae2-b664-3a75275c2c39",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "parentId": null,
    "organizationTemplateId": "625fd6fa-fbe9-4a93-be14-d720d1983829",
    "name": "testey",
    "address": null,
    "city": null,
    "countryCode": null,
    "Default Custom Field": null,
    "description": null,
    "industry": null,
    "organizationSize": null,
    "phoneNumber": null,
    "postalCode": null,
    "state": null,
    "websiteAddress": null
  }
}

Path Params

id
string
required

The GUID id of the organization you are deleting.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this organization (optimistic concurrency version). Must be included in API calls to update or delete an organization, in order to prove that the client is aware of the organization's most recent state prior to modifying it.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve the version number of a single deleted organization

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/organizations/id
https://blueprint.xively.com:443/api/v1/trash/organizations/e3edee64-7c26-4ae2-b664-3a75275c2c39
A binary file was returned

You couldn't be authenticated

{
  "organization": {
    "created": "2017-08-10T14:15:19.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-10T14:15:33.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "Ye",
    "id": "e3edee64-7c26-4ae2-b664-3a75275c2c39",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "parentId": null,
    "organizationTemplateId": "625fd6fa-fbe9-4a93-be14-d720d1983829",
    "name": "testey",
    "address": null,
    "city": null,
    "countryCode": null,
    "Default Custom Field": null,
    "description": null,
    "industry": null,
    "organizationSize": null,
    "phoneNumber": null,
    "postalCode": null,
    "state": null,
    "websiteAddress": null
  }
}

Path Params

id
string
required

The GUID id of the organization you are deleting.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve multiple version numbers of deleted organization

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/organizations/
https://blueprint.xively.com:443/api/v1/trash/organizations?accountId=dcfad7c8-90a4-441c-bf9d-fbfafd614771&&&&meta=true&results=true&page=1&pageSize=10&&sortOrder=asc&&
A binary file was returned

You couldn't be authenticated

{
  "organizations": {
    "results": [
      {
        "created": "2017-08-10T14:15:19.000Z",
        "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "lastModified": "2017-08-10T14:15:33.000Z",
        "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "version": "Ye",
        "id": "e3edee64-7c26-4ae2-b664-3a75275c2c39",
        "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
        "parentId": null,
        "organizationTemplateId": "625fd6fa-fbe9-4a93-be14-d720d1983829",
        "name": "testey",
        "description": null,
        "phoneNumber": null,
        "address": null,
        "city": null,
        "state": null,
        "postalCode": null,
        "countryCode": null,
        "industry": null,
        "organizationSize": null,
        "websiteAddress": null
      }
    ],
    "meta": {
      "count": 1,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Path Params

accountID
string
required

The GUID that identifies your Xively account.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

List all organizations

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/organizations
https://blueprint.xively.com:443/api/v1/organizations?accountId=f85e4fda-827d-46ff-9537-d4b453b27cde&&&&meta=true&results=true&page=1&&&sortOrder=asc&&
A binary file was returned

You couldn't be authenticated

{
  "organizations": {
    "results": [
      {
        "created": "2016-10-15T18:37:27.000Z",
        "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "lastModified": "2016-10-15T18:37:27.000Z",
        "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "version": "2z",
        "id": "6e2a972a-1ab1-400e-a9d2-948cbd02e4d3",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "parentId": null,
        "organizationTemplateId": "5ab17b64-6514-4dad-80cb-610b8b125cbb",
        "name": "Device Modeler",
        "description": null,
        "phoneNumber": null,
        "address": null,
        "city": null,
        "state": null,
        "postalCode": null,
        "countryCode": null,
        "industry": null,
        "organizationSize": null,
        "websiteAddress": null
      },
      {
        "created": "2016-10-16T07:27:26.000Z",
        "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "lastModified": "2016-10-16T07:27:26.000Z",
        "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "version": "NG",
        "id": "169b06d2-290e-4f2f-87d9-809f56757c8c",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "parentId": null,
        "organizationTemplateId": "8fa6c04d-379f-4837-9053-275253fdba06",
        "name": "Example organization",
        "description": null,
        "phoneNumber": null,
        "address": null,
        "city": null,
        "state": null,
        "postalCode": null,
        "countryCode": null,
        "industry": null,
        "organizationSize": null,
        "websiteAddress": null
      }
    ],
    "meta": {
      "count": 2,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Query Params

accountId
string
required

The GUID that identifies your Xively Account.

parentId
string

Filter by the parent organization's id.

organizationTemplateId
string

Filter by the GUID organizationTemplateId that the organizations stem from.

name
string

Filter by the name of the organizations. Supports partial string matches.

meta
boolean

Whether or not to include meta-information in the response (count, page, pageSize, sortOrder). Defaults to true.

results
boolean

Whether or not to include results in the response (vs. meta-information only). Defaults to true.

page
int32

Which page of results to return.

pageSize
int32

How many items to return per page (max 1000). Defaults to 10.

sortBy
int32

Choose which query parameter to sort results by (created, lastModified, id, accountId, parentId, organizationTemplateId, name). Defaults to name.

sortOrder
string

Sort direction (asc, desc). Defaults to asc.

count
string

Show counts of child entities (devices, end-users, children). List parameters as a comma-separated list (e.g. "devices,end-users,children"), to include multiple counts.

expand
string

Expand parent references (account, parent, organization-template). List parameters as a comma-separated list (e.g. "account,organization-template"), to include multiple expanded references.

 
Suggest Edits

Templates

 

Every entity in Blueprint has a template that defines the default properties of the entity. This allows you to define properties that are common across a subset of entities of a given type. For example, if a device is a specific instance of manufactured product, then a device-template represents the model or product number of that device.

Templates define:

  • What custom fields children of this template will inherit (e.g. model number, install site, colour, phone number)
  • (For devices only) What channels all device entities will have (define once for a Device Template and every Device will have them)
Suggest Edits

Device templates

 
Suggest Edits

The device template object

 

Header Auth

 Authentication is required for this endpoint.
optionshttps://blueprint.xively.com/api/v1/devices/templates
Attributes of the device template object are as follows
A binary file was returned

You couldn't be authenticated

Body Params

created
date

The ISO 8601 formatted date on which this device template was created. System created, not editable.

createdById
string

The GUID userId of the actor that created this device template. System created, not editable.

lastModified
date

The ISO 8601 formatted date on which this device template was last modified. System created, not editable.

lastModifiedById
string

The GUID userId of the actor that last modified this device template. System created, not editable.

version
string

The unique string that represents the most recent state of this device template (optimistic concurrency version). Must be included in API calls to update or delete a device template, in order to prove that the client is aware of the device template's most recent state prior to modifying it. System created, not editable.

id
string

The GUID that identifies this device template in all Xively API calls. System created, not editable, searchable.

accountId
string

The GUID that identifies your Xively Account.

name
string

The name of the device template.

default
boolean

When true, this template is the one that will be used if no deviceTemplateId is specified during a device creation API call. True only for the "Default Device Template" that appears by default in every account, not editable

deviceCount
int32

The number of child devices that stem from this template.

deviceFieldCount
int32

The number of custom fields attached to this template.

channelTemplates
array

The channels (channelTemplate objects) attached to this device template. The channels that this device has. Adding and removing channel templates from a device template will instantly be reflected on all child devices of that template.

 
Suggest Edits

Create a device template

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/devices/templates
{
  "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
  "name": "Example device template"
}
https://blueprint.xively.com:443/api/v1/devices/templates
A binary file was returned

You couldn't be authenticated

 {
  "deviceTemplate": {
    "created": "2016-10-15T22:06:06.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-15T22:06:06.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "el",
    "id": "988d3640-3b96-4a62-b79e-b4f636871ac6",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "name": "Example device template",
    "default": "false",
    "category": null,
    "code": null,
    "description": null,
    "make": null,
    "channelTemplates": [
      {
        "id": "9d1fe8ee-6eed-425a-89c1-de65ecf17cd2",
        "name": "_log",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      }
    ]
  }
}

Body Params

accountId
string
required

The GUID that identifies your Xively Account.

name
string
required

The name of the device template.

 
Suggest Edits

Get a device template

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/devices/templates/id
https://blueprint.xively.com:443/api/v1/devices/templates/9e26b2f7-4775-4151-930a-e3b2ddc3d5d4
A binary file was returned

You couldn't be authenticated

{
  "deviceTemplate": {
    "created": "2016-10-15T18:40:46.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-15T18:40:46.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "QW",
    "id": "9e26b2f7-4775-4151-930a-e3b2ddc3d5d4",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "name": "Example device template",
    "default": "false",
    "category": null,
    "code": null,
    "description": null,
    "make": null,
    "channelTemplates": [
      {
        "id": "9d1fe8ee-6eed-425a-89c1-de65ecf17cd2",
        "name": "_log",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      }
    ]
  }
}

Path Params

id
string
required

The GUID that identifies this device template in all Xively API calls.

Query Params

count
string

Shows counts of child entities (devices) and number of custom fields (device-fields). List parameters as a comma-separated list (e.g. "devices,device-fields"), to include multiple counts.

 
Suggest Edits

Update a device template

 

Header Auth

 Authentication is required for this endpoint.
puthttps://blueprint.xively.com/api/v1/devices/templates/id
{
  "name": "Example device template (updated)"
}
https://blueprint.xively.com:443/api/v1/devices/templates/9e26b2f7-4775-4151-930a-e3b2ddc3d5d4
A binary file was returned

You couldn't be authenticated

{
  "deviceTemplate": {
    "created": "2016-10-15T18:40:46.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-15T23:55:25.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "NW",
    "id": "9e26b2f7-4775-4151-930a-e3b2ddc3d5d4",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "name": "Example device template (updated)",
    "default": "false",
    "category": null,
    "code": null,
    "description": null,
    "make": null,
    "channelTemplates": [
      {
        "id": "9d1fe8ee-6eed-425a-89c1-de65ecf17cd2",
        "name": "_log",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      }
    ]
  }
}

Path Params

id
string
required

The GUID that identifies this device template in all Xively API calls.

Body Params

name
string

The name of the device template.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this device template (optimistic concurrency version). Must be included in API calls to update or delete a device template, in order to prove that the client is aware of the device template's most recent state prior to modifying it.

 
Suggest Edits

Delete a device template

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://blueprint.xively.com/api/v1/devices/templates/id
https://blueprint.xively.com:443/api/v1/devices/templates/9e26b2f7-4775-4151-930a-e3b2ddc3d5d4
A binary file was returned

You couldn't be authenticated

Path Params

id
string
required

The GUID that identifies this device template in all Xively API calls.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this device template (optimistic concurrency version). Must be included in API calls to update or delete device template, in order to prove that the client is aware of the device template's most recent state prior to modifying it.

 
Suggest Edits

Recover a device template

First, you must retrieve the version number of the templates you need to recover.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/api/v1/trash/devices/custom-fields/id/recover
https://blueprint.xively.com:443/api/v1/trash/devices/templates/c362fade-766a-4d09-a7d8-32205ba5dbc7/recover
{ 
    url: "https://blueprint.xively.com/api/v1/trash/devices/custom-fields/{id}/recover",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your channel template version>"
    }
}
A binary file was returned

You couldn't be authenticated

{
  "deviceTemplate": {
    "created": "2017-08-10T14:23:50.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-10T14:39:06.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "jm",
    "id": "c362fade-766a-4d09-a7d8-32205ba5dbc7",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "name": "Unnamed device template 1",
    "default": "false",
    "category": null,
    "code": null,
    "description": null,
    "make": null,
    "channelTemplates": [
      {
        "id": "a64d00ef-493f-4c6b-ab65-b0737f10737e",
        "name": "_log",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "id": "8874e430-9500-4a24-b2e7-b6575482c55b",
        "name": "_set/fields",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "id": "761a1b2e-73cd-42c2-82f2-110eef43d96e",
        "name": "_updates/fields",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "id": "6c38aa96-c91e-45b3-b5e5-016cdbbd29c6",
        "name": "_rejected",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      }
    ]
  }
}

Path Params

id
string
required

The GUID that identifies this device template in all Xively API calls.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this device template (optimistic concurrency version). Must be included in API calls to update or delete device template, in order to prove that the client is aware of the device template's most recent state prior to modifying it.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve the version number of a single deleted device template

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/devices/custom-fields/id
https://blueprint.xively.com:443/api/v1/trash/devices/templates/c362fade-766a-4d09-a7d8-32205ba5dbc7
A binary file was returned

You couldn't be authenticated

{
  "deviceTemplate": {
    "created": "2017-08-10T14:23:50.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-10T14:24:19.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "Vl",
    "id": "c362fade-766a-4d09-a7d8-32205ba5dbc7",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "name": "Unnamed device template 1",
    "default": "false",
    "category": null,
    "code": null,
    "description": null,
    "make": null,
    "channelTemplates": [
      {
        "id": "a64d00ef-493f-4c6b-ab65-b0737f10737e",
        "name": "_log",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "id": "8874e430-9500-4a24-b2e7-b6575482c55b",
        "name": "_set/fields",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "id": "761a1b2e-73cd-42c2-82f2-110eef43d96e",
        "name": "_updates/fields",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      },
      {
        "id": "6c38aa96-c91e-45b3-b5e5-016cdbbd29c6",
        "name": "_rejected",
        "flags": {
          "deviceUpdatable": true,
          "timeSeries": false
        },
        "kinesisBridgeDelivery": 0,
        "serviceTopic": true,
        "persistenceType": "simple"
      }
    ]
  }
}

Path Params

id
string
required

The GUID that identifies this device template in all Xively API calls.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve the version number of multiple deleted device templates

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/devices/custom-fields/
https://blueprint.xively.com:443/api/v1/trash/devices/templates?accountId=dcfad7c8-90a4-441c-bf9d-fbfafd614771&&&meta=true&results=true&page=1&pageSize=10&&sortOrder=asc&
A binary file was returned

You couldn't be authenticated

{
  "deviceTemplates": {
    "results": [
      {
        "created": "2017-08-10T14:23:50.000Z",
        "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "lastModified": "2017-08-10T14:24:19.000Z",
        "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "version": "Vl",
        "id": "c362fade-766a-4d09-a7d8-32205ba5dbc7",
        "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
        "name": "Unnamed device template 1",
        "default": "false",
        "category": null,
        "code": null,
        "description": null,
        "make": null,
        "channelTemplates": [
          {
            "id": "a64d00ef-493f-4c6b-ab65-b0737f10737e",
            "name": "_log",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          },
          {
            "id": "8874e430-9500-4a24-b2e7-b6575482c55b",
            "name": "_set/fields",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          },
          {
            "id": "761a1b2e-73cd-42c2-82f2-110eef43d96e",
            "name": "_updates/fields",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          },
          {
            "id": "6c38aa96-c91e-45b3-b5e5-016cdbbd29c6",
            "name": "_rejected",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          }
        ]
      }
    ],
    "meta": {
      "count": 1,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Path Params

accountID
string
required

The GUID that identifies your Xively account.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

List all device templates

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/devices/templates
https://blueprint.xively.com:443/api/v1/devices/templates?accountId=f85e4fda-827d-46ff-9537-d4b453b27cde&&&meta=true&results=true&page=1&pageSize=100&sortBy=name&sortOrder=asc&count=devices%2Cdevice-fields
A binary file was returned

You couldn't be authenticated

 {
  "deviceTemplates": {
    "results": [
      {
        "created": "2016-10-15T23:31:09.000Z",
        "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "lastModified": "2016-10-15T23:31:09.000Z",
        "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "version": "Da",
        "id": "41bda565-6b9a-41d2-b564-26608e43e306",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "name": "aaaa",
        "default": "false",
        "deviceCount": 0,
        "deviceFieldCount": 0,
        "category": null,
        "code": null,
        "description": null,
        "make": null,
        "channelTemplates": [
          {
            "id": "9d1fe8ee-6eed-425a-89c1-de65ecf17cd2",
            "name": "_log",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          }
        ]
      },
      {
        "created": "2016-10-15T18:37:27.000Z",
        "createdById": "ac9f9a60-7bb2-4563-b62f-52a77d2be1f4",
        "lastModified": "2016-10-15T18:37:27.000Z",
        "lastModifiedById": "ac9f9a60-7bb2-4563-b62f-52a77d2be1f4",
        "version": "mk",
        "id": "71189f7a-5e1e-449f-a4c0-eb5a8c725e6d",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "name": "Default Device Template",
        "default": "true",
        "deviceCount": 1,
        "deviceFieldCount": 1,
        "category": null,
        "code": null,
        "description": null,
        "make": null,
        "channelTemplates": [
          {
            "id": "ff94cdb0-cf1b-4c13-a083-751adb3c5d8d",
            "name": "Default Channel 1",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "kinesisBridgeDelivery": 0,
            "serviceTopic": false,
            "persistenceType": "simple"
          },
          {
            "id": "9300f8e0-288b-4915-abf7-b67052a22dcf",
            "name": "Default Channel 2",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "kinesisBridgeDelivery": 0,
            "serviceTopic": false,
            "persistenceType": "simple"
          },
          {
            "id": "551e6caa-5d95-4fc0-89c2-e7378ad43f85",
            "name": "Default Channel 3",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": true
            },
            "kinesisBridgeDelivery": 0,
            "serviceTopic": false,
            "persistenceType": "timeSeries"
          },
          {
            "id": "9d1fe8ee-6eed-425a-89c1-de65ecf17cd2",
            "name": "_log",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          }
        ]
      },
      {
        "created": "2016-10-15T18:40:46.000Z",
        "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "lastModified": "2016-10-15T18:40:46.000Z",
        "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "version": "QW",
        "id": "9e26b2f7-4775-4151-930a-e3b2ddc3d5d4",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "name": "Example device template",
        "default": "false",
        "deviceCount": 0,
        "deviceFieldCount": 0,
        "category": null,
        "code": null,
        "description": null,
        "make": null,
        "channelTemplates": [
          {
            "id": "9d1fe8ee-6eed-425a-89c1-de65ecf17cd2",
            "name": "_log",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          }
        ]
      },
      {
        "created": "2016-10-15T23:31:14.000Z",
        "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "lastModified": "2016-10-15T23:31:14.000Z",
        "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "version": "69",
        "id": "89d2198f-48e1-42d2-94e5-9f955a4d5cdf",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "name": "zzzzz",
        "default": "false",
        "deviceCount": 0,
        "deviceFieldCount": 0,
        "category": null,
        "code": null,
        "description": null,
        "make": null,
        "channelTemplates": [
          {
            "id": "9d1fe8ee-6eed-425a-89c1-de65ecf17cd2",
            "name": "_log",
            "flags": {
              "deviceUpdatable": true,
              "timeSeries": false
            },
            "kinesisBridgeDelivery": 0,
            "serviceTopic": true,
            "persistenceType": "simple"
          }
        ]
      }
    ],
    "meta": {
      "count": 4,
      "page": 1,
      "pageSize": 100,
      "sortBy": "name",
      "sortOrder": "asc"
    }
  }
}

Query Params

accountId
string
required

The GUID that identifies your Xively Account.

name
string

The name of the device template.

default
boolean

Return the default device template.

meta
boolean

Whether or not to include meta-information in the response (count, page, pageSize, sortOrder).

results
boolean

Whether or not to include results in the response (vs. meta-information only).

page
int32

Which page of results to return.

pageSize
int32

How many items to return per page (max 1000).

sortBy
int32

Choose which query parameter to sort results by (created, lastModified, id, accountId, name, default). Defaults to name.

sortOrder
string

Sort direction (asc, desc). Defaults to asc.

count
string

Shows counts of child entities (devices) and number of custom fields (device-fields). List parameters as a comma-separated list (e.g. "devices,device-fields"), to include multiple counts.

 
Suggest Edits

End-user templates

 
Suggest Edits

The end-user template object

 

Header Auth

 Authentication is required for this endpoint.
optionshttps://blueprint.xively.com/api/v1/end-users/templates
Attributes of the end-user template object are as follows
A binary file was returned

You couldn't be authenticated

Body Params

created
date

The ISO 8601 formatted date on which this end-user template was created. System created, not editable.

createdById
string

The GUID userId of the actor that created this end-user template. System created, not editable.

lastModified
date

The ISO 8601 formatted date on which this end-user template was last modified. System created, not editable.

lastModifiedById
string

The GUID userId of the actor that last modified this end-user template. System created, not editable.

version
string

The unique string that represents the most recent state of this end-user template (optimistic concurrency version). Must be included in API calls to update or delete an end-user template, in order to prove that the client is aware of the end-user template's most recent state prior to modifying it. System created, not editable.

id
string

The GUID that identifies this end-user template in all Xively API calls. System created, not editable, searchable.

accountId
string

The GUID that identifies your Xively Account.

name
string

The name of the end-user template.

default
boolean

When true, this template is the one that will be used if no endUserTemplateId is specified during an end-user creation API call. True only for the "Default End User Template" that appears by default in every account, not editable

endUserCount
int32

The number of child end-users that stem from this template.

 
Suggest Edits

Create end-user template

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/end-users/templates
{
  "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
  "name": "Example end user template"
}
https://blueprint.xively.com:443/api/v1/end-users/templates
A binary file was returned

You couldn't be authenticated

{
  "endUserTemplate": {
    "created": "2016-10-16T04:39:03.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T04:39:03.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "DQ",
    "id": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "name": "Example end user template",
    "default": "false"
  }
}

Body Params

accountId
string
required

The GUID that identifies your Xively Account.

name
string
required

The name of the end-user template.

 
Suggest Edits

Get an end-user template

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/end-users/templates/id
https://blueprint.xively.com:443/api/v1/end-users/templates/5bdcaca6-aae5-4c78-938b-10c892fecc70
A binary file was returned

You couldn't be authenticated

{
  "endUserTemplate": {
    "created": "2016-10-16T04:39:03.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T04:39:03.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "DQ",
    "id": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "name": "Example end user template",
    "default": "false"
  }
}

Path Params

id
string
required

The GUID that identifies this end-user template in all Xively API calls.

Query Params

count
string

Shows counts of child entities (end-users) and number of custom fields (end-user-fields). List parameters as a comma-separated list (e.g. "end-users,end-user-fields"), to include multiple counts.

 
Suggest Edits

Update an end-user template

 

Header Auth

 Authentication is required for this endpoint.
puthttps://blueprint.xively.com/api/v1/end-users/templates/id
{
  "name": "Example end-user template (updated)"
}
https://blueprint.xively.com:443/api/v1/end-users/templates/5bdcaca6-aae5-4c78-938b-10c892fecc70
A binary file was returned

You couldn't be authenticated

{
  "endUserTemplate": {
    "created": "2016-10-16T04:39:03.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T04:47:20.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "vQ",
    "id": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "name": "Example end-user template (updated)",
    "default": "false"
  }
}

Path Params

id
string
required

The GUID that identifies this end-user template in all Xively API calls.

Body Params

name
string

The name of the end-user template.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this end-user template (optimistic concurrency version). Must be included in API calls to update or delete an end-user template, in order to prove that the client is aware of the end-user template's most recent state prior to modifying it.

 
Suggest Edits

Recover an end-user template

First, you must retrieve the version number of the templates you need to recover.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/api/v1/trash/end-users/templates/id/recover
https://blueprint.xively.com:443/api/v1/trash/end-users/templates/b4729357-615b-48c2-bec7-8d87af0d2dbb/recover
{ 
    url: "https://blueprint.xively.com/api/v1/trash/end-users/templates/{id}/recover",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your channel template version>"
    }
}
A binary file was returned

You couldn't be authenticated

{
  "endUserTemplate": {
    "created": "2017-08-01T14:33:05.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-10T15:11:41.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "54",
    "id": "b4729357-615b-48c2-bec7-8d87af0d2dbb",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "name": "test",
    "default": "false"
  }
}

Path Params

id
string
required

The GUID that identifies this end-user template in all Xively API calls.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this end-user template (optimistic concurrency version). Must be included in API calls to update or delete an end-user template, in order to prove that the client is aware of the end-user template's most recent state prior to modifying it.

 

Important

Suggest Edits

Retrieve the version number of a single end-user template

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/end-users/templates/id
https://blueprint.xively.com:443/api/v1/trash/end-users/templates/b4729357-615b-48c2-bec7-8d87af0d2dbb
A binary file was returned

You couldn't be authenticated

{
  "endUserTemplate": {
    "created": "2017-08-01T14:33:05.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-01T14:33:17.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "RL",
    "id": "b4729357-615b-48c2-bec7-8d87af0d2dbb",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "name": "test",
    "default": "false"
  }
}

Path Params

id
string
required

The GUID that identifies this end-user template in all Xively API calls.

 

Important

Suggest Edits

Retrieve the version number of multiple end-user templates

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/end-users/templates/
https://blueprint.xively.com:443/api/v1/trash/end-users/templates?accountId=dcfad7c8-90a4-441c-bf9d-fbfafd614771&&&meta=true&results=true&page=1&pageSize=10&&sortOrder=asc&
A binary file was returned

You couldn't be authenticated

{
  "endUserTemplates": {
    "results": [
      {
        "created": "2017-08-01T14:33:05.000Z",
        "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "lastModified": "2017-08-01T14:33:17.000Z",
        "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "version": "RL",
        "id": "b4729357-615b-48c2-bec7-8d87af0d2dbb",
        "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
        "name": "test",
        "default": "false"
      }
    ],
    "meta": {
      "count": 1,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Path Params

accountID
string
required

The GUID that identifies your Xively account.

 

Important

Suggest Edits

List all end-user templates

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/end-users/templates
https://blueprint.xively.com:443/api/v1/end-users/templates?accountId=f85e4fda-827d-46ff-9537-d4b453b27cde&meta=true&results=true&page=1&pageSize=10&sortOrder=asc&
A binary file was returned

You couldn't be authenticated

{
  "endUserTemplates": {
    "results": [
      {
        "created": "2016-10-15T18:37:27.000Z",
        "createdById": "ac9f9a60-7bb2-4563-b62f-52a77d2be1f4",
        "lastModified": "2016-10-15T18:37:27.000Z",
        "lastModifiedById": "ac9f9a60-7bb2-4563-b62f-52a77d2be1f4",
        "version": "Da",
        "id": "35d21d89-5691-453d-a053-2620cfa9e7db",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "name": "Default End User Template",
        "default": "true"
      },
      {
        "created": "2016-10-16T04:39:03.000Z",
        "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "lastModified": "2016-10-16T04:39:03.000Z",
        "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "version": "DQ",
        "id": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "name": "Example end user template",
        "default": "false"
      }
    ],
    "meta": {
      "count": 2,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Query Params

accountId
string
required

The GUID that identifies your Xively Account.

name
string

The name of the end-user template.

default
boolean

Return the default end-user template.

meta
boolean

Whether or not to include meta-information in the response (count, page, pageSize, sortOrder).

results
boolean

Whether or not to include results in the response (vs. meta-information only).

page
int32

Which page of results to return.

pageSize
int32

How many items to return per page (max 1000).

sortBy
int32

Choose which query parameter to sort results by (created, lastModified, id, accountId, name, default). Defaults to name.

sortOrder
string

Sort direction (asc, desc). Defaults to asc.

count
string

ser-fields`). List parameters as a comma-separated list (e.g. "end-users,end-user-fields"), to include multiple counts.

 
Suggest Edits

Organization templates

 

Organization templates from API endpoints are called "group templates" in the Xively management app. Their functionality is the same, the difference is only in the naming convention.

Suggest Edits

The organization template object

 

Header Auth

 Authentication is required for this endpoint.
optionshttps://blueprint.xively.com/api/v1/organizations/templates
Attributes of the organization template object are as follows
A binary file was returned

You couldn't be authenticated

Body Params

created
date

The ISO 8601 formatted date on which this organization template was created. System created, not editable.

createdById
string

The GUID userId of the actor that created this organization template. System created, not editable.

lastModified
date

The ISO 8601 formatted date on which this organization template was last modified. System created, not editable.

lastModifiedById
string

The GUID userId of the actor that last modified this organization template. System created, not editable.

version
string

The unique string that represents the most recent state of this organization template (optimistic concurrency version). Must be included in API calls to update or delete an organization template, in order to prove that the client is aware of the organization template's most recent state prior to modifying it. System created, not editable.

id
string

The GUID that identifies this organization template in all Xively API calls. System created, not editable, searchable.

accountId
string

The GUID that identifies your Xively Account.

name
string

The name of the organization template.

default
boolean

When true, this template is the one that will be used if no organizationTemplateId is specified during an organization creation API call. True only for the "Default Organization Template" that appears by default in every account, not editable

organizationCount
int32

The number of child organizations that stem from this template.

 
Suggest Edits

Create an organization template

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/organizations/templates
{
  "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
  "name": "Example organization template"
}
https://blueprint.xively.com:443/api/v1/organizations/templates
A binary file was returned

You couldn't be authenticated

{
  "organizationTemplate": {
    "created": "2016-10-16T01:52:20.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T01:52:20.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "ab",
    "id": "a75e1dac-272b-402a-851e-e4fb00b6bde2",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "name": "Example organization template",
    "default": "false"
  }
}

Body Params

accountId
string
required

The GUID that identifies your Xively Account.

name
string
required

The name of the organization template.

 
Suggest Edits

Get an organization template

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/organizations/templates/id
https://blueprint.xively.com:443/api/v1/organizations/templates/a75e1dac-272b-402a-851e-e4fb00b6bde2
A binary file was returned

You couldn't be authenticated

{
  "organizationTemplate": {
    "created": "2016-10-16T01:52:20.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T01:52:20.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "ab",
    "id": "a75e1dac-272b-402a-851e-e4fb00b6bde2",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "name": "Example organization template",
    "default": "false"
  }
}

Path Params

id
string
required

The GUID that identifies this organization template in all Xively API calls.

Query Params

count
string

Shows counts of child entities (organizations) and number of custom fields (organization-fields). List parameters as a comma-separated list (e.g. "organizations,organization-fields"), to include multiple counts.

 
Suggest Edits

Update an organization template

 

Header Auth

 Authentication is required for this endpoint.
puthttps://blueprint.xively.com/api/v1/organizations/templates/id
{
  "name": "Example organization template (updated)"
}
https://blueprint.xively.com:443/api/v1/organizations/templates/a75e1dac-272b-402a-851e-e4fb00b6bde2
A binary file was returned

You couldn't be authenticated

{
  "organizationTemplate": {
    "created": "2016-10-16T01:52:20.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T04:29:27.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "rk",
    "id": "a75e1dac-272b-402a-851e-e4fb00b6bde2",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "name": "Example organization template (updated)",
    "default": "false"
  }
}

Path Params

id
string
required

The GUID that identifies this organization template in all Xively API calls.

Body Params

name
string

The name of the organization template.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this organization template (optimistic concurrency version). Must be included in API calls to update or delete an organization template, in order to prove that the client is aware of the organization template's most recent state prior to modifying it.

 
Suggest Edits

Delete an organization template

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://blueprint.xively.com/api/v1/organizations/templates/id
https://blueprint.xively.com:443/api/v1/organizations/templates/9e26b2f7-4775-4151-930a-e3b2ddc3d5d4
A binary file was returned

You couldn't be authenticated

Path Params

id
string
required

The GUID that identifies this device template in all Xively API calls.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this organization template (optimistic concurrency version). Must be included in API calls to update or delete an organization template, in order to prove that the client is aware of the organization template's most recent state prior to modifying it.

 
Suggest Edits

Recover an organization template

First, you must retrieve the version number of the templates you need to recover.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/api/v1/trash/organizations/custom-fields/id/recover
https://blueprint.xively.com:443/api/v1/trash/organizations/templates/0c6aad24-b927-4156-8eee-97554c39aaf9/recover
{ 
    url: "https://blueprint.xively.com/api/v1/trash/organizations/custom-fields/{id}/recover",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your channel template version>"
    }
}
A binary file was returned

You couldn't be authenticated

{
  "organizationTemplate": {
    "created": "2017-08-10T15:21:38.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-10T15:25:05.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "z1",
    "id": "0c6aad24-b927-4156-8eee-97554c39aaf9",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "name": "sdfghsdfgsf",
    "default": "false"
  }
}

Path Params

id
string
required

The GUID that identifies this device template in all Xively API calls.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this organization template (optimistic concurrency version). Must be included in API calls to update or delete an organization template, in order to prove that the client is aware of the organization template's most recent state prior to modifying it.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve the version number of a single organization template

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/organizations/custom-fields/id
https://blueprint.xively.com:443/api/v1/trash/organizations/templates/0c6aad24-b927-4156-8eee-97554c39aaf9
A binary file was returned

You couldn't be authenticated

{
  "organizationTemplate": {
    "created": "2017-08-10T15:21:38.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-10T15:21:43.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "KD",
    "id": "0c6aad24-b927-4156-8eee-97554c39aaf9",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "name": "sdfghsdfgsf",
    "default": "false"
  }
}

Path Params

id
string
required

The GUID that identifies this device template in all Xively API calls.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve the version number of multiple organization templates

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/organizations/custom-fields
https://blueprint.xively.com:443/api/v1/trash/organizations/templates?accountId=dcfad7c8-90a4-441c-bf9d-fbfafd614771&&&meta=true&results=true&page=1&pageSize=10&&sortOrder=asc&
A binary file was returned

You couldn't be authenticated

{
  "organizationTemplates": {
    "results": [
      {
        "created": "2017-08-10T15:21:38.000Z",
        "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "lastModified": "2017-08-10T15:21:43.000Z",
        "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "version": "KD",
        "id": "0c6aad24-b927-4156-8eee-97554c39aaf9",
        "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
        "name": "sdfghsdfgsf",
        "default": "false"
      }
    ],
    "meta": {
      "count": 1,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Path Params

accountID
string
required

The GUID that identifies your Xively account.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

List all organization templates

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/organizations/templates
https://blueprint.xively.com:443/api/v1/organizations/templates?accountId=f85e4fda-827d-46ff-9537-d4b453b27cde&meta=true&results=true&page=1&pageSize=10&&sortOrder=asc&
A binary file was returned

You couldn't be authenticated

{
  "organizationTemplates": {
    "results": [
      {
        "created": "2016-10-15T18:37:27.000Z",
        "createdById": "ac9f9a60-7bb2-4563-b62f-52a77d2be1f4",
        "lastModified": "2016-10-15T18:37:27.000Z",
        "lastModifiedById": "ac9f9a60-7bb2-4563-b62f-52a77d2be1f4",
        "version": "YA",
        "id": "5ab17b64-6514-4dad-80cb-610b8b125cbb",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "name": "Default Organization Template",
        "default": "true"
      },
      {
        "created": "2016-10-16T01:52:20.000Z",
        "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "lastModified": "2016-10-16T01:52:20.000Z",
        "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
        "version": "ab",
        "id": "a75e1dac-272b-402a-851e-e4fb00b6bde2",
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "name": "Example organization template",
        "default": "false"
      }
    ],
    "meta": {
      "count": 2,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Query Params

accountId
string
required

The GUID that identifies your Xively Account.

name
string

The name of the organization template.

default
boolean

Return the default device template.

meta
boolean

Whether or not to include meta-information in the response (count, page, pageSize, sortOrder).

results
boolean

Whether or not to include results in the response (vs. meta-information only).

page
int32

Which page of results to return.

pageSize
int32

How many items to return per page (max 1000).

sortBy
int32

Choose which query parameter to sort results by (created, lastModified, id, accountId, name, default). Defaults to name.

sortOrder
string

Sort direction (asc, desc). Defaults to asc.

count
string

Shows counts of child entities (organizations) and number of custom fields (organization-fields). List parameters as a comma-separated list (e.g. "organizations,organization-fields"), to include multiple counts.

 
Suggest Edits

Custom fields

 

Custom fields allow you to extend the metadata of an entity so that you can store specific, relevant information for your company. Custom fields can be attached to any device template, end-user template, or organization template.

Custom fields will be inherited by every entity which stems from that template, allowing you to store and query their values in Xively without needing an external database.

For example:

  • You could define a purchase date (datetime) field on a device template to store and query devices by the date they were bought
  • You could define a phone number (string) field on an end-user template to store and query your end-users' phone numbers
  • You could define lat & long (lat & long) fields on an organization template to store and query organizations by their geography, if you were using organizations as representations of installation sites or customer households

Custom fields ! = messages

Custom fields are best used to store static information or information that changes infrequently.

Field types

These are the allowed types of custom fields.

Type
Constraints
Example

url

Max 255 chars

www.xively.com

lat

A valid Javascript number between -90 and 90

37.42382538

long

A valid Javascript number between -180 and 180

-122.0829009

datetime

An ISO 8601 formatted date

2015-09-08T01:55:28+00:00

name

String of min 5 max 100 chars

Annabelle

email

String of max 254 chars

annabelle@concaria.com

countryCode

String of max 2 chars

CA

territory

String of max 2 chars

ON

locality

String of max 100 chars

Toronto

postalCode

String of max 10 chars

M5F 7H5

int

Integer

43

string

String of max 255 chars

Concaria Corporation

boolean

Boolean, allowing only "true" or "false"

true

float

A valid Javascript number

3.14159

text

Max 1,000 chars

Concaria Corporation is a diversified original equipment manufacturer that produces residential, commercial and industrial durable equipment. Concaria’s largest division is focused on air quality products and has been selling residential, commercial, and industrial air purifiers for the past 25 years. Concaria has a distribution network sells the majority of their products to contractors who install them in commercial and industrial buildings. They also sell home air purifiers through retail channels. These two main paths to market limit Concaria interaction with the end consumer/user.

The following is the payload to POST, PUT, or DELETE custom fields:

Devices themselves have:
    "deviceVersion"
    "location"
    "name"
    "purchaseDate"

Device templates have:
    "category"
    "code"
    "description"
    "make"
End-users themselves have:
    "address"
    "city"
    "countryCode"
    "emailAddress"
    "name"
    "phoneNumber"
    "postalCode"
    "state"

End-user templates have:
    (no extra custom fields)
Organizations themselves have:
    "address"
    "city"
    "countryCode"
    "description"
    "industry"
    "organizationSize"
    "phoneNumber"
    "postalCode"
    "state"
    "websiteAddress"

Organization templates have:
   (no extra custom fields)
Suggest Edits

The custom field object

 

Header Auth

 Authentication is required for this endpoint.
optionshttps://blueprint.xively.com/api/v1/entityType/custom-fields
Attributes of the custom field object are as follows
A binary file was returned

You couldn't be authenticated

Path Params

entityType
string
required

The type of template to which the custom field is attached. They can be attached to any of end-users, devices, organizations.

Body Params

created
date

The ISO 8601 formatted date on which this custom field was created. System created, not editable.

createdById
string

The GUID userId of the actor that created this custom field. System created, not editable.

lastModified
date

The ISO 8601 formatted date on which this custom field was last modified. System created, not editable.

lastModifiedById
string

The GUID userId of the actor that last modified this custom field. System created, not editable.

version
string

The unique string that represents the most recent state of this custom field (optimistic concurrency version). Must be included in API calls to update or delete a custom field, in order to prove that the client is aware of the custom field's most recent state prior to modifying it. System created, not editable.

id
string

The GUID that identifies this custom field in all Xively API calls. System created, not editable, searchable.

device/endUser/organizationTemplateId
string

The template to which this custom field is attached.

accountId
string

The GUID that identifies your Xively Account.

name
string

The name of the custom field.

fieldType
string

The type of data that is allowed in the field. (Data that does not match the type validation will be rejected). See above for list of possible types.

description
string

A short description of the field's purpose.

required
boolean

Whether or not it is mandatory to provide a value for this field when creating a new entity. (Accepts true or false). Defaults to false.

default
string

The default value of this custom field, if no value is provided on entity creation.

Headers

authorization
string
required

Bearer YOUR-JWT-HERE

 
Suggest Edits

Add a custom field to a template

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/entityType/custom-fields
{
  "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
  "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
  "name": "phone number",
  "fieldType": "string",
  "description": "This is a string field to capture the user's phone number",
  "required": "true"
}
https://blueprint.xively.com:443/api/v1/end-users/custom-fields
A binary file was returned

You couldn't be authenticated

 {
  "endUserField": {
    "created": "2016-10-16T05:10:46.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T05:10:46.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "Er",
    "id": "b4657f44-f61f-4ccb-8c91-2fc13c9d6611",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
    "name": "phone number",
    "fieldType": "string",
    "description": "This is a string field to capture the user's phone number",
    "required": "true",
    "default": null
  }
}

Path Params

entityType
string
required

Specify the type of template to which you are attaching this custom field. Must be one of end-users, devices, organizations.

Body Params

accountId
string
required

The GUID that identifies your Xively Account.

device/endUser/organizationTemplateId
string
required

The template to which this custom field is attached.

name
string
required

The name of the custom field.

fieldType
string
required

The type of data that is allowed in the field. (Data that does not match the type validation will be rejected). See above for list of possible types.

description
string

A short description of the field's purpose.

required
boolean

Whether or not it is mandatory to provide a value for this field when creating a new entity. (Accepts true or false). Defaults to false.

default
string

The default value of this custom field, if no value is provided on entity creation.

 
Suggest Edits

Get a specific custom field

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/entityType/custom-fields/id
https://blueprint.xively.com:443/api/v1/end-users/custom-fields/b4657f44-f61f-4ccb-8c91-2fc13c9d6611
A binary file was returned

You couldn't be authenticated

{
  "endUserField": {
    "created": "2016-10-16T05:10:46.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T05:24:41.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "7X",
    "id": "b4657f44-f61f-4ccb-8c91-2fc13c9d6611",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
    "name": "phone number",
    "fieldType": "string",
    "description": "This is a string field to capture the user's phone number",
    "required": "false",
    "default": null
  }
}

Path Params

entityType
string
required

Specify the type of template this custom field is attached to. Must be one of end-users, devices, organizations.

id
string
required

The GUID (id) of the custom field you are searching for.

 
Suggest Edits

Update a custom field's properties

 

Header Auth

 Authentication is required for this endpoint.
puthttps://blueprint.xively.com/api/v1/entityType/custom-fields/id
{
  "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
  "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
  "name": "phone number",
  "fieldType": "string",
  "description": "This is a string field to capture the user's phone number",
  "required": "true"
}
https://blueprint.xively.com:443/api/v1/end-users/custom-fields
A binary file was returned

You couldn't be authenticated

 {
  "endUserField": {
    "created": "2016-10-16T05:10:46.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-10-16T05:10:46.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "Er",
    "id": "b4657f44-f61f-4ccb-8c91-2fc13c9d6611",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "endUserTemplateId": "5bdcaca6-aae5-4c78-938b-10c892fecc70",
    "name": "phone number",
    "fieldType": "string",
    "description": "This is a string field to capture the user's phone number",
    "required": "true",
    "default": null
  }
}

Path Params

entityType
string
required

Specify the type of template to which you are attaching this custom field in the URL. Must be one of end-users, devices, organizations.

id
string
required

The GUID (id) of the custom field you are updating.

Body Params

accountId
string
required

The GUID that identifies your Xively Account.

device/endUser/organizationTemplateId
string
required

The template to which this custom field is attached.

name
string
required

The name of the custom field.

fieldType
string
required

The type of data that is allowed in the field. (Data that does not match the type validation will be rejected). See above for list of possible types.

description
string

A short description of the field's purpose.

required
boolean

Whether or not it is mandatory to provide a value for this field when creating a new entity. (Accepts true or false). Defaults to false.

default
string

The default value of this custom field, if no value is provided on entity creation.

Headers

etag
string
required

The GUID (id) of the custom field to update.

 

Don't get confused !

This API call is used to update the properties of a custom field at a template level -- NOT the values of it at an entity level!

For example, this is the difference between ...

  • updating the field phone number for all end-users of the template "Home consumer" to now be required (PUT end-users/custom-fields/{id})
  • and setting one specific end-user's phone number field value to "+1 (857) 444-4444" (PUT end-users/{id})
Suggest Edits

Delete a custom field

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://blueprint.xively.com/api/v1/entityType/custom-fields/id
https://blueprint.xively.com:443/api/v1/end-users/custom-fields/b4657f44-f61f-4ccb-8c91-2fc13c9d6611
A binary file was returned

You couldn't be authenticated

Path Params

entityType
string
required

Specify the type of template to which you are attaching this custom field in the URL. Must be one of end-users, devices, organizations.

id
string
required

The GUID (id) of the custom field you are deleting.

Headers

etag
string
required

The GUID (id) of the custom field to update.

 
Suggest Edits

Recover a custom field

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/entityType/custom-fields/id/recover
https://blueprint.xively.com:443/api/v1/trash/organizations/custom-fields/fe557883-84cf-4dde-bdb6-b3fad4f63550/recover
{ 
    url: "https://blueprint.xively.com/api/v1/:entityType/custom-fields/:id/recover",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your channel template version>"
    }
}
A binary file was returned

You couldn't be authenticated

{
  "organizationField": {
    "created": "2017-08-10T15:27:02.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-10T15:31:01.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "6p",
    "id": "fe557883-84cf-4dde-bdb6-b3fad4f63550",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "organizationTemplateId": "625fd6fa-fbe9-4a93-be14-d720d1983829",
    "name": "zffggsgfsfgs",
    "fieldType": "countryCode",
    "description": null,
    "required": "false",
    "default": null
  }
}

Path Params

entityType
string
required

Specify the type of template to which you are attaching this custom field in the URL. Must be one of end-users, devices, organizations.

id
string
required

The GUID (id) of the custom field you are deleting.

Headers

etag
string
required

The GUID (id) of the custom field to update.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve the version number for a single custom field

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/entityType/custom-fields/id
https://blueprint.xively.com:443/api/v1/trash/organizations/custom-fields/fe557883-84cf-4dde-bdb6-b3fad4f63550
A binary file was returned

You couldn't be authenticated

{
  "organizationField": {
    "created": "2017-08-10T15:27:02.000Z",
    "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "lastModified": "2017-08-10T15:27:07.000Z",
    "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
    "version": "Ng",
    "id": "fe557883-84cf-4dde-bdb6-b3fad4f63550",
    "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
    "organizationTemplateId": "625fd6fa-fbe9-4a93-be14-d720d1983829",
    "name": "zffggsgfsfgs",
    "fieldType": "countryCode",
    "description": null,
    "required": "false",
    "default": null
  }
}

Path Params

entityType
string
required

Specify the type of template to which you are attaching this custom field in the URL. Must be one of end-users, devices, organizations.

id
string
required

The GUID (id) of the custom field you are deleting.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve the version numbers for multiple custom field

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/entityType/custom-fields
https://blueprint.xively.com:443/api/v1/trash/organizations/custom-fields?accountId=dcfad7c8-90a4-441c-bf9d-fbfafd614771&&&&&meta=true&results=true&page=1&pageSize=10&&sortOrder=asc
A binary file was returned

You couldn't be authenticated

{
  "organizationFields": {
    "results": [
      {
        "created": "2017-08-10T15:27:02.000Z",
        "createdById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "lastModified": "2017-08-10T15:27:07.000Z",
        "lastModifiedById": "c042d153-d1f2-42c0-84a0-9a0a94677c80",
        "version": "Ng",
        "id": "fe557883-84cf-4dde-bdb6-b3fad4f63550",
        "accountId": "dcfad7c8-90a4-441c-bf9d-fbfafd614771",
        "organizationTemplateId": "625fd6fa-fbe9-4a93-be14-d720d1983829",
        "name": "zffggsgfsfgs",
        "fieldType": "countryCode",
        "description": null,
        "required": "false",
        "default": null
      }
    ],
    "meta": {
      "count": 1,
      "page": 1,
      "pageSize": 10,
      "sortOrder": "asc"
    }
  }
}

Path Params

entityType
string
required

Specify the type of template to which you are attaching this custom field in the URL. Must be one of end-users, devices, organizations.

id
string
required

The GUID (id) of the custom field you are deleting.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

List a template's custom fields

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/entityType/custom-fields
Attributes of the custom field object are as follows
A binary file was returned

You couldn't be authenticated

Path Params

entityType
string
required

Specify the type of template to which you are attaching this custom field in the URL. Must be one of end-users, devices, organizations.

Body Params

device/endUser/organizationTemplateId
string
required

The template whose custom fields you are searching for.

accountId
string
required

The GUID that identifies your Xively Account.

name
string

The name of the custom field.

fieldType
string

The type of data that is allowed in the field. See above for list of possible types.

required
boolean

Whether or not to return only required custom fields. Defaults to false.

default
string

The default value of this custom field, if no value is provided on entity creation.

meta
boolean

Whether or not to include meta-information in the response (count, page, pageSize, sortOrder)

results
boolean

Whether or not to include results in the response (vs. meta-information only). Defaults to true.

page
int32

Which page of results to return.

pageSize
int32

How many items to return per page (max 1000).

sortBy
string

Choose which query parameter to sort results by (created, lastModified, id, accountId, device/endUser/organizationTemplateId, name, fieldType, required). Defaults to name.

sortOrder
string

Sort direction (asc, desc). Defaults to asc.

 
Suggest Edits

Channel templates

 

Channel templates are represented in Blueprint through the channels/templates endpoint. A channel template is attached to a device template, and all the devices derived from that device template have their own instance of the channel. The channel name represents the last portion of the MQTT topic (path) that devices use to communicate through the Xively Gateway.

Suggest Edits

The channel template object

 

Header Auth

 Authentication is required for this endpoint.
optionshttps://blueprint.xively.com/api/v1/channels/templates
Attributes of the channelTemplate object are as follows
A binary file was returned

You couldn't be authenticated

Body Params

created
date

The ISO 8601 formatted date on which this channel template was created. System created, not editable.

createdById
string

The GUID userId of the actor that created this channel template. System created, not editable.

lastModified
date

The ISO 8601 formatted date on which this channel template was last modified. System created, not editable.

lastModifiedById
string

The GUID userId of the actor that last modified this channel template. System created, not editable.

version
string

The unique string that represents the most recent state of this channel template (optimistic concurrency version). Must be included in API calls to update or delete a channel template, in order to prove that the client is aware of the channel template's most recent state prior to modifying it. System created, not editable.

id
string

The GUID that identifies this channel template in all Xively API calls. System created, not editable, searchable.

accountId
string

The GUID that identifies your Xively Account.

entityId
string

The GUID (id) that identifies the device template to which this channel template is attached.

entityType
string

The type of template to which this channel template is attached. It has to be set to deviceTemplate.

name
string

The name of the channel template. Cannot start with underscore (_).

kinesisBridgeDelivery
int32

The Kinesis Bridge delivery method: 0 - do not send, 1 - best effort delivery, 2 - guaranteed delivery.

flags
object

This parameter is reserved for internal Xively use.

 
serviceTopic
boolean

This parameter is reserved for internal Xively use. For internal service channels it is set to true, for all other channels it is set to false. System created, not editable.

persistenceType
string

Channel data storage strategy. Defines whether the channel type is timeSeries (data from this channel is stored in the Time Series databse) or simple (data is not stored). Defaults to simple.

 
Suggest Edits

Create a channel template

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/channels/templates
{
    url: "https://blueprint.xively.com/api/v1/channels/templates",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>"
    }
    body {
        "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
        "entityId": "<device-template-ID-to-which-the-channel-template-is-attached>",
        "entityType": "deviceTemplate",
        "name": "<channel-template-name>",
        "kinesisBridgeDelivery": 0,
        "persistenceType": "timeSeries"
    }
}
A binary file was returned

You couldn't be authenticated

{ 
  "channelTemplate": {
    "created": "2016-12-14T11:02:48.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-12-14T11:02:48.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "37",
    "id": "58f265d0-07eb-4b6d-b2d7-2c1cbe2e25d0",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "entityId": "988d3640-3b96-4a62-b79e-b4f636871ac6",
    "entityType": "deviceTemplate",
    "name": "humidity",
    "kinesisBridgeDelivery": 0,
    "flags": {
      "deviceUpdatable": true,
      "timeSeries": true
    },
    "serviceTopic": false,
    "persistenceType": "timeSeries"
  }
}

Body Params

accountId
string
required

The GUID that identifies your Xively Account.

entityId
string
required

The GUID (id) that identifies the device template to which this channel template is attached.

entityType
string
required

Must be populated with the string deviceTemplate.

name
string
required

The name of the channel template.

kinesisBridgeDelivery
int32

The Kinesis Bridge delivery method. Set one of the following: 0 - do not send, 1 - best effort delivery, 2 - guaranteed delivery.

persistenceType
string

Channel data storage strategy. If set to timeSeries, data from this channel is stored in the Time Series databse. If set to simple, data is not stored.

 
Suggest Edits

Get a channel template

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/channels/templates/id
https://blueprint.xively.com/api/v1/channels/templates/58f265d0-07eb-4b6d-b2d7-2c1cbe2e25d0
A binary file was returned

You couldn't be authenticated

{ 
  "channelTemplate": {
    "created": "2016-12-14T11:02:48.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-12-14T11:02:48.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "37",
    "id": "58f265d0-07eb-4b6d-b2d7-2c1cbe2e25d0",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "entityId": "988d3640-3b96-4a62-b79e-b4f636871ac6",
    "entityType": "deviceTemplate",
    "name": "humidity",
    "kinesisBridgeDelivery": 0,
    "flags": {
      "deviceUpdatable": true,
      "timeSeries": true
    },
    "serviceTopic": false,
    "persistenceType": "timeSeries"
  }
}

Path Params

id
string
required

The GUID (id) that identifies the channel template in all Xively API calls. System created, not editable, searchable.

 
Suggest Edits

Update a channel template

 

Header Auth

 Authentication is required for this endpoint.
puthttps://blueprint.xively.com/api/v1/channels/templates/id
{ 
    url: "https://blueprint.xively.com/api/v1/channels/templates",
    method: "put",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your-channel-template-version>"
    }
    body {
        "kinesisBridgeDelivery": 2
    }
}
A binary file was returned

You couldn't be authenticated

{
  "channelTemplate": {
    "created": "2016-12-14T11:02:48.000Z",
    "createdById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "lastModified": "2016-12-14T11:51:12.000Z",
    "lastModifiedById": "15033b16-9095-429c-b0f8-0bb6516ec781",
    "version": "18",
    "id": "58f265d0-07eb-4b6d-b2d7-2c1cbe2e25d0",
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "entityId": "988d3640-3b96-4a62-b79e-b4f636871ac6",
    "entityType": "deviceTemplate",
    "name": "humidity",
    "kinesisBridgeDelivery": 2,
    "flags": {
      "deviceUpdatable": true,
      "timeSeries": true
    },
    "serviceTopic": false,
    "persistenceType": "timeSeries"
  }
}

Path Params

id
string
required

The GUID (id) that identifies this channel template in all Xively API calls.

Body Params

kinesisBridgeDelivery
int32

The Kinesis Bridge delivery method. Set one of the following: 0 - do not send, 1 - best effort delivery, 2 - guaranteed delivery.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this channel template (optimistic concurrency version).

 
Suggest Edits

Delete a channel template

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://blueprint.xively.com/api/v1/channels/templates/id
{ 
    url: "https://blueprint.xively.com/api/v1/channels/templates/id",
    method: "delete",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your channel template version>"
    }
}
A binary file was returned

You couldn't be authenticated

Path Params

id
string
required

The GUID (id) that identifies this channel template in all Xively API calls.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this channel template (optimistic concurrency version).

 
Suggest Edits

Recover a channel template

First, you must retrieve the version number of the templates you need to recover.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://blueprint.xively.com/api/v1/api/v1/trash/channels/templates/id/recover
{ 
    url: "https://blueprint.xively.com/api/v1/channels/templates/id",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your channel template version>"
    }
}
A binary file was returned

You couldn't be authenticated

Path Params

id
string
required

The GUID (id) that identifies this channel template in all Xively API calls.

Headers

etag
string
required

The unique string (version) that represents the most recent state of this channel template (optimistic concurrency version).

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve the version number of a single channel template

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/channels/templates/id
{ 
    url: "https://blueprint.xively.com/api/v1/channels/templates/id",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your channel template version>"
    }
}
A binary file was returned

You couldn't be authenticated

Path Params

id
string
required

The GUID (id) that identifies this channel template in all Xively API calls.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

Retrieve the version number of multiple channel templates

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/api/v1/trash/channels/templates
{ 
    url: "https://blueprint.xively.com/api/v1/channels/templates/id",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>",
        "etag": "<your channel template version>"
    }
}
A binary file was returned

You couldn't be authenticated

Path Params

id
string
required

The GUID (id) that identifies this channel template in all Xively API calls.

 

Important

If it has been more than 30 days since an entity was deleted then the entity cannot be recovered.

Suggest Edits

List all channel templates

 

Header Auth

 Authentication is required for this endpoint.
gethttps://blueprint.xively.com/api/v1/channels/templates
https://blueprint.xively.com/api/v1/channels/templates?accountId=f85e4fda-827d-46ff-9537-d4b453b27cde&persistenceType=timeSeries&meta=true&results=true&sortBy=created&sortOrder=desc
A binary file was returned

You couldn't be authenticated

{
    "channelTemplates": {
        "results": [],
        "meta": {
            "count": 0,
            "pageSize": 0,
            "page": 0,
            "sortBy": "",
            "sortOrder": "asc"
        }
    }
}

Query Params

accountId
string
required

The GUID that identifies your Xively Account.

entityId
string

The GUID (id) that identifies the device template to which this channel template is attached.

name
string

The name of the channel template.

kinesisBridgeDelivery
int32

The Kinesis Bridge delivery method (0, 1, or 2).

persistenceType
string

Channel data storage strategy (timeSeries or simple).

meta
boolean

Whether or not to include meta-information in the response (count, page, pageSize, sortOrder).

results
boolean

Whether or not to include results in the response (vs. meta-information only).

page
int32

Which page of results to return.

pageSize
int32

How many items to return per page (max 1000).

sortBy
string

Choose which query parameter to sort results by (created, lastModified, deleted, id, accountId, entityId, entityType, name, persistenceType).

sortOrder
string

Sort direction (asc, desc). Defaults to asc.

 
Suggest Edits

User profile

 

Use the User profile API in your application to allow end-users to view and modify their profile information.

User profile is an entity in Identity Management (IDM) service that allows users to log in to Xively. This entity contains such user data as the name, email, user's company, department, telephone number and address details. IDM creates a user profile when an app with registered credentials (appId, appToken) calls POST to the https://id.xively.com/api/v1/auth/create-user endpoint or when a new end-user is created in Blueprint with the parameter "createIdmUser": true.

Only the owner of the profile can access their profile details. Otherwise, the API call will be unauthorized. That means that a user does not have access to any other user's profile details. This is also valid for the admins, they cannot view, modify, or delete any profile properties of end-users.

A user cannot delete their own profile. To delete a user identity object, admins and back-end apps must call DELETE to https://id.xively.com/api/v1/internal/users/{userId}.

Suggest Edits

The user profile object

 

Header Auth

 Authentication is required for this endpoint.
optionshttps://id.xively.com/api/v1/profile
Attributes of the user profile object are as follows
A binary file was returned

You couldn't be authenticated

Body Params

userId
string

The GUID that identifies this user identity object (email/password) in all Xively API calls. System created, not editable, searchable.

emailAddress
string

Email address of the user. This email is used for logging into the CPM app. Must be unique within the account.

firstName
string

First name of the user

lastName
string

Last name of the user

name
string

User profile name

phoneNumber
string

The user's telephone number

address
object
 
address.streetAddress
string

Street name and house number

address.city
string

City

address.state
string

State or province

address.postalCode
string

Postal or zip code

address.countryCode
string

The ISO-3166-2 country code

company
string

Company of the user

department
string

Department of the user

emailConfirmed
boolean

This parameter is reserved for internal Xively use. It does not have any impact on the user profile.

 
Suggest Edits

Create a user profile

 
posthttps://id.xively.com/api/v1/auth/create-user
{
   url: "https://id.xively.com/api/v1/auth/create-user",
   method: "post",
   header: {
      "AccessToken": "<your appToken here>"
   },
   body: {
      "emailAddress": "chloe.smith@airco.com",
      "password": "<new user's password>",
      "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
      "applicationId": "<your appID here>",
      "name": "Chloe Smith",
      "firstName": "Chloe",
      "lastName": "Smith"
   }
}
A binary file was returned

You couldn't be authenticated

{
   "userId":"74fa7bec-fef9-4b6a-a729-03e1c4bd6c99",
   "emailAddress":"chloe.smith@airco.com",
   "accountId":"f85e4fda-827d-46ff-9537-d4b453b27cde",
   "createdAt":"2017-03-23T10:53:18.968Z"
}

Body Params

emailAddress
string
required

The user's email

password
string
required

The user's password

accountId
string
required

The GUID id of your account

applicationId
string
required

The GUID appId that identifies your application

name
string

User profile name

firstName
string

First name of the user

lastName
string

Last name of the user

company
string

Company of the user

department
string

Department of the user

phoneNumber
string

The user's telephone number

address
object
 
address.streetAddress
string

Street name and house number

address.city
string

City

address.state
string

State or province

address.postalCode
string

Postal or zip code

address.countryCode
string

The ISO-3166-2 country code

emailConfirmed
boolean

This parameter is reserved for internal Xively use. It does not have any impact on the user profile.

Headers

AccessToken
string
required

Application token appToken of the application that makes the call

 
Suggest Edits

Get a user profile

 

Header Auth

 Authentication is required for this endpoint.
gethttps://id.xively.com/api/v1/profile/userId
https://id.xively.com/api/v1/profile/74fa7bec-fef9-4b6a-a729-03e1c4bd6c99
A binary file was returned

You couldn't be authenticated

{
  "firstName": "Chloe",
  "lastName": "Smith",
  "name": "Chloe",
  "phoneNumber": "+1234567890",
  "emailConfirmed": false,
  "company": "AirCo",
  "department": "other",
  "userId": "74fa7bec-fef9-4b6a-a729-03e1c4bd6c99",
  "emailAddress": "chloe.smith@airco.com"
}

Path Params

userId
string
required

The GUID that identifies this user identity object (email/password) in all Xively API calls. Only the owner of the profie can access their profile details.

 
Suggest Edits

Update a user profile

 

Header Auth

 Authentication is required for this endpoint.
posthttps://id.xively.com/api/v1/profile/update
{  
   url: "https://id.xively.com/api/v1/profile/update",
   method: "post",
   header: {  
      "authorization": "Bearer <your-JWT-here>"
   },
   body: {  
      "userId": "74fa7bec-fef9-4b6a-a729-03e1c4bd6c99",
      "phoneNumber": "+10987654321",
      "address": {  
         "city": "Brighton"
      }
   }
}
A binary file was returned

You couldn't be authenticated

{
  "success": true,
  "user": {
    "userId": "74fa7bec-fef9-4b6a-a729-03e1c4bd6c99"
  }
}

Body Params

userId
string
required

The GUID that identifies this user identity object (email/password) in all Xively API calls.

firstName
string

First name of the user

lastName
string

Last name of the user

name
string

User profile name

phoneNumber
string

The user's telephone number

address
object
 
address.streetAddress
string

Street name and house number

address.city
string

City

address.state
string

State or province

address.postalCode
string

Postal or zip code

address.countryCode
string

The ISO-3166-2 country code

company
string

Company of the user

department
string

Department of the user

 
Suggest Edits

Change a user's password

 

Header Auth

 Authentication is required for this endpoint.
posthttps://id.xively.com/api/v1/profile/change-password
{
    url: "https://id.xively.com/api/v1/profile/change-password",
    method: "post",
    header: {
        "authorization": "Bearer <your-JWT-here>"
    },
    body: {
        "userId": "74fa7bec-fef9-4b6a-a729-03e1c4bd6c99",
        "oldPassword": "<old-password>",
        "newPassword": "<new-password>"
    }
}
A binary file was returned

You couldn't be authenticated

{
  "success": true,
  "user": {
    "userId": "74fa7bec-fef9-4b6a-a729-03e1c4bd6c99"
  }
}

Body Params

userId
string
required
oldPassword
string
required
newPassword
string
required
 
Suggest Edits

Get a user ID

 
gethttps://id.xively.com/api/v1/users/by-email/email/user-id
curl --request GET \
  --url 'https://id.xively.com/api/v1/users/by-email/email/user-id?accountId=accountId' \
  --header 'accesstoken: AccessToken'
var request = require("request");

var options = { method: 'GET',
  url: 'https://id.xively.com/api/v1/users/by-email/email/user-id',
  qs: { accountId: 'accountId' },
  headers: { accesstoken: 'AccessToken' } };

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

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

url = URI("https://id.xively.com/api/v1/users/by-email/email/user-id?accountId=accountId")

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

request = Net::HTTP::Get.new(url)
request["accesstoken"] = 'AccessToken'

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://id.xively.com/api/v1/users/by-email/email/user-id?accountId=accountId");
xhr.setRequestHeader("accesstoken", "AccessToken");

xhr.send(data);
import requests

url = "https://id.xively.com/api/v1/users/by-email/email/user-id"

querystring = {"accountId":"accountId"}

headers = {'accesstoken': 'AccessToken'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "success": true,
  "userId": "74fa7bec-fef9-4b6a-a729-03e1c4bd6c99"
}

Path Params

email
string
required

The user's email

Query Params

accountId
string
required

The GUID that identifies the Xively Account to which the user belongs

Headers

AccessToken
string
required

Application token appToken of the application that makes the call

 

The Logging service provides remote error log collection for embedded devices. Logs can be submitted using HTTP or MQTT and retrieved with a high degree of speed and searchability. Using a single log format, the Logging Service can be used to store various log message types from devices, users and apps.

The following are the expected log properties followed by examples. The logging service will accept a single log, or an array of logs. For more information on how to send logs using http and mqtt, refer to Sending logs.

Log properties

Property
Type
HTTP required
MQTT required
Description

sourceTimestamp

number

The device's timestamp of the log entry.

sourceId

guid

yes

The ID of the device, app or user posting the log.

sourceType

string

yes

Valid values are: 'deviceId', 'appId', 'endUserId', 'accountUserId'

accountId

guid

yes

The account Id the logging entity belongs to.

message

string

yes

yes

The log message.

code

number

A user defined status code for this particular log.

details

string

Additional Details about the log. e.g. a stacktrace

severity

string

Valid values are : 'emergency', 'alert', 'critical', 'error', 'warning', 'notice', 'informational', 'debug', 'lifecycle'

tags

array

A collection of contextual tags for the log event.

custom

json object

An object containing user defined properties for the log.

Device lifecycle logs

Some logs are attached to devices automatically on operational lifecycle events. They are:

  • Device defined. Device is created in Xively.
  • Device activated. Device password is generated for the first time.
  • Device associated. An association code is used to move the device into an organization.
  • Device deleted. The device is deleted (logs can still be queried for deleted devices).
  • Device connected. The device CONNECTs to the message broker.
  • Device disconnected . The device is disconnected from the messaging broker (either with a DISCONNECT or by failing to respond to an MQTT keepalive).
Suggest Edits

Sending logs

 
posthttps://logging.xively.com/api/v1/logs/
{
  "accountId": "48572C1A-58E8-4035-88A9-3950CCB16C22",
  "sourceTimestamp" : "1455657352000",
  "sourceId" : "27F46C30-2445-43A3-B55E-6938090E651E",
  "sourceType" : "deviceId",
  "code" : "500",
  "message" : "Out Of Memory",
  "details" : "Allocation Failed. Allocated: 25214 kilobytes Free: 256 bytes",
  "severity" : "critical",
  "tags" : ["cached"]
}
A binary file was returned

You couldn't be authenticated

{
  "success": "true"
}
 

Sending multiple logs at once

The Logging Service endpoint will accept a POST with the payload of a single log or an array of logs.

Sending logs over MQTT

Every device is created with a default logging channel called _log which appears by default and cannot be removed. (For more on MQTT messaging, see the Messaging section).

Only send single log entries via MQTT

MQTT logging does not support an array of logs.

xi/blue/v1/7831A4EB-23FA-4463-8D2D-994AB3561664/d/B936D898-1CA5-41B9-9735-D9A6E13CA59F/_log
{
  "sourceTimestamp" : "1455657352000",
  "code" : "500",
  "message" : "Out Of Memory",
  "details" : "Allocation Failed. Allocated: 25214 kilobytes Free: 256 bytes",
  "severity" : "critical",
  "tags" : ["cached"]
}

Note: accountId, sourceType and sourceId are implied from the topic, and are not required for MQTT logging.

Suggest Edits

Retrieving logs

 

Header Auth

 Authentication is required for this endpoint.
gethttps://logging.xively.com/api/v1/logs/device/deviceId
curl --request GET \
  --url https://logging.xively.com/api/v1/logs/device/deviceId
var request = require("request");

var options = { method: 'GET',
  url: 'https://logging.xively.com/api/v1/logs/device/deviceId' };

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

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

url = URI("https://logging.xively.com/api/v1/logs/device/deviceId")

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://logging.xively.com/api/v1/logs/device/deviceId");

xhr.send(data);
import requests

url = "https://logging.xively.com/api/v1/logs/device/deviceId"

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

print(response.text)
A binary file was returned

You couldn't be authenticated

{

    results: [{
  "sourceId": "85a03d72-c0e9-4c52-9610-ed049cf53091",
  "accountId": "3a9fa0ee-532c-46c5-8c91-5d773f35660e",
  "organizationId": null,
  "deviceTemplateId": "7e4780fe-8a76-466c-baf7-a51eb4a56b92",
  "sourceType": "deviceId",
  "message": "Device Activated",
  "severity": "lifecycle",
  "serviceTimestamp": 1506026848457
    }]
    meta: {
      page: 1,
      pageSize: 100,
      count: 55,
      sortBy: 'serviceTimestamp',
      sortOrder: 'descending',
      filterFrom: 1234567,
      filterTo: 7891100
}

Query Params

to
string

The most recent log date for the query. Must consist of standard ISO date and time format: '2017-09-01T09:40:13.866Z'. Default is the time when the API call is made

from
string

The beginning log times. Must consist of standard ISO date and time format.

severity
string

Optional. Can be one of the following: 'emergency', 'alert', 'critical', 'error', 'warning', 'notice', 'informational', 'debug', 'lifecycle'

page
int32

The number of the page of logs you want to retrieve.

pagesize
int32

The number of log entries per page. Minimum value of 1 and a maximum of 100

Headers

Authorization
string

Optional. Can contain your JWT

Cookies
string

Optional. Can contain your JWT (xively-access-token), CSRF (xively-csrf-token).

Content-Type
string

application/json

xively-csrf-token
string

Optional. Needed when using authorization with Cookies.

 
Suggest Edits

Time series data

 

The Xively Time Series service exposes historical data that has been captured from devices.

The lifetime of any brokered device communication is defined by the Quality of Service (QoS) level of the MQTT protocol; however such exchange of data is not intended to be persistent and bulk storage is not possible.

Time Series messaging follows the same subscribe/publish model of standard MQTT communication, with two main differences: the required channel type and the payload format.

Channel type

Historical device data is only available on timeSeries-type channels.
Tip: Learn more about configuring channels in Blueprint here.

Payload format

Time Series messages must follow the SenML standard, a low-footprint format designed to represent simple sensor measurements.

The timeseries data point object

Name
Type

time

dateTime (ISO 8601)

category

string

numericValue

numeric

stringValue

string

SenML

Learn more about the SenML format here.

Note: Non-SenML messaging is still available on timeSeries channels for standard publish/subscribe scenarios, but Xively ignores message bodies not in the SenML format.

Suggest Edits

Publishing timeseries data

 

Data published by devices to Xively using the MQTT protocol are retrievable via timeseries API endpoints.

To persist timeseries data in the Xively database, ensure the following:

  • Messages must be published to a channel that has been marked as a timeSeries channel
  • The payload of MQTT messages must be in the proper CSV or SenML-formatted JSON format

As all timeSeries channels are standard MQTT channels, the publishing process is exactly the same as in other scenarios. However, properly-formatted messages sent to timeSeries channels will also be stored for later retrieval.

For the full details on how to format time series messages, read the guide on timeseries data.

Normal MQTT rules apply

It is possible to publish messages of any format to a timeSeries channel, but only properly formatted data are stored for later retrieval.

Other types of payloads are still delivered as usual, but they are not stored.

libXively auto-formats for time series

Tip: If your device is using libXively, or any other Xively client, SenML formatting can be automatically applied to time series messages.

Suggest Edits

Retrieve the latest timeseries data

 

Header Auth

 Authentication is required for this endpoint.
gethttps://timeseries.xively.com/api/v4/data/topic/latest
https://timeseries.xively.com:443/api/v4/data/YOUR-FULL-CHANNEL-TOPIC-HERE/latest?pageSize=100

For example ...

https://timeseries.xively.com:443/api/v4/data/xi/blue/v1/f85e4fda-827d-46ff-9537-d4b453b27cde/d/ed514e97-6d5b-4774-9ca2-cb0a62c6a2f8/exampleTimeseriesChannel/latest?pageSize=100
A binary file was returned

You couldn't be authenticated

{
  "meta": {
    "timeSpent": 21,
    "start": "2016-10-16T20:36:43Z",
    "end": "2016-10-16T20:24:08Z",
    "count": 8,
    "pagingToken": null
  },
  "result": [
    {
      "time": "2016-10-16T20:36:43Z",
      "category": "Voltage",
      "numericValue": 1.25
    },
    {
      "time": "2016-10-16T20:36:41Z",
      "category": "Voltage",
      "numericValue": 1.25
    },
    {
      "time": "2016-10-16T20:36:37Z",
      "category": "Voltage",
      "numericValue": 1.25
    },
    {
      "time": "2016-10-16T20:24:24Z",
      "category": "Voltage",
      "numericValue": 1.25,
      "stringValue": "Normal"
    },
    {
      "time": "2016-10-16T20:24:21Z",
      "category": "Voltage",
      "numericValue": 1.25,
      "stringValue": "Normal"
    },
    {
      "time": "2016-10-16T20:24:17Z",
      "category": "Voltage",
      "numericValue": 1.25,
      "stringValue": "Normal"
    },
    {
      "time": "2016-10-16T20:24:12Z",
      "category": "Voltage",
      "numericValue": 1.25,
      "stringValue": "Normal"
    },
    {
      "time": "2016-10-16T20:24:08Z",
      "category": "Voltage",
      "numericValue": 1.25,
      "stringValue": "Normal"
    }
  ]
}

Path Params

topic
string
required

Topic name ("xi/blue/v1/{accountId}/d/{deviceId}/{channelName}")

Query Params

pageSize
int32
required

Number of most recent items to retrieve on this channel. (Must be between 1 and 100).

omitNull
boolean

Whether or