Thingsee Open Services API specification

Authentication

[/auth]

Create client access token

[POST /auth/client-token]

Since 2020 Mid release
Creates a temporary access token for accessing other APIs
Token expires in 15 mins and can be recreated at any point
Supports multiple simultaneous tokens
Request
- Attributes (object)
  - client_id (string, required) – Client id
  - client_secret (string, required) – Client secret
- Headers
```
Content-Type: application/json
```

Body

{
  "client_id": "",
  "client_secret": ""
}

Response 200 (application/json)
- Attributes (object)
  - data (object)
    - token (string) – Access token used to access other APIs
- Body
```
{
    "data": {
        "token": "",
    }
}
```

Things

[/things]

Get all alerts

[GET /things/alerts]

Since 2020 Late release
Request
- Headers
```
Authorization: Bearer 
```
Response 200 (application/json)
- Attributes (object)
  - data (object, fixed-type)
    - alerting_tuids (array, fixed-type) – Array containing all tuids with active alerts
- Body
```
{
    "data": {
        "alerting_tuids": ["XXXX03X2Z74162459", "XXXX03X2Z74162947"]
    }
}
```

Get alert count

[GET /things/alerts/count]

Since 2020 Late release
Request
Headers
```
Authorization: Bearer 
```
Response 200 (application/json)
- Attributes (object)
  - data (object, fixed-type)
    - alert_count (string) – Amount of tuids with active alerts
- Body
```
{
    "data": {
        "alert_count": "207"
    }
}
```

Get alerts of a thing

[GET /things/{tuid}/alerts?from={from_timestamp}&to={to_timestamp}]

Since 2020 Late release
Includes alerts for both sensors and gateways
Parameters
- tuid (string, required) – Thing’s tuid
- from (number, optional) – Unix timestamp from when to fetch the messages
- to (number, optional) – Unix timestamp to when to fetch the messages
Request
Headers
```
Authorization: Bearer 
```

Response 200 (application/json)

Attributes (object)
- data (array, fixed-type)
  - (object)
    - tuid (string) – Thing’s tuid
    - alert_type (string) – Alert type
    - alerts (array, fixed-type)
      - (object)
        
        from (string) – Timestamp when the alert started
        
        to (string) – Timestamp when the alert ended

Body

{
    "data": [
        {
            "tuid": "XXXX04X1N73261481",
            "alert_type": "gateway connection lost",
            "alerts": [
                {
                    "from": "2019-12-03T07:22:19",
                    "to": "2019-12-03T07:32:19"
                }
            ]
        },
        {
            "tuid": "XXXX04X1N73261481",
            "alert_type": "heartbeat missed",
            "alerts": [
                {
                    "from": "1970-01-01T00:00:00",
                    "to": "2019-11-22T06:12:33"
                }
            ]
        }
    ]
}

Get general information of a thing

[GET /things/{tuid}]

Since 2020 Late release
Fetches general information of a thing
Parameters
- tuid (string, required) – Thing’s tuid
Request
- Headers
```
Authorization: Bearer 
```
Response 200 (application/json)
- Attributes (object)
  - data (object)
    - battery_level (number) – Battery level
    - timestamp (number) – Unix timestamp of last event
    - location (object)
      - lat (string) – Latitude
      - lon (string) – Longitude
    - gateway_tuid – Gateway tuid
    - version (string) – Software version
- Body
```
{
    "data": {
        "battery_level": 86,
        "timestamp": 1586952604,
        "location": {
            "lat": 65.01,
            "lon": 25.52
        },
        "gateway_tuid": "XXXX00X1O73360355",
        "version": "2019.11.15.2_ts_pod3wp34"
    }
}
```

Get messages of a thing

[GET /things/{tuid}/messages?messageid={messageid}&eventid={eventid}&from={from}&to={to}&limit={limit}]

Since 2020 Late release
Fetches messages of a thing
Parameters
- tuid (string, required) – Thing’s tuid
- messageid (string, optional) – Only returns messages that have message id in this list of
- comma-separated message id
- eventid (string, optional) – Only returns messages that have event id in this list of comma-separated event id
- from (number, optional) – Unix timestamp from when to fetch the messages
- to (number, optional) – Unix timestamp to when to fetch the messages
- limit (number, required) – Number of messages to return
Request
- Headers
```
Authorization: Bearer 
```
Response 200 (application/json)
- Attributes (object)
  - data (array, fixed-type)
    - (object)
      - tsmId (number) – Message identifier
      - tsmEv (number) – identifier
      - tsmTs (number) – Unix timestamp when the message was sent
      - tsmTuid (string) – Thing’s tuid
      - tsmGw (string) – Gateway’s tuid
      - deploymentGroupId (string) – Deployment group id which the thing belongs to
      - {variable} – Other dynamic attributes depending on the message identifier
- Body
```
{
    "data": [
        {
            "tsmId": 1110,
            "tsmEv": 10,
            "tsmTs": 1559638241,
            "tsmTuid": "XXXXTUID",
            "tsmGw": "XXXXGATEWAYTUID",
            "deploymentGroupId": "foo",
            "batl": 74,
        }
    ]
}
```

