Skip to content

The Thingsquare REST API Reference

Session methods

Every API invocation is done on a specific session. The session is identified by a session cookie created by the server and sent by the client along every subsequent request. The session methods creates and destroys a session.

Note: some curl examples use the -b parameter and some the -c parameter. The difference between them is that the -b parameter tells curl to read cookies from a file whereas the -c parameter tells curl to write cookies to a file. The methods where the server supplies a new session cookie use the c parameter for their examples and the methods where the server expects a session cookie use the -b parameter.

POST /0/session/: create anonymous session

Description

Create a new anonymous user session. A new session cookie will be returned for the new session. This session cookie is to be used for further requests during the session.

Parameters

None

Return values

  • 200 user-ok: a session already existed
  • 201 user-ok: a new session was created

Example usage

$ curl -c sessioncookie.txt -X POST https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/
user-ok

POST /0/session/login: create login session

Description

Create a user session with for a user. A new session cookie will be returned for the new session. This session cookie is to be used for further requests during the session.

Parameters

  • login: the login name
  • password: the password, in cleartext

Return values

  • 201 login-ok: authentication succeeded and the user was successfully logged in
  • 403 login-fail: authentication failed

Example usage

$ curl -c sessioncookie.txt -X POST --data login=dummy@example.com --data password=secret https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/login
login-fail

POST /0/session/logout: logout from session

Description

Logs out of the current session. The session cookie will no longer be possible to use for future requests.

Parameters

None.

Return values

  • 201 logout-ok: the session was successfully logged out
  • 400 logout-fail: there was no session registered with the session cookie

Example usage

$ curl -b sessioncookie.txt -X POST https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/logout
logout-ok

POST /0/session/signup: sign up new user

Description

Creates a new user and sends out a confirmation email. If no session was registered, a new session is created.

Parameters

  • login: the login name
  • password: the password, in cleartext

Return values

  • 201 signup-ok: the user was successfully signed up
  • 400 signup-fail-no-email: user user name was not a valid email address
  • 400 signup-fail-already-exists: user user name already exists

Example usage

$ curl -b sessioncookie.txt -X POST --data login=badloginname --data password=secret https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/signup
signup-fail-no-email

POST /0/session/resend: resend confirmation email

Description

Send a new confirmation email to the user.

Parameters

  • login: the login name

Return values

  • 200 resend-ok: a new confirmation email was successfully sent
  • 400 resend-fail: a new confirmation email could not be sent

Example usage

$ curl -b sessioncookie.txt -X POST --data login=badloginname https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/resend
resend-fail

POST /0/session/recovery: send password recovery email

Description

Send an email with a password recovery link to the user.

Parameters

  • login: the login name

Return values

  • 200 recover-ok: a password recovery email was successfully sent
  • 400 recover-fail: a password recovery email could not be sent

Example usage

$ curl -b sessioncookie.txt -X POST --data login=badloginname https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/recover
recover-fail

User data methods

The user data methods are used for storing and retrieving JSON data associated with the user.

GET /0/user/: get user data

Description

Retrieve the user's JSON data object. The user's data object contains four fields:

  • login (string): the login name of the user
  • confirmed (boolean): a boolean value indicating if the user is confirmed
  • authcode (string): a unique code that is used to identify the user with devices in the network. May change over time
  • data (object): an opaque JSON data structure that can hold arbitrary data

Parameters

None

Return values

  • 200 + user data: the user data in JSON format
  • 404 not found: no user session was found

Example usage

$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/
{"login":"","confirmed":false,"authcode":"cbcca1229ef0b9d588a1b148090fa67d","data":{}}

POST /0/user/: store user data

Description

Store data in the user's data field.

The data supplied in the data parameter will be merged with the user's data. This makes it possible to store only a subset of the data.

Parameters

  • field name: a string with the user's data.

Return values

  • 200 user-data-ok: the data was successfully stored
  • 413 user-data-failed: the data was too large

Example usage

$ curl -b sessioncookie.txt -X POST --data test=data https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/
user-data-ok

$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/
{"login":"","confirmed":false,"authcode":"cbcca1229ef0b9d588a1b148090fa67d","data":{"test":"data"}}

$ curl -b sessioncookie.txt -X POST --data another=test https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/
user-data-ok

