REST API Requests

Account Management

Create an Account With Email

POST https://api.cloudofthings.com/v3/companies/<company_id>/users/register/

Register user with email, password and username are optional.

Example request:

POST /v3/companies/%3Ccompany_id%3E/users/register/ HTTP/1.1
Host: api.cloudofthings.com
Content-Type: application/json

{
  "email": "<new_user_email>",
  "password":"SOMEPASS",
  "username":"REQUESTED_USERNAME"
}

Create an Account with Phone Number

POST https://api.cloudofthings.com/v3/companies/<company_id>/users/register/

Register user with phone number, username is optional

Example request:

POST /v3/companies/%3Ccompany_id%3E/users/register/ HTTP/1.1
Host: api.cloudofthings.com
Content-Type: application/json

{
  "phonenumber": "{{new_user_phonenumber}}",
  "username":"REQUESTED_USERNAME"
}

Login with Username

POST https://api.cloudofthings.com/v3/companies/<company_id>/users/login/

Using login will return your API key, and using that supplied API key you can use other API services. The API key will be returned as soon as you activate your account from the link given in your email registration notice. (In case an email registration notice was not received, check you spam folder or use the resend email API.)

Example request:

POST /v3/companies/%3Ccompany_id%3E/users/login/ HTTP/1.1
Host: api.cloudofthings.com
Content-Type: application/x-www-form-urlencoded

{
  "password":"<new_user_password>",
  "username":"<new_user_name>"
}

Login with Email

POST https://api.cloudofthings.com/v3/companies/<company_id>/users/login/

Using login will return your API key, and using that supplied API key you can use other API services. The API key will be returned as soon as you activate your account from the link given in your email registration notice. (In case an email registration notice was not received, check you spam folder or use the resend email API.)

Example request:

POST /v3/companies/%3Ccompany_id%3E/users/login/ HTTP/1.1
Host: api.cloudofthings.com
Content-Type: application/json

{
  "password":"<new_user_password>",
  "email":"<new_user_name>"
}

Login with Phone Number

POST https://api.cloudofthings.com/v3/companies/<company_id>/users/login/

Using login will return your API key, and using the supplied API key you can use other API services.

Example request:

POST /v3/companies/%3Ccompany_id%3E/users/login/ HTTP/1.1
Host: api.cloudofthings.com
Content-Type: application/json

{
  "password":"<new_user_password>",
  "phonenumber":"{{new_user_phonenumber}}"
}

Validate Phone Number (with code)

POST https://api.cloudofthings.com/v3/companies/<company_id>/users/validate_number/

This URL allows you to take the key sent to you by SMS message and input it to validate the phone number you entered for your account.

Example request:

POST /v3/companies/%3Ccompany_id%3E/users/validate_number/ HTTP/1.1
Host: api.cloudofthings.com
Content-Type: application/json

{
"phonenumber":"{{new_user_phonenumber}}",
"code":"CODEFROMSMS"
}

*Re-send Activation Email *

GET https://api.cloudofthings.com/v3/companies/<company_id>/users/resendemail/?username={{username}}&company=<company_id>

Re-send account activation email, in case the first one was not received. This call can be used until the user has activated his/her account. In case the user is already active, an error code 400 will be returned with the message “User already active”.

Example request:

GET /v3/companies/%3Ccompany_id%3E/users/resendemail/?username={{username}}&company=<company_id> HTTP/1.1
Host: api.cloudofthings.com

Password Recovery Email

POST https://api.cloudofthings.com/v3/companies/<company_id>/users/forgotpassword/

Using the Forgot Password helper will send your email account a link to reset it. Before using this API, you must supply an HTML page that will be rendered for the user when he/she clicks the Reset Password link. (The html template file should contain embedded css and js; for more details please contact us.)

Example request:

POST /v3/companies/%3Ccompany_id%3E/users/forgotpassword/ HTTP/1.1
Host: api.cloudofthings.com
Content-Type: application/json

{
  "email": "<new_user_email>"
}

Password Recovery Phone Number

POST https://api.cloudofthings.com/v3/companies/<company_id>/users/forgotpassword/

Using the Forgot Password helper will send your email account a link to reset it. Before using this API, you must supply an HTML page that will be rendered for the user when he/she clicks the Reset Password link. (The html template file should contain embedded css and js; for more details please contact us.)

Example request:

POST /v3/companies/%3Ccompany_id%3E/users/forgotpassword/ HTTP/1.1
Host: api.cloudofthings.com
Content-Type: application/json

{
  "phonenumber": "{{new_user_phonenumber}}"
}

Delete an Account Email

DELETE https://api.cloudofthings.com/v3/companies/<company_id>/users/remove/

