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
          }
      }

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
          }
      }