Open Service API

RESTful API for Thingsee IoT device management and data access.

Thingsee Open Service APIs are included in both Thingsee Operations Cloud and Thingsee Operations Edge. With this API you can create your own device management dashboard, field service application, or integrate Thingsee device data into your existing asset management tools.

Base URL

Your base URL is allocated during deployment:

https://{apiId}.execute-api.{region}.amazonaws.com/prod/v1/

apiId - Identifier allocated by AWS API Gateway
region - AWS region where Thingsee is deployed

Authentication

Create Client Access Token

POST /auth/client-token

Creates a temporary access token (expires in 15 minutes). Supports multiple simultaneous tokens.

Request:

curl -X POST \
  "https://{api-url}/v1/auth/client-token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

Response:

{
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
}

Use the token in subsequent requests:

Authorization: Bearer {token}

Things (Devices)

Get General Information

GET /things/{tuid}

Fetch device information including battery level, location, and firmware version.

Response:

{
    "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

GET /things/{tuid}/messages

Fetch device messages with optional filters.

Query Parameters:

Parameter	Type	Description
`messageid`	String	Comma-separated message IDs
`eventid`	String	Comma-separated event IDs
`from`	Number	Unix timestamp (start)
`to`	Number	Unix timestamp (end)
`limit`	Number	Maximum results (required)

Example:

curl -X GET \
  "https://{api-url}/v1/things/XXXXTUID/messages?limit=10&messageid=1110" \
  -H "Authorization: Bearer {token}"

Response:

{
    "data": [
        {
            "tsmId": 1110,
            "tsmEv": 10,
            "tsmTs": 1559638241,
            "tsmTuid": "XXXXTUID",
            "tsmGw": "XXXXGATEWAYTUID",
            "deploymentGroupId": "foo",
            "batl": 74
        }
    ]
}

Send Command

POST /things/{tuid}/commands

Send configuration or command messages to a device. Allowed message IDs: 1500, 1501, 12200, 13200.

Request:

curl -X POST \
  "https://{api-url}/v1/things/XXXXTUID/commands" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '[{
    "tsmId": 1500,
    "tsmEv": 30,
    "transactionId": 99999,
    "measurementInterval": 60,
    "reportInterval": 300
  }]'

Response:

{
    "data": {
        "responsible": "api-user",
        "commands": [
            {
                "tsmEv": 30,
                "tsmId": 1500,
                "tsmTs": 1557302186,
                "tsmDstTuid": "XXXXTUID",
                "measurementInterval": 60,
                "reportInterval": 300,
                "transactionId": 99999
            }
        ]
    }
}

Get All Commands

GET /things/{tuid}/commands

Fetch command history for a device.

Get Alerts

GET /things/{tuid}/alerts

Fetch active and historical alerts.

Query Parameters:

Parameter	Type	Description
`from`	Number	Unix timestamp (start)
`to`	Number	Unix timestamp (end)

Response:

{
    "data": [
        {
            "tuid": "XXXX04X1N73261481",
            "alert_type": "gateway connection lost",
            "alerts": [
                {
                    "from": "2019-12-03T07:22:19",
                    "to": "2019-12-03T07:32:19"
                }
            ]
        }
    ]
}

Installation Management

Set Installation Status

POST /things/{tuid}/installations

Update device lifecycle status.

Status Values:

Status	Description
`new`	New from factory
`installed`	Deployed (warranty begins)
`uninstalled`	Removed, awaiting reinstallation
`quarantine`	Awaiting maintenance
`retired`	Removed from service

Request:

{
    "installation_status": "installed"
}

Get Installation History

GET /things/{tuid}/installations

Fetch installation status history.

Deployment Groups

Create Group

POST /groups

Create a new deployment group for organizing devices.

Request:

{
    "group_id": "northern-finland",
    "group_description": "Sensors in Northern Finland"
}

Note

Group IDs cannot contain whitespace or be named “unassigned”.

Get Groups

GET /groups

List all groups with optional search.

Query Parameters:

Parameter	Type	Description
`q`	String	Search text
`limit`	Number	Maximum results

Assign Device to Group

POST /things/{tuid}/group

Assign a device to a deployment group.

Request:

{
    "group_id": "northern-finland"
}

Get Group Devices

GET /groups/{groupid}/things

List all devices in a group.

Delete Group

DELETE /groups/{groupid}

Remove a deployment group.

Message Sequences

Typical Installation Flow

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#73F9C1','primaryTextColor':'#143633','primaryBorderColor':'#143633','lineColor':'#143633','secondaryColor':'#C7FDE6','tertiaryColor':'#F6FAFA','actorBkg':'#73F9C1','actorBorder':'#143633','noteBorderColor':'#FF8862','noteBkgColor':'#FFCFC0','signalColor':'#143633'}}}%%
sequenceDiagram
    participant App as Installation App
    participant API as Thingsee API
    participant Device as Thingsee Device
    
    App->>Device: Read QR code
    Device-->>App: Returns PSN, IMC
    App->>App: Create TUID = IMC + PSN
    App->>API: POST /things/{tuid}/installations
    API-->>App: 200 OK
    App->>API: POST /things/{tuid}/group
    API-->>App: 200 OK

Remote Configuration Flow

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#73F9C1','primaryTextColor':'#143633','primaryBorderColor':'#143633','lineColor':'#143633','secondaryColor':'#C7FDE6','tertiaryColor':'#F6FAFA','actorBkg':'#73F9C1','actorBorder':'#143633','noteBorderColor':'#FF8862','noteBkgColor':'#FFCFC0','signalColor':'#143633'}}}%%
sequenceDiagram
    participant Cloud as Your Cloud
    participant API as Thingsee API
    participant Data as Data Integration
    participant Device as Thingsee Device
    
    Cloud->>Cloud: Construct configuration JSON
    Cloud->>API: POST /things/{tuid}/commands
    API-->>Cloud: 200 OK
    API->>Device: Route configuration
    Device->>Device: Process message
    Device->>Data: Echo new config
    Data->>Cloud: Configuration response
    Cloud->>Cloud: Update inventory

The configuration response (“echo”) is delivered through your data integration (MQTT, Azure IoT Hub, etc.), not through the REST API response.