Allows you to remove an email address from your account.

Example request:

DELETE /v3/companies/%3Ccompany_id%3E/users/remove/ HTTP/1.1
Host: api.cloudofthings.com
Content-Type: application/json

{
  "password": "<new_user_password>",
  "email": "<new_user_email>"
}

Delete an Account Phone Number

DELETE https://api.cloudofthings.com/v3/companies/<company_id>/users/remove/

Allows you to remove a phone number from your account.

Example request:

DELETE /v3/companies/%3Ccompany_id%3E/users/remove/ HTTP/1.1
Host: api.cloudofthings.com
Content-Type: application/json

{
  "password": "<new_user_password>",
  "phonenumber": "{{new_user_phonenumber}}"
}

Configuration Management

Get Device Property

GET https://api.cloudofthings.com/v3/devices/<device_id>/properties/?name=<device_property_name>&version=<device_property_version>&signature={{device_property_md5}}

Get a device property by name and version. Optimal network traffic is acheived by http ETag style signature (md5) field. The server will send a new version if the property checksum is different from the client’s checksum for that property, and otherwise it will respond with 304 not modified. (Multiple properties query example: ?name=config,layout&version=0&md5=xxx,yyy)

Example request:

GET /v3/devices/%3Cdevice_id%3E/properties/?name=<device_property_name>&version=<device_property_version>&signature={{device_property_md5}} HTTP/1.1
Host: api.cloudofthings.com
X-API: {{device_api_key}}

Update Device Property

PATCH https://api.cloudofthings.com/v3/devices/<device_id>/properties/?name=<device_property_name>&version=<device_property_version>

Use this to update the last property version.

Example request:

PATCH /v3/devices/%3Cdevice_id%3E/properties/?name=<device_property_name>&version=<device_property_version> HTTP/1.1
Host: api.cloudofthings.com
X-API: {{device_api_key}}
Content-Type: application/json

{
  "image_url":"http://cloudofthings.com/api/db/image.jpg",
  "context_url":"http://cloudofthings.com/api/db/data.db"
}

Data Management

Get Streams Value

GET https://api.cloudofthings.com/v3/devices/<device_id>/streams/

This call will return the values of a device’s streams with its unique device_id.

Example request:

GET /v3/devices/%3Cdevice_id%3E/streams/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>

Set Stream Value

PUT https://api.cloudofthings.com/v3/devices/<device_id>/streams/<stream_id_set>/

You can use this to set the value of a stream with a valid device_id and stream_id_set.

Example request:

PUT /v3/devices/%3Cdevice_id%3E/streams/%3Cstream_id_set%3E/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>
Content-Type: application/json

{
  "content":12
}

Get Stream History

GET https://api.cloudofthings.com/v3/devices/<device_id>/streams/<stream_id_get>/history/?since=1minutes
Paramaters on the query string can be:
  • since=5minutes (all enteries in the last 5 minutes)
  • since=1years (all entries in the last year)

Note that the default is 24 hours, and aggregators can be specified using aggregator=avg value=1 unit=minutes (the default value is 1).

Example request:

GET /v3/devices/%3Cdevice_id%3E/streams/%3Cstream_id_get%3E/history/?since=1minutes HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>

Get Device Groups

GET https://api.cloudofthings.com/v3/devices/4838113bc968434483e88766ff9c931b/groups/

Show all the group that this device belongs to, or that its parent/hub belongs to.

Example request:

GET /v3/devices/4838113bc968434483e88766ff9c931b/groups/ HTTP/1.1
Host: api.cloudofthings.com
x-api: {{device_api_key}}

Create a Device Group

POST https://api.cloudofthings.com/v3/companies/<company_id>/groups/
In order to create a group of devices which you can control by a common group streams 3 things are needed:
  1. the list of devices you want to assign to the group (you must be user/owner on all devices)
  2. a name for a stream (a group stream) that will match multiple streams in the devices that are listed above
  3. stream in each device to match that group stream that you would like to control

Example request:

POST /v3/companies/%3Ccompany_id%3E/groups/ HTTP/1.1
Host: api.cloudofthings.com
x-api: <user_api_key>
Content-Type: application/json

{
    "name": "Kitchen",
    "description": "Control kitchen lights",
    "devices":["a0e736dd11de460b8a8ad651feee25a7","4838113bc968434483e88766ff9c931b"],
    "mapping":[{"on":["9f0e528899e74572b8d4dd400fc44247","87201fa88a3e48d6b8170a9bd441a83b"]},{"dimm":["9360cdaa19ac4161bbc4f1d5fc762fc3","8159bfa3067c456681af0785d0f975b0"]}]
}

Update a Device Group