Get all commands sent to a thing

[GET /things/{tuid}/commands?messageid={messageid}&eventid={eventid}&from={from}&to={to}&limit={limit}]

Since 2020 Mid release
Fetches a list of all commands sent to a thing in chronological order
Response contains only commands with allowed message ids (1500, 1501, 12200, 13200)
Parameters
- tuid (string, required) – Thing’s tuid
- messageid (string, optional) – Only returns messages that have message id (tsmId) in this list of comma-separated message id
- eventid (string, optional) – Only returns messages that have event id (tsmEv) in this list of comma-separated event id
- from (number, optional) – Unix timestamp from when to fetch the messages
- to (number, optional) – Unix timestamp to when to fetch the messages
- limit (number, optional) – Number of messages to return
Request
- Headers
```
Authorization: Bearer 
```
Response 200 (application/json)
- Attributes (object)
  - data (array, fixed-type)
    - (object)
      - tuid (string) – Thing’s tuid
      - timestamp (number) – Unix timestamp when the command was sent
      - responsible (string) – Identity of the responsible who sent the commands
      - command (object) – Command info
        
        tsmId (number) – Message identifier
        
        tsmEv (number) – Event identifier
        
        tsmTs (number) – Unix timestamp when the command was sent
        
        tsmDstTuid (string) – Tuid of the thing where the command was sent
        
        {variable} – Other dynamic attributes depending on the message identifier
- Body
```
{
    "data": [
        {
            "tuid": "XXXXTUID",
            "timestamp": 1557302186,
            "responsible": ,
            "command": {
                "tsmEv": 30,
                "tsmId": 17110,
                "tsmTs": 1557302186,
                "tsmDstTuid": "XXXXTUID",
                "profileId": 0,
                "transactionId": 99999
            }
        }
    ]
}
```

Send a command to a thing

[POST /things/{tuid}/commands]

Since 2020 Mid release
Send commands to a thing
Allowed message ids are 1500, 1501, 12200, 13200
Parameters
- tuid (string, required) – Thing’s tuid
Request
- Headers
```
Authorization: Bearer 
Content-Type: application/json
```
- Attributes (array, fixed-type)
  - (object)
    - tsmId (number, required) – Message identifier
    - tsmEv (number, required) – Event id
    - {variable} – Other dynamic attributes depending on the message identifier
- Body
```
[
    {
        "tsmId": 17110,
        "tsmEv": 30,
        "transactionId": 99999,
        "profileId": 0
    }
]
```
Response 200 (application/json)
- Attributes (object)
  - data (object)
    - responsible (string) – Identity of the responsible who sent the commands
    - commands (array, fixed-type) – List of commands that have been made through this request
      - (object)
        
        tsmId (number) – Message identifier
        
        tsmEv (number) – Event id
        
        tsmTs (number) – Unix timestamp when the command is sent
        
        tsmDstTuid (string) – Tuid of the thing where the command is sent
        
        {variable} – Other dynamic attributes depending on the message identifier
- Body
```
{
    "data": {
        "responsible": ,
        "commands": [
            {
                "tsmEv": 30,
                "tsmId": 17110,
                "tsmTs": 1557302186,
                "tsmDstTuid": "XXXXTUID",
                "profileId": 0,
                "transactionId": 99999
            }
        ]
    }
}
```

Get installation history for a thing

[GET /things/{tuid}/installations?limit={limit}]

Since 2020 Mid release
Fetches installation history for a thing
Available installation statuses:
- new – New thing from the factory
- installed – Thing has been installed and warranty period for the thing is applied
- uninstalled – Thing has been uninstalled and waits for a possible reinstallation
- quarantine – Thing is waiting for a maintenance
- retired – Thing has been removed from the system (eg. thing is broken)
Parameters
- tuid (string, required) – Thing’s tuid -limit (number, optional) – Number of installation histories to return
Request
- Headers
```
Authorization: Bearer 
```
Response 200 (application/json)
- Attributes (object)
  - data (array, fixed-type)
    - (object)
      - tuid (string) – Thing’s tuid
      - installation_status (string) – Thing’s status
      - timestamp (number) – Unix timestamp when the status is set
      - responsible (string) – Identity of the responsible who made the change
- Body
```
{
    "data": [
        {
            "tuid": "XXXXTUID",
            "installation_status": "retired",
            "timestamp": 1559564455,
            "responsible": 
        }
    ]
}
```

Set installation status for a thing

[POST /things/{tuid}/installations]

Since 2020 Mid release
Available installation statuses:
- new – New thing from the factory
- installed – Thing has been installed and warranty period for the thing is applied
- uninstalled – Thing has been uninstalled and waits for a possible reinstallation
- quarantine – Thing is waiting for a maintenance
- retired – Thing has been removed from the system (eg. thing is broken)
Parameters
tuid (string, required) – Thing’s tuid
Request
- Headers
```
Authorization: Bearer 
Content-Type: application/json
```
- Attributes (object)
  - installation_status (string, required) – Thing’s installation status.
