Docs

Appearance

Open console

Reference

Devices

REST API reference for Devices: create and configure devices, call their resources, and manage their tokens, properties, callbacks and files. 45 operations.

Reference22 min read

For the base URL, authentication and errors, see the REST API overview.

GET /v1/users/{user}/devices ​

  • Request: GET /v1/users/{user}/devices
  • Operation: ListDevices
  • Operation ID: Device_List
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/devices' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200)

json
[
  {
    "asset_group": "AssetGroup",
    "asset_type": "AssetType",
    "created": 1792263090700,
    "description": "HTTP Device",
    "device": "http_device",
    "enabled": true,
    "modified": 1792263090700,
    "name": "SN0300301",
    "type": "HTTP"
  },
  {
    "asset_group": "AssetGroup",
    "asset_type": "AssetType",
    "created": 1792263090700,
    "description": "MQTT Device",
    "device": "mqtt_device",
    "enabled": true,
    "modified": 1792263090700,
    "name": "SN0300301",
    "type": "MQTT"
  },
  {
    "asset_group": "AssetGroup",
    "asset_type": "AssetType",
    "created": 1792263090700,
    "description": "Thinger Device",
    "device": "thinger_device",
    "enabled": true,
    "modified": 1792263090700,
    "name": "SN0300301",
    "type": "Generic"
  }
]

POST /v1/users/{user}/devices ​

  • Request: POST /v1/users/{user}/devices
  • Operation: CreateDevice
  • Operation ID: Device_Create
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Request body (application/json, required)

The body matches one of these 2 variants.

Variant 1

FieldTypeRequiredConstraintsDescription
asset_groupstringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
asset_typestringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
connectionobjectno
connection.timeoutsobjectno
connection.timeouts.disconnectintegernoMinimum: 60
connection.timeouts.sleepintegernoMinimum: 0
credentialsstringyesLength: 6 to 255
descriptionstringnoLength: 0 to 255
devicestringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
enabledbooleanno
labelsobjectnoKeys: ^[A-Za-z0-9_][A-Za-z0-9_-]{0,62}$
labels.*stringnoMaximum length: 255
namestringnoLength: 0 to 255
productstringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
typestringnoOne of: Generic, MQTT

Variant 2

FieldTypeRequiredConstraintsDescription
asset_groupstringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
asset_typestringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
descriptionstringnoLength: 1 to 255
devicestringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
enabledbooleanno
labelsobjectnoKeys: ^[A-Za-z0-9_][A-Za-z0-9_-]{0,62}$
labels.*stringnoMaximum length: 255
namestringnoLength: 0 to 255
parentstringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
productstringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
protocolstringnoLength: 1 to 50
typestringnoOne of: HTTP, Virtual, Subdevice

Example request: HTTP Device

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/devices' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "asset_group": "AssetGroup",
  "asset_type": "AssetType",
  "description": "HTTP Device",
  "device": "http_device",
  "enabled": true,
  "name": "SN0300301",
  "type": "HTTP"
}'

Example body: MQTT Device

json
{
  "asset_group": "AssetGroup",
  "asset_type": "AssetType",
  "credentials": "YOUR_TOKEN",
  "description": "MQTT Device",
  "device": "mqtt_device",
  "enabled": true,
  "name": "SN0300301",
  "type": "MQTT"
}

Example body: Thinger Device

