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

      Authorization: Bearer <token>
      Content-Type: application/json
      
    • Body

      {
          "client_id": "<client_id>",
          "client_secret": "<client_secret>"
      }
      
  • Response 200 (application/json)

    • Attributes (object)

      • data (object)
        • token (string) - Access token used to access other APIs
    • Body

      {
          "data": {
              "token": "<token>",
          }
      }
      

Things

[/things]

Get all alerts

[GET /things/alerts]

  • Since 2020 Late release
  • Request

    • Headers

      Authorization: Bearer <token>
      
  • 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 <token>
      
  • 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
  • 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 <token>
      
  • 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 <token>
      
  • 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 <accessToken>
      
  • 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 <token>
      
  • 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": <identity_id>,
                  "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 <token>
      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": <responsible_id>,
              "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 <token>
      
  • 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": <responsible_id>
              }
          ]
      }
      

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 <token>
      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 <token>
      
  • 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 <token>
      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 <token>
      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 <token>
      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 <token>
      
  • 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
          }
      }
      
Previous