- Body
```
{
    "installation_status": "installed"
}
```
Response 200 (application/json)
- Attributes (object)
  - data (object)
    - tuid (string) – Thing’s tuid
    - installation_status (string) – Thing’s current status after being updated
- Body
```
{
    "data": {
        "tuid": "XXXXXXTUID",
        "installation_status": "installed"
    }
}
```

Get deployment group of a thing

[GET /things/{tuid}/group]

Since 2020 Mid release
Fetches deployment group of a thing
Parameters
- tuid (string, required) – Thing’s tuid
Request
- Headers
```
Authorization: Bearer 
```
Response 200 (application/json)
- Attributes (object)
  - data (object, fixed-type)
    - group_id (string, required) – Thing’s deployment group.
    - tuid (string) – Thing’s tuid
- Body
```
{
    "data": {
        "group_id": "testgroup1",
        "tuid": "XXXXTUID"
    }
}
```

Set deployment group of a thing

[POST /things/{tuid}/group]

Since 2020 Mid release
Sets deployment group of a thing
Parameters
- tuid (string, required) – Thing’s tuid
Request
- Headers
```
Authorization: Bearer 
Content-Type: application/json
```
- Attributes (object)
  - group_id (string, required) – Thing’s deployment group.
- Body
```
{
    "group_id": "testgroup1"
}
```
Response 200 (application/json)
- Attributes (object)
  - data (object, fixed-type)
    - group_id (string, required) – Thing’s deployment group.
    - tuid (string) – Thing’s tuid
- Body
```
{
    "data": {
        "group_id": "testgroup",
        "tuid": "XXXXTUID"
    }
}
```

Deployment Groups

[/groups]

Create a group

[POST /groups]

Since 2020 Mid release
Request
- Headers
```
Authorization: Bearer 
Content-Type: application/json
```
- Attributes (object)
  - group_id (string, required) – Group id. Note that group id must not contain whitespaces and must not be named "unassigned"
  - group_description (string, optional) – Group description
- Body
```
{
    "group_id": "testgroup1",
    "group_description": "This is a test group"
}
```
Response 200 (application/json)
- Attributes (object)
  - data (object)
    - group_id (string) – Group id (group name)
    - group_description (string) – Group description
- Body
```
{
    "data": {
        "group_id": "testgroup1",
        "group_description": "This is a test group"
    }
}
```

Rename a group

[POST /groups/{groupid}/rename]

Since 2020 Mid release
Parameters
- groupid (string, required) – Existing group id to be renamed
Request
- Headers
```
Authorization: Bearer 
Content-Type: application/json
```
- Attributes (object)
  - group_id (string, required) – New group id. Note that group id must not contain whitespaces and must not be named "unassigned"
- Body
```
{
    "group_id": "newgroupname"
}
```
Response 200 (application/json)
- Attributes (object)
  - data (object)
    - group_id (string) – Group id (group name)
    - old (string) – Old group id
    - renamed (boolean) – Whether the group was renamed successfully or not
- Body
```
{
    "data": {
        "group_id": "newgroupname",
        "old": "oldgroupname",
        "renamed": true
    }
}
```

Get groups

[GET /groups/?[q={searchtext}][&limit={limit}]]

Get things from a group

[GET /groups/{groupid}/things]

Delete a group

[DELETE /groups/{groupid}]

Since 2020 Mid release
Parameters
- groupid (string, required) – Group id to be deleted
Request
- Headers
```
Authorization: Bearer 
```
Response 200 (application/json)
- Attributes (object)
  - data (object)
    - group_id (string) – Group id (group name)
    - deleted (boolean) – Whether the group was deleted successfully or not
- Body
```
{
    "data": {
        "group_id": "deletedgroup",
        "deleted": true
    }
}
```

Cookie	Duration	Description
DEVICE_INFO	5 months 27 days	No description
manualDocSingleID	past	No description
manualFaqSingleID	past	No description

Cookie	Duration	Description
VISITOR_INFO1_LIVE	5 months 27 days	A cookie set by YouTube to measure bandwidth that determines whether the user gets the new or old player interface.
YSC	session	YSC cookie is set by Youtube and is used to track the views of embedded videos on Youtube pages.
yt-remote-connected-devices	never	YouTube sets this cookie to store the video preferences of the user using embedded YouTube video.
yt-remote-device-id	never	YouTube sets this cookie to store the video preferences of the user using embedded YouTube video.

Cookie	Duration	Description
_ga	2 years	The _ga cookie, installed by Google Analytics, calculates visitor, session and campaign data and also keeps track of site usage for the site's analytics report. The cookie stores information anonymously and assigns a randomly generated number to recognize unique visitors.
_ga_JXQRHKETY0	2 years	This cookie is installed by Google Analytics.
CONSENT	2 years	YouTube sets this cookie via embedded youtube-videos and registers anonymous statistical data.

API