json
{
  "asset_group": "AssetGroup",
  "asset_type": "AssetType",
  "credentials": "YOUR_TOKEN",
  "description": "Thinger Device",
  "device": "thinger_device",
  "enabled": true,
  "name": "SN0300301",
  "type": "Generic"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/devices/{device} ​

  • Request: GET /v1/users/{user}/devices/
  • Operation: ReadDeviceStatus
  • Operation ID: Device_ReadStatus
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PUT /v1/users/{user}/devices/{device} ​

  • Request: PUT /v1/users/{user}/devices/
  • Operation: UpdateDevice
  • Operation ID: Device_Update
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
asset_groupstringnoVariant 1: Pattern: ^[a-zA-Z0-9_-]{1,32}$
Variant 2: Maximum length: 0		A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
asset_typestringnoVariant 1: Pattern: ^[a-zA-Z0-9_-]{1,32}$
Variant 2: Maximum length: 0		A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
connectionobjectno
connection.timeoutintegernoMinimum: 1
connection.timeoutsobjectno
connection.timeouts.disconnectintegernoMinimum: 60
connection.timeouts.sleepintegernoMinimum: 0
credentialsstringnoLength: 1 to 255
descriptionstringnoLength: 0 to 255
enabledbooleanno
labelsobjectnoKeys: ^[A-Za-z0-9_][A-Za-z0-9_-]{0,62}$
labels.*stringnoMaximum length: 255
namestringnoLength: 0 to 255
productstringnoVariant 1: Pattern: ^[a-zA-Z0-9_-]{1,32}$
Variant 2: Maximum length: 0		A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Update Asset Group

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "asset_group": "Farm 1"
}'

Example body: Update Asset Type

json
{
  "asset_type": "Truck"
}

Example body: Update Credentials

json
{
  "credentials": "YOUR_TOKEN"
}

Example body: Update Description

json
{
  "description": "Updated Description"
}

Example body: Update Enabled

json
{
  "enabled": false
}

Example body: Update Labels

json
{
  "labels": {
    "region": "europe",
    "type": "small"
  }
}

Example body: Update Name

json
{
  "name": "SN0300301"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

DELETE /v1/users/{user}/devices/{device} ​

  • Request: DELETE /v1/users/{user}/devices/
  • Operation: DeleteDevice
  • Operation ID: Device_Delete
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/devices/{device}/clone ​

  • Request: GET /v1/users/{user}/devices/{device}/clone
  • Operation: CloneDeviceConfig
  • Operation ID: Device_CloneConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v1/users/{user}/devices/{device}/clone ​

  • Request: POST /v1/users/{user}/devices/{device}/clone
  • Operation: CloneDevice
  • Operation ID: Device_Clone
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
devicestringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
enabledbooleanno
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.

Example request: Copy with a new id

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "device": "copy_of_device"
}'

Example body: Copy with name and description

json
{
  "description": "Same configuration as the original, for production line 2",
  "device": "line_2_device",
  "name": "Line 2 copy"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PUT /v1/users/{user}/devices/{device}/projects ​

  • Request: PUT /v1/users/{user}/devices/{device}/projects
  • Operation: UpdateDeviceProjects
  • Operation ID: Device_UpdateProjects
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
(body)array of stringnoProjects the resource belongs to, as <owner>@<project> ids. Replaces the whole list: read the current one first to add or remove a single project; [] removes it from every project.

Example request: No projects

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE/projects' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[]'

Example body: One project

json
[
  "YOUR_USER@greenhouse"
]

Example body: Two projects

json
[
  "YOUR_USER@greenhouse",
  "YOUR_USER@maintenance"
]

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/devices/{device}/stats ​

Deprecated. The OpenAPI document marks this operation as deprecated.

  • Request: GET /v1/users/{user}/devices/{device}/stats
  • Operation: ReadDeviceStatistics
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE/stats' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/devices/{device}/tokens ​

  • Request: GET /v1/users/{user}/devices/{device}/tokens
  • Operation: ListDeviceTokens
  • Operation ID: Device_ListTokens
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE/tokens' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v1/users/{user}/devices/{device}/tokens ​

  • Request: POST /v1/users/{user}/devices/{device}/tokens
  • Operation: CreateDeviceToken
  • Operation ID: Device_CreateToken
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Request body (application/json, required)

A token limited to this device: it can only call the listed device resources (all of them when token_resources is missing). Useful to let a third party read or control one device.

FieldTypeRequiredConstraintsDescription
token_expirationnumbernoUnix timestamp when the token stops working.
token_namestringyes
token_resourcesarray of stringnoResource names the token can call.

Example request: All resources until a date

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE/tokens' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "token_expiration": 1798761600,
  "token_name": "Installer"
}'

