Server APIs

A trusted backend calls TiRTC server capabilities through the cloud tirtc-server-api. Every request must originate from a trusted backend that holds the application credentials. Do not call these APIs from a client application or device firmware.

Base URL:

https://api-tirtc.tange365.com

TGV1-HMAC-SHA256 authentication

Requests use TGV1-HMAC-SHA256. Follow the server API signing instructions to generate Authorization, X-Tg-Algorithm, X-Tg-Date, X-Tg-App-Id, X-Tg-Content-Sha256, and X-Tg-Signed-Headers. Keep SecretKeyId on the trusted backend; never send it in a request or store it in client or device code.

Header	Description
Authorization	TGV1 authorization line
X-Tg-Algorithm	Signing algorithm name
X-Tg-Date	UTC request time
X-Tg-App-Id	Application ID; must match the credential app_id
X-Tg-Content-Sha256	Lowercase hexadecimal SHA-256 of the request body; use an empty body for GET requests
X-Tg-Signed-Headers	Names of the headers included in the signature

API list

Capability	API	Purpose
Low-power sleep wakeup	GET /v1/device/connectivity	Query the current connection information of a device
Low-power sleep wakeup	POST /v1/device/wakeup-request	Submit a wakeup request to a device

Low-power sleep wakeup

These APIs complement the device-side low-power integration. Before submitting a wakeup request, the controller must obtain sleep parameters from the TiRTC SDK, and the low-power module must use them to log in to at least one sleep server and maintain heartbeats. See Low-Power Sleep Wakeup for the complete device flow.

A normal client connection triggers wakeup automatically. Submit a backend wakeup request only when an alarm, doorbell, or another business event needs to start the controller.

Query observed connectivity

This API queries the current connection information of a device, including the latest controller signaling and sleep-connection events observed by TiRTC. It does not directly determine whether the device is alive, has completed wakeup, or is in a particular business state.

Request

GET /v1/device/connectivity?device_id={device_id}

Parameter	Required	Description
device_id	Yes	TiRTC business device ID; 1–255 bytes of valid UTF-8; URL-encode it when passing it as a query parameter

Response

The API uses a common response envelope:

Field	Type	Description
code	number	Business status code; 0 means success and a non-zero value means a business error
message	string	Business status message
data	object	Device connectivity data on success; omit the field when there is no data

Both successful and failed business results use HTTP 200 OK. Check code in the response body instead of relying only on the HTTP status.

On success, data reports two independent device-side connection paths:

{
  "code": 0,
  "message": "ok",
  "data": {
    "device_id": "example-device-id",
    "signal": {
      "is_online": true,
      "last_login_at": 1787000000,
      "last_heartbeat_at": 1787000030,
      "last_offline_at": 1786999000
    },
    "sleep": {
      "last_login_at": 1786998000,
      "last_heartbeat_at": 1786998060,
      "last_offline_at": 1786999100
    }
  }
}

Object	Device-side meaning	Fields
signal	The signaling connection established while the controller is running the TiRTC SDK	is_online indicates whether the platform currently observes the controller connection as online; timestamps describe its latest login, heartbeat, and offline events
sleep	The TCP keepalive connection between the low-power module and a sleep server while the controller sleeps	Timestamps describe the latest sleep-connection events; this object does not currently include is_online

last_login_at, last_heartbeat_at, and last_offline_at are Unix-second timestamps, or null when no corresponding event has been observed. These objects observe separate connections and are not mutually exclusive device modes. Use a device-online notification or another business signal to determine final wakeup state.

Errors

Business errors also return HTTP 200 OK, for example:

{
  "code": 40003,
  "message": "invalid parameter"
}

code	Description
40003	Invalid parameter, such as a missing device_id, a length outside 1–255 bytes, or invalid UTF-8
40301	The application credential does not have permission
40302	The device does not match the application
40304	The device has expired
40403	The device does not exist
50000	An internal server error occurred
50301	The connectivity service is unavailable
50401	The query timed out

When the connectivity service is unavailable or the query times out, TiRTC returns the corresponding business error instead of interpreting missing data as the device being offline.

Submit a wakeup request

Use this API to submit a wakeup request to a device for a business event. The target device must already be logged in to a sleep server as described in the device integration flow.

Request

POST /v1/device/wakeup-request
Content-Type: application/json

The optional X-Request-ID header specifies a request identifier containing 1–128 printable ASCII characters. If omitted, the server generates one; if it is invalid, the server returns 40003 and generates a new request_id. The effective identifier is returned as the top-level request_id in the response body and matches the X-Tg-Request-Id response header.

{
  "device_id": "example-device-id",
  "custom_data": "0x1234"
}

Field	Required	Description
device_id	Yes	TiRTC business device ID; 1–255 bytes of valid UTF-8
custom_data	No	Two bytes of custom wakeup data; must be a string in the form 0x followed by four hexadecimal characters, for example 0x1234; a non-string value returns 40003 with the stable message custom_data must be a string; send it only when the target device can parse custom data

If the module can only match a fixed packet, omit custom_data so TiRTC sends 98 3b 16 f8 f3 9c 00 00. See Wakeup packet for device-side packet handling.

Response

The response uses a common structure. request_id, code, and message are top-level fields; on success the API returns data as defined and omits data when there is no data.

Field	Type	Description
code	number	Business status code; 0 means success and a non-zero value means a business error
message	string	Business status message
request_id	string	Effective request identifier; uses a valid X-Request-ID or a server-generated value when the header is omitted; matches the X-Tg-Request-Id response header
data	object	Wakeup request information on success; omit the field when there is no data

A successful submission returns HTTP 202 Accepted:

{
  "code": 0,
  "message": "ok",
  "request_id": "req-001",
  "data": {
    "device_id": "example-device-id",
    "status": "accepted",
    "accepted_at": "2026-08-23T10:00:00.126+08:00"
  }
}

This only means a sleep connection was found and the TCP write did not fail immediately. It does not prove delivery, controller startup, signal login, or final wakeup success.

Errors

Business errors use the same code, message, and request_id structure:

{
  "code": 40412,
  "message": "device not connected",
  "request_id": "req-001"
}

code	Description
40003	Invalid parameter, such as a missing field, an excessive length, an invalid format, or a non-string custom_data
40301	The application credential does not have permission
40302	The device does not match the application
40304	The device has expired
40403	The device does not exist
40412	The device is not connected
40902	The wakeup protocol is not supported
42901	Request overload
50000	An internal server error occurred
50204	Wakeup delivery failed
50301	The wakeup service is unavailable
50402	The delivery result is unknown

For 50402, do not assume whether the wakeup data was delivered. Correlate logs with request_id, use a device-online signal to determine the final result, and keep business actions idempotent when retrying.