PATCH https://api.cloudofthings.com/v3/companies/<company_id>/groups/{{group_id}}/

You can use this to update a device group.

Example request:

PATCH /v3/companies/%3Ccompany_id%3E/groups/%7B%7Bgroup_id%7D%7D/ HTTP/1.1
Host: api.cloudofthings.com
x-api: <user_api_key>
Content-Type: application/json

{
    "name": "Kitchen",
    "description": "Control kitchen lights",
    "devices":["a0e736dd11de460b8a8ad651feee25a7","4838113bc968434483e88766ff9c931b"],
    "mapping":[{"on":["9f0e528899e74572b8d4dd400fc44247","87201fa88a3e48d6b8170a9bd441a83b"]},{"dimm":["9360cdaa19ac4161bbc4f1d5fc762fc3","8159bfa3067c456681af0785d0f975b0"]}]
}

Delete a Device Group

DELETE https://api.cloudofthings.com/v3/companies/<company_id>/groups/{{group_id}}/

This call allows you to delete a group by specifying its group_id.

Example request:

DELETE /v3/companies/%3Ccompany_id%3E/groups/%7B%7Bgroup_id%7D%7D/ HTTP/1.1
Host: api.cloudofthings.com
x-api: <user_api_key>
Content-Type: application/json

Device Access

Manage user access level for a device.

The user management API allows an application developer to control the complete lifecycle of a user - owning a device, asking permissions for a device, and revoking user permissions.

The first step of the device lifecycle is attaching a device to an owner. A device that does not have an owner will be automatically assign the first user that requests acess to it as the owner of the device. Subsequent requests of other users to the same device will result in a permission requests to that user, allowing the owner to provide permissions to users as the device is going through its lifecycle.

The following access levels are available in the system:

  • OW: Owner - this user is the owner of the device
  • US: User - this user got read-write permissions from the owner to the device
  • VI: Viewer - this user got read-only permissions from the owner to the device
  • PE: Pending - this user requested permissions that were not granted yet
  • DI: Disabled - this user was rejected permissions by the owner

Request Device Access

POST https://api.cloudofthings.com/v3/devices/<device_id>/deviceusers/

Add a user to a device access list. If a device has no owner then the request will set the user as the owner of the device; otherwise, it will set his level as pending (PE).

Example request:

POST /v3/devices/%3Cdevice_id%3E/deviceusers/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <new_user_api_key>
Content-Type: application/json

Get List of Users for a Device

GET https://api.cloudofthings.com/v3/devices/<device_id>/deviceusers/

Get list of users for a device. This method returns a list of users associated with the device with the access permissions they have. The current user will be marked with “current=true”

Example request:

GET /v3/devices/%3Cdevice_id%3E/deviceusers/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>
Content-Type: application/json

Update User Access-Level

PUT https://api.cloudofthings.com/v3/devices/<device_id>/deviceusers/<user_access_id>/

Change the access level for a user. This method gets a user identifier and an access level parameter and sets the user to that access level, allowing you to redefine access for team members.

Example request:

PUT /v3/devices/%3Cdevice_id%3E/deviceusers/%3Cuser_access_id%3E/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>
Content-Type: application/json

{
  "usertype":"PE"
}

Delete User Access

DELETE https://api.cloudofthings.com/v3/devices/<device_id>/deviceusers/<user_access_id>/

Remove a user from the access list to the device.

Example request:

DELETE /v3/devices/%3Cdevice_id%3E/deviceusers/%3Cuser_access_id%3E/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>

Get Device List

GET https://api.cloudofthings.com/v3/devices/

Get the list of devices accessible by the specific API key.

  • For User API keys - returns the list of devices that the user has access level permssions for. Note that in this case, the system would return only devices that the user was granted permission for.
  • For Device API keys - returns the device and its children
  • For Project and Company API keys - returns the full list of accessible devices.

Example request:

GET /v3/devices/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>

Get Device Commands

GET https://api.cloudofthings.com/v3/devices/<device_id>/commands/

Get the list of commands available for a certain device, identified by device_id.

Example request:

GET /v3/devices/%3Cdevice_id%3E/commands/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>

Device Management

Platform Management

Get Project List

GET https://api.cloudofthings.com/v3/projects/

Returns the list of projects associated with the user or company. Only company or user API keys are allowed.

Example request:

GET /v3/projects/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>
Content-Type: application/json

Get Project Details

GET https://api.cloudofthings.com/v3/projects/{{project_id}}/

This call returns a project’s details.

Example request:

GET /v3/projects/%7B%7Bproject_id%7D%7D/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>
Conte: application/json

Get Project Firmware List

GET https://api.cloudofthings.com/v3/projects/{{project_id}}/firmware/