Example body: Read two resources

json
{
  "token_name": "Display panel",
  "token_resources": [
    "temperature",
    "humidity"
  ]
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

DELETE /v1/users/{user}/devices/{device}/tokens/{token} ​

  • Request: DELETE /v1/users/{user}/devices/{device}/tokens/
  • Operation: DeleteDeviceToken
  • Operation ID: Device_DeleteToken
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
tokenpathstringyes

Example request

bash
curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE/tokens/YOUR_TOKEN' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/devices/{device}/{resource} ​

Deprecated. The OpenAPI document marks this operation as deprecated.

  • Request: GET /v1/users/{user}/devices/{device}/
  • Operation: AccessDeviceResources
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
resourcepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE/YOUR_RESOURCE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v1/users/{user}/devices/{device}/{resource} ​

Deprecated. The OpenAPI document marks this operation as deprecated.

  • Request: POST /v1/users/{user}/devices/{device}/
  • Operation: AccessDeviceResources
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
resourcepathstringyes

Request body (application/json, required)

A JSON object.

Example request (skeleton generated from the schema: required fields only, neutral values)

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/devices/YOUR_DEVICE/YOUR_RESOURCE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/info/devices/stats ​

  • Request: GET /v1/users/{user}/info/devices/stats
  • Operation: ReadDeviceStatistics
  • Operation ID: Device_ReadDevicesStatistics
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/info/devices/stats' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v2/users/{user}/devices/{device}/{resource} ​

Deprecated. The OpenAPI document marks this operation as deprecated.

  • Request: GET /v2/users/{user}/devices/{device}/
  • Operation: AccessDeviceResources
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
resourcepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v2/users/YOUR_USER/devices/YOUR_DEVICE/YOUR_RESOURCE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v2/users/{user}/devices/{device}/{resource} ​

Deprecated. The OpenAPI document marks this operation as deprecated.

  • Request: POST /v2/users/{user}/devices/{device}/
  • Operation: AccessDeviceResources
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
resourcepathstringyes

Request body (application/json, required)

A JSON object.

Example request (skeleton generated from the schema: required fields only, neutral values)

bash
curl -X POST 'https://YOUR_SERVER/v2/users/YOUR_USER/devices/YOUR_DEVICE/YOUR_RESOURCE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/buckets ​

  • Request: GET /v3/users/{user}/devices/{device}/buckets
  • Operation: ListDeviceBuckets
  • Operation ID: Device_ListBuckets
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/buckets' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/buckets/{bucket}/tags ​

  • Request: GET /v3/users/{user}/devices/{device}/buckets/{bucket}/tags
  • Operation: ListDeviceBucketTags
  • Operation ID: Device_ListBucketTags
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
bucketpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/buckets/YOUR_BUCKET/tags' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/buckets/{bucket}/tags/{tag} ​

  • Request: GET /v3/users/{user}/devices/{device}/buckets/{bucket}/tags/
  • Operation: ReadDeviceBucketTag
  • Operation ID: Device_ReadBucketTag
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
bucketpathstringyes
tagpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/buckets/YOUR_BUCKET/tags/YOUR_TAG' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/callback ​

  • Request: GET /v3/users/{user}/devices/{device}/callback
  • Operation: ReadDeviceCallbackConfig
  • Operation ID: Device_ReadCallbackConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/callback' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PUT /v3/users/{user}/devices/{device}/callback ​

  • Request: PUT /v3/users/{user}/devices/{device}/callback
  • Operation: UpdateDeviceCallback
  • Operation ID: Device_UpdateCallback
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Request body (application/json, required)

What the server does with the JSON an HTTP device posts to its callback (POST /v3/users/{user}/devices/{device}/callback/data): write_bucket stores it in a bucket, call_endpoint forwards it to an endpoint, set_property saves it as a device property, send_property returns a property as the response (e.g. its configuration). properties.timeout: minutes without data before the device is shown as disconnected.

FieldTypeRequiredConstraintsDescription
actionsobjectno
actions.call_endpointstringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
actions.send_propertystringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
actions.set_propertystringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
actions.write_bucketstringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
propertiesobjectno
properties.timeoutintegerno

Example request: Store the data in a bucket

bash
curl -X PUT 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/callback' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "actions": {
    "write_bucket": "meter_readings"
  },
  "properties": {
    "timeout": 10
  }
}'