$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/
{"login":"","confirmed":false,"authcode":"cbcca1229ef0b9d588a1b148090fa67d","data":{"test":"data","another":"test"}}

Device methods

The device methods are used to retrieve device data, store device data, and register devices for remote access.

GET /0/devices/: get all remote access devices

Description

Get information about all devices registered for remote access.

Parameters

None

Return values

  • 200 + device data: a JSON object of all device data, hashed by the device ID

Example usage

$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/
{"b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56":{"d":{"network-id":{"value":"8d6f953b730f4e4e","time":1468494129774,"acked":1468494129774,"syncacked":1468876125944,"synced":1468876109029},"mode":{"value":"deadleaf","time":1467199258562,"acked":1467199259016,"synced":1468876109029,"syncacked":1468876126171}},"s":{"platform":{"value":"thsq-sensortag","time":1468876126172}, <...>}}

GET /0/devices/<id>: get one device

Description

Get information about one specific device that has been registered for remote access or is nearby.

Parameters

  • <id>: the device ID for a remote access device, or the nearby ID for a nearby device

Return values

  • 200 + device data: a JSON object with the device data

Example usage

$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56
{"d":{"network-id":{"value":"8d6f953b730f4e4e","time":1468494129774,"acked":1468494129774,"syncacked":1468876125944,"synced":1468876109029},"mode":{"value":"deadleaf","time":1467199258562,"acked":1467199259016,"synced":1468876109029,"syncacked":1468876126171}},"s":{"platform":{"value":"thsq-sensortag","time":1468876126172}, <...>}

GET /0/devices/<id>/<type>/<name>: get one variable

Description

Get one specific variable for a device

Parameters

  • <id>: the device ID for a remote access device, or the nearby ID for a nearby device
  • <type>: the variable type, either d, s, or meta
  • <name>: the variable name

Return values

  • 200 + variable data: a JSON object with the variable data

Example usage

$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/s/platform
{"value":"thsq-sensortag","time":1468876126172}

GET /0/devices/<id>/<type>/<name>?latest=<latest>: get variable history

Description

Get data history for a specific variable

Parameters

  • <id>: the device ID for a remote access device, or the nearby ID for a nearby device
  • <type>: the variable type, either d, s, or meta
  • <name>: the variable name
  • <latest>: the number of data points to be retrieved

Return values

  • 200 + variable data: a JSON array with historical values for the variable

Example usage

$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/s/platform\?latest=2
[{"key":"platform","value":"thsq-sensortag","by":"device","type":"s","timestamp":1468876126172,"id":54968717},{"key":"platform","value":"thsq-sensortag","by":"device","type":"s","timestamp":1468852593002,"id":54800348}]

GET /0/devices/<id>/<type>/<name>?latest=<latest>: get variable history

Description

Get data history for a specific variable

Parameters

  • <id>: the device ID for a remote access device, or the nearby ID for a nearby device
  • <type>: the variable type, either d, s, or meta
  • <name>: the variable name
  • <latest>: the number of data points to be retrieved

Return values

  • 200 + variable data: a JSON array with historical values for the variable

Example usage

$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/s/platform\?latest=2
[{"key":"platform","value":"thsq-sensortag","by":"device","type":"s","timestamp":1468876126172,"id":54968717},{"key":"platform","value":"thsq-sensortag","by":"device","type":"s","timestamp":1468852593002,"id":54800348}]

POST /0/devices/: register device for remote access

Description

Claim a device for remote access. The authentication token can be received either via a Bluetooth beacon (or other proximity communication) or from a network device.

Parameters

  • auth: the device authentication token

Return values

  • 201 + <device ID>: the device was successfully registered for remote access, <device ID> is the device's new access ID
  • 400 claim-fail: could not register device for remote access

Example usage

$ curl -b sessioncookie.txt -X POST --data auth=123456789abcdef https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/
claim-fail

DELETE /0/devices/<id>: remove a device from remote access

Description

Remove remote access for a device.

Parameters

None.

Return values

  • 200 device-ok: remote access for the device was successfully removed
  • 400 device-fail: the device could not be found

Example usage

$ curl -b sessioncookie.txt -X DELETE --data value=120 https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56
device-ok

POST /0/devices/<id>/<type>/<name>: set a device variable

Description

Set a device variable. The <type> can be s or d. If <type> is d, variable data will be sent to the device.

The variable value can be set either as a string (with the value parameter) or as a base64-encoded string (with the value64 parameter) to make it easier to set binary data values.

If <type> is d and no value is given, the device will be synchronized with the current value of the variable named <name>.

If a d variable is set and the device is currently available, the new value of the variable will be pushed to the device, but this method will return to the caller before the value has reached the device. The caller should use the GET /0/devices/<id>/d/<name>/ method to query for the successful acknowledgment of the variable to ensure that the variable has reached the device.

Parameters

  • value: the variable value
  • value64 (optional): a base64-encoded value

Return values

  • 200 device-ok: the variable was successfully set
  • 400 device-fail: the variable could not be set

Example usage

$ curl -b sessioncookie.txt -X POST --data value=120 https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/d/period
device-ok

DELETE /0/devices/<id>/<type>/<name>: delete a device variable

Description

Delete a device variable.

If the variable is a d variable, the deletion will be synchronized with the device.

Parameters

None.

Return values

  • 200 device-ok: the variable was successfully deleted
  • 400 device-fail: the variable could not be deleted

Example usage

$ curl -b sessioncookie.txt -X DELETE --data value=120 https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/d/period
device-ok

POST /0/devices/<id>/: send device command

Description

Send a the device command to a device.

Parameters

  • command: the command to be sent, if the command is an ASCII string
  • command64 (optional): the base64 encoded version of the command string, if the command contains binary characters
  • priority (optional): the priority of the command (0: default urgency, 1: urgent, 2: most urgent)
  • lifetime (optional): the time, in milliseconds, that the command should be on the command queue before being removed

Return values

  • 200 <command uuid>: command transmission of command with command uuid started

Example usage

$ curl -b sessioncookie.txt -X POST --data command=idfy https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/
043e6ba0-8cee-4519-b061-c3a263b7be18

Network methods

The network methods is used to query the network that the user currently is in. To announce the presence of a user, the user's client must broadcast the user's authcode in repeated UDP messages on port 590. These messages are picked up by nearby access points and the backend can then match the devices that are in the same network as the user.

GET /0/network/: get all available devices in the network

Description

The all device information for devices in the same network as the user.

Parameters

None

Return values

  • 200 + JSON string: a JSON object with all devices in the network, hashed by the devices' auth codes.

Example usage

$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/network/
{"fd92477f326aaa4de8b2d85122560591":{"d":{"period":{"value":"60","time":1464883503962,"acked":1464883503962,"syncacked":1468930674962,"synced":1468930674841},"mode":{"value":"master","time":1468930675543,"acked":1468930675543},"network-id":{"value":"8d6f953b730f4e4e","time":1468930675543,"acked":1468930675691},<...>}

Over-the-air firmware update methods

The firmware update methods are used to query the system for available firmware images and for starting and stopping a remote firmware update for a device.

GET /0/firmware/: obtain available firmware images

Description

Retrieve the list of available firmware images.

Parameters

None

Return values

  • 200 + JSON string: a JSON array with all available firmware images

Example usage

$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/firmware/
[{"name":"20160718/cc2538dk/client.signed","platform":"thsq-cc2538dk-bootloader","version":1468838806,"info":{"platforms":{"from":["thsq-cc2538dk"],"to":{"platform":"thsq-cc2538dk","name":"TI CC2538dk"}}}}, <...>]

POST /0/devices/<id>/fw/<name>: start a firmware update

Description

Start a firmware update for the device with ID <id>.

The device must be in the connected state for the firmware update to commence. To set the device to the connected state, the d variable mode must be set to connected. Once the device has connected to the backend, the meta variable state will become connected. It is the responsibility of the caller to ensure that these conditions are met before calling this method.

Parameters

None

Return values

  • 200 device-ok: device firmware update was started
  • 400 device-fwup-name-fail: firmware name could not be found
  • 400 device-fwup-start-fail: device firmware update could not be started

Example usage

$ curl -b sessioncookie.txt -X POST https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/fw/20160718/sensortag/client.signed
device-ok

DELETE /0/devices/<id>/fw: cancel an ongoing a firmware update

Description

Cancel an ongoing firmware update for a device.

Parameters

None

Return values

  • `200 firmware-ok': device firmware update was canceled
  • 400 firmware-fail: device firmware update could not be canceled

Example usage

$ curl -b sessioncookie.txt -X DELETE https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/fw
device-ok