This call returns a list of firmwares active on devices in a project.

Example request:

GET /v3/projects/%7B%7Bproject_id%7D%7D/firmware/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>
Conte: application/json

Get Project Versions

GET https://api.cloudofthings.com/v3/projects/{{project_id}}/versions/

This call returns all the versions of a project, identified by the project_id.

Example request:

GET /v3/projects/%7B%7Bproject_id%7D%7D/versions/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>
Conte: application/json

Get Project Tags

GET https://api.cloudofthings.com/v3/projects/{{project_id}}/tags/

With your unique project_id, you can use this call to view all the tags in a project.

Example request:

GET /v3/projects/%7B%7Bproject_id%7D%7D/tags/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>
Conte: application/json

Get Project Users

GET https://api.cloudofthings.com/v3/projects/{{project_id}}/users/

With your unique project_id, use this call to view a list of all users with permissions to your project.

Example request:

GET /v3/projects/%7B%7Bproject_id%7D%7D/users/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>
Conte: application/json

Get Project Property

GET https://api.cloudofthings.com/v3/projects/{{project_id}}/properties/?name={{project_property_name}}&version={{project_property_version}}&signature={{project_property_md5}}

Get a project’s properties by name and version. Optimal network traffic is achieved by http ETag style signature (md5) field. The server will send a new version if the property checksum is different from the client’s checksum for that property; otherwise it will respond with 304 not modified. (multiple properties query example: ?name=config,layout&version=0&md5=xxx,yyy)

Example request:

GET /v3/projects/%7B%7Bproject_id%7D%7D/properties/?name={{project_property_name}}&version={{project_property_version}}&signature={{project_property_md5}} HTTP/1.1
Host: api.cloudofthings.com
X-API: {{project_api_key}}

Update Project Property

PATCH https://api.cloudofthings.com/v3/projects/{{project_id}}/properties/?name={{project_property_name}}&version={{project_property_version}}

Will update the last property version with a new patch.

Example request:

PATCH /v3/projects/%7B%7Bproject_id%7D%7D/properties/?name={{project_property_name}}&version={{project_property_version}} HTTP/1.1
Host: api.cloudofthings.com
X-API: {{project_api_key}}
Content-Type: application/json

{
  "image_url":"http://cloudofthings.com/api/db/image.jpg",
  "context_url":"http://cloudofthings.com/api/db/data.db"
}

Get Company Property

GET https://api.cloudofthings.com/v3/companies/<company_id>/properties/?name={{company_property_name}}&version={{company_property_version}}&signature={{company_property_md5}}

Retrieve a company property by name and version. Optimal network traffic is achieved by http ETag style signature (md5) field. The server will send a new version if the property checksum is different from the client’s checksum for that property, otherwise it will respond with 304 not modified. (multiple properties query example: ?name=config,layout&version=0&md5=xxx,yyy)

Example request:

GET /v3/companies/%3Ccompany_id%3E/properties/?name={{company_property_name}}&version={{company_property_version}}&signature={{company_property_md5}} HTTP/1.1
Host: api.cloudofthings.com
X-API: {{company_api_key}}

Update Company Property

PATCH https://api.cloudofthings.com/v3/companies/<company_id>/properties/?name={{company_property_name}}&version={{company_property_version}}

This call will update the latest property version.

Example request:

PATCH /v3/companies/%3Ccompany_id%3E/properties/?name={{company_property_name}}&version={{company_property_version}} HTTP/1.1
Host: api.cloudofthings.com
X-API: {{company_api_key}}
Content-Type: application/json

{
  "image_url":"http://cloudofthings.com/api/db/image.jpg",
  "context_url":"http://cloudofthings.com/api/db/data.db"
}

Software Management

Get Device Firmware Property

GET https://api.cloudofthings.com/v3/devices/<device_id>/properties/?name=firmwareversion

Get the firmware version property of the device. This is a virtual property created on the server side and marked by ‘id = virtual’

Example request:

GET /v3/devices/%3Cdevice_id%3E/properties/?name=firmwareversion HTTP/1.1
Host: api.cloudofthings.com
X-API: {{device_api_key}}

User Management

User Properties

manage user related content

Get User Properties

GET https://api.cloudofthings.com/v3/properties/

Get all user Properties.

Example request:

GET /v3/properties/ HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>
Content-Type: application/json

Update User Property

PATCH https://api.cloudofthings.com/v3/properties/?name={{property_name}}&version={{property_version}}

Use this to update the last property version to the most recent.

Example request:

PATCH /v3/properties/?name={{property_name}}&version={{property_version}} HTTP/1.1
Host: api.cloudofthings.com
X-API: <user_api_key>

{"this is a test":"this is a test2"}