Example body: Store, notify and reply with a property

json
{
  "actions": {
    "call_endpoint": "readings_webhook",
    "send_property": "settings",
    "write_bucket": "meter_readings"
  }
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/callback/data ​

  • Request: GET /v3/users/{user}/devices/{device}/callback/data
  • Operation: ReadDeviceCallbackResponse
  • Operation ID: Device_ReadCallbackResponseData
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/callback/data' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v3/users/{user}/devices/{device}/callback/data ​

  • Request: POST /v3/users/{user}/devices/{device}/callback/data
  • Operation: CallDeviceCallback
  • Operation ID: Device_CallCallbackData
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Request body (application/json, required)

Data an HTTP device sends: any JSON. The device callback settings (PUT .../callback) decide what happens with it (bucket, endpoint, property, response). ?ts=<epoch ms> sets the timestamp.

Example request: Meter reading

bash
curl -X POST 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/callback/data' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "energy": 1532.8,
  "power": 2.1,
  "voltage": 229.7
}'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/files{file} ​

  • Request: GET /v3/users/{user}/devices/{device}/files
  • Operation: ReadDeviceFiles
  • Operation ID: Device_ReadFilesFiles(?<file>.*$)
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
filepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/filesYOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PUT /v3/users/{user}/devices/{device}/files{file} ​

  • Request: PUT /v3/users/{user}/devices/{device}/files
  • Operation: UpdateDeviceFiles
  • Operation ID: Device_UpdateFilesFiles(?<file>.*$)
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
filepathstringyes

Request body (application/json, required)

A JSON object.

Example request (skeleton generated from the schema: required fields only, neutral values)

bash
curl -X PUT 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/filesYOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PATCH /v3/users/{user}/devices/{device}/files{file} ​

  • Request: PATCH /v3/users/{user}/devices/{device}/files
  • Operation: RenameDeviceFiles
  • Operation ID: Device_RenameFilesFiles(?<file>.*$)
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
filepathstringyes

Request body (application/json, required)

A JSON object.

Example request (skeleton generated from the schema: required fields only, neutral values)

bash
curl -X PATCH 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/filesYOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

DELETE /v3/users/{user}/devices/{device}/files{file} ​

  • Request: DELETE /v3/users/{user}/devices/{device}/files
  • Operation: DeleteDeviceFiles
  • Operation ID: Device_DeleteFilesFiles(?<file>.*$)
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
filepathstringyes

Example request

bash
curl -X DELETE 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/filesYOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/properties ​

  • Request: GET /v3/users/{user}/devices/{device}/properties
  • Operation: ListDeviceProperties
  • Operation ID: Device_ListProperties
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/properties' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200)

json
[
  {
    "created": 1792263090701,
    "description": "Sampling and alert thresholds",
    "modified": 1792263090701,
    "name": "Settings",
    "property": "settings",
    "type": "configuration",
    "value": {
      "alerts": true,
      "interval": 60,
      "max_temperature": 28.5
    }
  },
  {
    "created": 1792263090701,
    "modified": 1792263090701,
    "name": "Location",
    "property": "location",
    "value": {
      "lat": 40.4168,
      "lon": -3.7038
    }
  },
  {
    "created": 1792263090701,
    "modified": 1792263090701,
    "name": "Calibration",
    "perm": {
      "readOnly": [
        "member"
      ]
    },
    "property": "calibration",
    "value": {
      "gain": 1.02,
      "offset": -0.4
    }
  },
  {
    "created": 1792263090701,
    "modified": 1792263090701,
    "name": "Dashboard",
    "property": "dashboard",
    "value": {
      "source": "url",
      "url": "/v1/users/YOUR_USER/storages/fleet_app/files/"
    }
  }
]

