REST API

ThingsBoard provides a REST API for managing platform entities, integrations, device provisioning, and building custom applications. The API is available on every ThingsBoard instance and documented interactively via Swagger UI.

All examples on this page use $TB_URL for the ThingsBoard base URL (e.g. https://thingsboard.cloud) and $AUTH for the authorization header value (e.g. ApiKey YOUR_KEY).

Swagger UI lets you browse all available REST API endpoints, inspect request and response schemas, and test API calls directly in your browser.

Access it at:

http://localhost:8080/swagger-ui.html

If you are already logged into the ThingsBoard UI, Swagger UI authenticates automatically using your session.

Pass the API key in the X-Authorization header:

X-Authorization: ApiKey YOUR_API_KEY_VALUE

Example request:

curl -X GET -H 'X-Authorization: ApiKey YOUR_API_KEY_VALUE' \
  '$TB_URL/api/auth/user'

API keys are long-lived, require no login, and can be revoked through the ThingsBoard UI.

Obtain an access token by sending credentials to the login endpoint:

curl -X POST -H 'Content-Type: application/json' \
  -d '{"username":"[email protected]", "password":"tenant"}' \
  '$TB_URL/api/auth/login'

Response:

{"token":"YOUR_JWT_TOKEN", "refreshToken":"YOUR_JWT_REFRESH_TOKEN"}

Use the token in subsequent requests:

X-Authorization: Bearer YOUR_JWT_TOKEN

Access tokens are valid for 2.5 hours; refresh tokens for 1 week.

ThingsBoard provides language-specific client libraries that simplify REST API usage:

• Java REST Client — manage entities from Java applications
• Python REST Client — manage entities from Python scripts

Most API calls require an entity ID (UUID). You can find it in the ThingsBoard UI (it appears in the URL when you open an entity), or fetch it via REST.

List devices — returns paginated devices with their IDs:

curl -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/tenant/devices?pageSize=10&page=0'

Response (abbreviated):

{
  "data": [
    {
      "id": {"entityType": "DEVICE", "id": "784f394c-42b6-435a-983c-b7beff2784f9"},
      "name": "Thermostat A1",
      "type": "thermostat"
    }
  ],
  "totalElements": 3
}

Use the id value (784f394c-...) in the {deviceId} placeholder in all subsequent examples. The same pattern applies to other entity types — use /api/tenant/assets, /api/customers, etc.

The Attributes API lets you create, read, and delete attributes on any entity. Attributes are organized into scopes:

Create or update attributes in a given scope. The request body is a JSON object with key-value pairs.

curl -X POST -H 'Content-Type: application/json' \
  -H 'X-Authorization: $AUTH' \
  -d '{"firmware":"1.2.3", "batchSize":100}' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/attributes/SERVER_SCOPE'

Works for any entity type — replace DEVICE/{deviceId} with ASSET/{assetId}, etc.

All scopes — returns attributes from every scope merged together:

curl -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/values/attributes'

Specific scope with optional key filter:

curl -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/values/attributes/SERVER_SCOPE?keys=firmware,batchSize'

Response:

[
  {"lastUpdateTs": 1709912345000, "key": "firmware", "value": "1.2.3"},
  {"lastUpdateTs": 1709912345000, "key": "batchSize", "value": 100}
]

# All scopes
curl -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/keys/attributes'

# Specific scope
curl -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/keys/attributes/SERVER_SCOPE'

Response: ["firmware", "batchSize"]

curl -X DELETE -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/SERVER_SCOPE?keys=firmware,batchSize'

The Time Series API lets you save, query, and delete time series data for any entity.

Simple format — the server assigns the current timestamp:

curl -X POST -H 'Content-Type: application/json' \
  -H 'X-Authorization: $AUTH' \
  -d '{"temperature": 22.5, "humidity": 58}' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/timeseries/ANY'

With explicit timestamp (milliseconds since epoch):

curl -X POST -H 'Content-Type: application/json' \
  -H 'X-Authorization: $AUTH' \
  -d '{"ts": 1709912345000, "values": {"temperature": 22.5, "humidity": 58}}' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/timeseries/ANY'

Multiple data points with different timestamps:

curl -X POST -H 'Content-Type: application/json' \
  -H 'X-Authorization: $AUTH' \
  -d '[
    {"ts": 1709912340000, "values": {"temperature": 22.3}},
    {"ts": 1709912345000, "values": {"temperature": 22.5}}
  ]' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/timeseries/ANY'

With TTL — data expires after the specified number of seconds:

curl -X POST -H 'Content-Type: application/json' \
  -H 'X-Authorization: $AUTH' \
  -d '{"temperature": 22.5}' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/timeseries/ANY/86400'

Returns the most recent value for each requested key:

curl -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries?keys=temperature,humidity'

Response:

{
  "temperature": [{"ts": 1709912345000, "value": "22.5"}],
  "humidity": [{"ts": 1709912345000, "value": "58"}]
}

Returns historical data points within a time window. Supports aggregation.

curl -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries?keys=temperature&startTs=1709900000000&endTs=1709999999999&limit=100&agg=NONE&orderBy=ASC'

Parameters:

Aggregated example — hourly averages:

curl -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries?keys=temperature&startTs=1709900000000&endTs=1709999999999&agg=AVG&interval=3600000'

curl -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/keys/timeseries'

Response: ["temperature", "humidity", "speed"]

curl -X DELETE -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/plugins/telemetry/DEVICE/{deviceId}/timeseries/delete?keys=temperature&deleteAllDataForKeys=true'

Parameters:

The RPC API lets server-side applications send commands to devices. The device must be online (or persistent RPC must be used).

Sends a command without waiting for a response from the device:

curl -X POST -H 'Content-Type: application/json' \
  -H 'X-Authorization: $AUTH' \
  -d '{"method": "setGpio", "params": {"pin": 4, "value": 1}}' \
  '$TB_URL/api/rpc/oneway/{deviceId}'

Returns HTTP 200 with empty body on success.

Sends a command and waits for the device to respond:

curl -X POST -H 'Content-Type: application/json' \
  -H 'X-Authorization: $AUTH' \
  -d '{"method": "getState", "params": {}}' \
  '$TB_URL/api/rpc/twoway/{deviceId}'

Returns the device response as JSON. If the device does not respond within the timeout, returns HTTP 504.

Request body:

When "persistent": true, the platform stores the RPC request and delivers it when the device comes online.

Query persistent RPCs for a device:

curl -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/rpc/persistent/device/{deviceId}?pageSize=10&page=0&rpcStatus=QUEUED&sortProperty=createdTime&sortOrder=ASC'

Get a specific RPC by ID:

curl -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/rpc/persistent/{rpcId}'

Delete a persistent RPC:

curl -X DELETE -H 'X-Authorization: $AUTH' \
  '$TB_URL/api/rpc/persistent/{rpcId}'

The table below lists all REST API controller groups available in Swagger UI. Each controller groups related endpoints.

• Entity Data Query API — advanced entity search with filters, used by entity-query-controller and WebSocket ENTITY_DATA
• Alarm Query API — alarm search with severity, status, and time filters, used by alarm-query-controller and WebSocket ALARM_DATA
• WebSocket API — real-time subscriptions for telemetry, alarms, and notifications
• APIs & SDKs — all available APIs and client libraries