POST /v3/users/{user}/devices/{device}/properties ​

  • Request: POST /v3/users/{user}/devices/{device}/properties
  • Operation: CreateDeviceProperty
  • Operation ID: Device_CreateProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Request body (application/json, required)

The body matches one of these 2 variants.

Variant 1

FieldTypeRequiredConstraintsDescription
(body)array of objectno
(body)[].descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
(body)[].formobjectno
(body)[].form.fieldsanyyes
(body)[].namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
(body)[].permobjectno
(body)[].perm.hiddenarray of stringnoUnique items
(body)[].perm.readOnlyarray of stringnoUnique items
(body)[].propertystringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
(body)[].typestringnoOne of: ``, configuration
(body)[].valueanyyes

Variant 2: Property Create. Schema for creating a property

Schema for creating a property

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
formobjectno
form.fieldsanyyes
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
permobjectno
perm.hiddenarray of stringnoUnique items
perm.readOnlyarray of stringnoUnique items
propertystringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
typestringnoOne of: ``, configuration
valueanyyes

Example request: Configuration value

bash
curl -X POST 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/properties' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Sampling and alert thresholds",
  "name": "Settings",
  "property": "settings",
  "type": "configuration",
  "value": {
    "alerts": true,
    "interval": 60,
    "max_temperature": 28.5
  }
}'

Example body: Location

json
{
  "name": "Location",
  "property": "location",
  "value": {
    "lat": 40.4168,
    "lon": -3.7038
  }
}

Example body: Read-only for project members

json
{
  "name": "Calibration",
  "perm": {
    "readOnly": [
      "member"
    ]
  },
  "property": "calibration",
  "value": {
    "gain": 1.02,
    "offset": -0.4
  }
}

Example body: Url dashboard of the resource

json
{
  "name": "Dashboard",
  "property": "dashboard",
  "value": {
    "source": "url",
    "url": "/v1/users/YOUR_USER/storages/fleet_app/files/"
  }
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/properties/{property} ​

  • Request: GET /v3/users/{user}/devices/{device}/properties/
  • Operation: ReadDeviceProperty
  • Operation ID: Device_ReadProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
propertypathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/properties/YOUR_PROPERTY' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PUT /v3/users/{user}/devices/{device}/properties/{property} ​

  • Request: PUT /v3/users/{user}/devices/{device}/properties/
  • Operation: UpdateDeviceProperty
  • Operation ID: Device_UpdateProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
propertypathstringyes

Request body (application/json, required)

Schema for updating a property

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
formobjectno
form.fieldsanyyes
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
permobjectno
perm.hiddenarray of stringnoUnique items
perm.readOnlyarray of stringnoUnique items
propertystringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
typestringnoOne of: ``, configuration
valueanyyes

Example request: Hide from project members

bash
curl -X PUT 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/properties/YOUR_PROPERTY' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "perm": {
    "hidden": [
      "member"
    ]
  },
  "value": "internal note"
}'

Example body: Replace the value

json
{
  "value": {
    "alerts": true,
    "interval": 30,
    "max_temperature": 27
  }
}

Example body: Value, name and description

json
{
  "description": "Faster sampling during commissioning",
  "name": "Settings",
  "value": {
    "alerts": false,
    "interval": 10,
    "max_temperature": 28.5
  }
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PATCH /v3/users/{user}/devices/{device}/properties/{property} ​

  • Request: PATCH /v3/users/{user}/devices/{device}/properties/
  • Operation: UpdateDeviceProperty
  • Operation ID: Device_PatchProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
propertypathstringyes

Request body (application/json, required)

The body matches one of these 2 variants.

Variant 1

FieldTypeRequiredConstraintsDescription
valueanyyes

Variant 2

FieldTypeRequiredConstraintsDescription
*anyno

Example request: Change some fields of the value

bash
curl -X PATCH 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/properties/YOUR_PROPERTY' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "value": {
    "interval": 30
  }
}'

Example body: Flattened fields

json
{
  "value.alerts": false,
  "value.max_temperature": 27
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

DELETE /v3/users/{user}/devices/{device}/properties/{property} ​

  • Request: DELETE /v3/users/{user}/devices/{device}/properties/
  • Operation: DeleteDeviceProperty
  • Operation ID: Device_DeleteProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
propertypathstringyes

Example request

bash
curl -X DELETE 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/properties/YOUR_PROPERTY' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/properties/{property}/clone ​

  • Request: GET /v3/users/{user}/devices/{device}/properties/{property}/clone
  • Operation: CloneDevicePropertyConfig
  • Operation ID: Device_ClonePropertyConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
propertypathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/properties/YOUR_PROPERTY/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v3/users/{user}/devices/{device}/properties/{property}/clone ​

  • Request: POST /v3/users/{user}/devices/{device}/properties/{property}/clone
  • Operation: CloneDeviceProperty
  • Operation ID: Device_CloneProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
propertypathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanno
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
propertystringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Copy with a new id

bash
curl -X POST 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/properties/YOUR_PROPERTY/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "property": "copy_of_property"
}'

Example body: Copy with name and description

json
{
  "description": "Same configuration as the original, for production line 2",
  "name": "Line 2 copy",
  "property": "line_2_property"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/resources ​

  • Request: GET /v3/users/{user}/devices/{device}/resources
  • Operation: AccessDeviceResources
  • Operation ID: Device_AccessResources
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/resources' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/resources/{resource} ​

  • Request: GET /v3/users/{user}/devices/{device}/resources/
  • Operation: AccessDeviceResources
  • Operation ID: Device_AccessOutputResources
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
resourcepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/resources/YOUR_RESOURCE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v3/users/{user}/devices/{device}/resources/{resource} ​

  • Request: POST /v3/users/{user}/devices/{device}/resources/
  • Operation: AccessDeviceResources
  • Operation ID: Device_AccessInputResources
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
resourcepathstringyes

Request body (application/json, required)

Input of the device resource: whatever JSON the resource expects (see GET .../resources for its description). Resources without input take no body.

Example request: Set a target

bash
curl -X POST 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/resources/YOUR_RESOURCE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "auto",
  "setpoint": 21.5
}'

Example body: Switch a relay

json
{
  "in": true
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/services ​

  • Request: GET /v3/users/{user}/devices/{device}/services
  • Operation: ListDeviceServices
  • Operation ID: Device_ListServices
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/services' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/services/{service} ​

  • Request: GET /v3/users/{user}/devices/{device}/services/
  • Operation: ReadDeviceService
  • Operation ID: Device_ReadService
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
servicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/services/YOUR_SERVICE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/services/{service}/vnc ​

  • Request: GET /v3/users/{user}/devices/{device}/services/{service}/vnc
  • Operation: AccessDeviceRemoteDesktop
  • Operation ID: Device_AccessRemoteDesktopVnc
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
servicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/services/YOUR_SERVICE/vnc' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/services/{service}/web ​

  • Request: GET /v3/users/{user}/devices/{device}/services/{service}/web
  • Operation: AccessDeviceWebServices
  • Operation ID: Device_AccessWebServices
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes
servicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/services/YOUR_SERVICE/web' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v3/users/{user}/devices/{device}/stats ​

  • Request: GET /v3/users/{user}/devices/{device}/stats
  • Operation: ReadDeviceStatistics
  • Operation ID: Device_ReadStatistics
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
devicepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v3/users/YOUR_USER/devices/YOUR_DEVICE/stats' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /{version}/users/{user}/devices/{device}/buckets/{bucket}/data ​

  • Request: GET /{version}/users/{user}/devices/{device}/buckets/{bucket}/data
  • Operation: ReadDeviceBucket
  • Operation ID: Device_ReadBucketData
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
versionpathstringyes
userpathstringyes
devicepathstringyes
bucketpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/YOUR_VERSION/users/YOUR_USER/devices/YOUR_DEVICE/buckets/YOUR_BUCKET/data' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden