Devices | Developers | Qubitro Documentation

List all devices in a project

get

Retrieves all devices in the specified project sorted by last_seen (most recent first). Supports filtering by custom metadata fields to query specific device subsets.

Metadata Filtering: Filter devices by custom metadata fields using the format key:value,key2:value2

Example: metadata=location:warehouse,floor:2 returns devices where metadata.location="warehouse" AND metadata.floor="2"

Response Fields:

Device credentials (MQTT username/password or HTTP token) are excluded in list view
Use GET /devices/{device_id} to retrieve credentials for a specific device

Authorizations

AuthorizationstringRequired

Enter your API key with the Bearer prefix, e.g. "Bearer QB_your_api_key_here"

Path parameters

project_idstringRequired

Project ID (UUID format)

Example: 3e5c0246-c759-48e8-8345-27db13f11ff7

Query parameters

metadatastringOptional

Filter by metadata (format: key:value,key2:value2)

Example: location:warehouse,floor:2

Responses

200

Devices retrieved successfully - Sorted by last_seen descending

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Project not found or access denied

application/json

get

/v2/projects/{project_id}/devices

GET /v2/projects/{project_id}/devices HTTP/1.1
Host: api.qubitro.com
Authorization: YOUR_API_KEY
Accept: */*

[
  {
    "avatar": "https://cdn.qubitro.com/avatars/temperature-sensor.png",
    "brand": "Custom",
    "description": "Temperature sensor in warehouse zone A",
    "device_credentials": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "id": "5f8d0d55b54764ca6f3a1234",
    "last_seen": "2024-01-15T14:30:00Z",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "model": "Custom",
    "name": "Temperature Sensor 01",
    "source": "mqtt",
    "tags": [
      "warehouse",
      "zone_a",
      "temperature"
    ]
  }
]

Create a new device

post

Creates a new device in the specified project and generates connection credentials automatically. The response includes MQTT credentials or HTTP token based on the selected protocol.

Required Fields:

name: Device name (max 100 characters)
description: Device description (max 500 characters)
source: Connection protocol - "mqtt", "http", or "intemo-wifi"

Optional Fields:

brand: Device brand (defaults to "Custom")
model: Device model (defaults to "Custom")
tags: Array of alphanumeric tags (e.g., ["sensor", "warehouse", "zone_a"])
metadata: Custom key-value pairs for filtering (e.g., {"location": "warehouse", "floor": "2"})

Generated Credentials:

MQTT: Returns username and password for broker connection
HTTP: Returns token for API authentication
Save credentials immediately - they cannot be retrieved again

Authorizations

AuthorizationstringRequired

Enter your API key with the Bearer prefix, e.g. "Bearer QB_your_api_key_here"

Path parameters

project_idstringRequired

Project ID (UUID format)

Example: 3e5c0246-c759-48e8-8345-27db13f11ff7

Body

avatarstringOptional

Device avatar/icon URL

Example: https://cdn.qubitro.com/avatars/temperature-sensor.png

brandstringOptional

Device brand (defaults to "Custom")

Example: Custom

descriptionstringOptional

Device description (required, max 500 characters)

Example: Temperature sensor in warehouse zone A

idstringOptional

Unique device identifier

Example: 5f8d0d55b54764ca6f3a1234

last_seenstringOptional

Last time device sent data (ISO 8601 format, UTC)

Example: 2024-01-15T14:30:00Z

modelstringOptional

Device model (defaults to "Custom")

Example: Custom

namestringOptional

Device name (required, max 100 characters)

Example: Temperature Sensor 01

sourcestringOptional

Connection protocol: "mqtt", "http", or "intemo-wifi" (required for creation)

Example: mqtt

tagsstring[]Optional

Optional tags for categorization (alphanumeric and underscore only)

Example: ["warehouse","zone_a","temperature"]

Responses

200

Device created successfully - Includes generated connection credentials

application/json

400

Invalid request body - Check required fields and format

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Project not found

application/json

post

/v2/projects/{project_id}/devices

POST /v2/projects/{project_id}/devices HTTP/1.1
Host: api.qubitro.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 424

{
  "avatar": "https://cdn.qubitro.com/avatars/temperature-sensor.png",
  "brand": "Custom",
  "description": "Temperature sensor in warehouse zone A",
  "device_credentials": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "id": "5f8d0d55b54764ca6f3a1234",
  "last_seen": "2024-01-15T14:30:00Z",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "model": "Custom",
  "name": "Temperature Sensor 01",
  "source": "mqtt",
  "tags": [
    "warehouse",
    "zone_a",
    "temperature"
  ]
}

{
  "avatar": "https://cdn.qubitro.com/avatars/temperature-sensor.png",
  "brand": "Custom",
  "description": "Temperature sensor in warehouse zone A",
  "device_credentials": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "id": "5f8d0d55b54764ca6f3a1234",
  "last_seen": "2024-01-15T14:30:00Z",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "model": "Custom",
  "name": "Temperature Sensor 01",
  "source": "mqtt",
  "tags": [
    "warehouse",
    "zone_a",
    "temperature"
  ]
}

Get device details

get

Retrieves detailed information about a specific device including connection credentials. Use this endpoint to get MQTT credentials or HTTP tokens required for device communication.

Returned Credentials:

MQTT devices: Returns device_credentials with username and password
HTTP devices: Returns device_credentials with token

Security Note: Device credentials are sensitive. Store them securely on your device and never expose them publicly.

Authorizations

AuthorizationstringRequired

Enter your API key with the Bearer prefix, e.g. "Bearer QB_your_api_key_here"

Path parameters

project_idstringRequired

Project ID (UUID format)

Example: 3e5c0246-c759-48e8-8345-27db13f11ff7

device_idstringRequired

Device ID

Example: 5f8d0d55b54764ca6f3a1234

Responses

200

Device retrieved successfully - Includes connection credentials

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Device not found or access denied

application/json

get

/v2/projects/{project_id}/devices/{device_id}

GET /v2/projects/{project_id}/devices/{device_id} HTTP/1.1
Host: api.qubitro.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "avatar": "https://cdn.qubitro.com/avatars/temperature-sensor.png",
  "brand": "Custom",
  "description": "Temperature sensor in warehouse zone A",
  "device_credentials": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "id": "5f8d0d55b54764ca6f3a1234",
  "last_seen": "2024-01-15T14:30:00Z",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "model": "Custom",
  "name": "Temperature Sensor 01",
  "source": "mqtt",
  "tags": [
    "warehouse",
    "zone_a",
    "temperature"
  ]
}

Update a device

put

Updates an existing device's properties. All fields are optional - only provided fields will be updated.

Updatable Fields:

name: Device name (max 100 characters)
description: Device description (max 500 characters)
brand: Device brand
model: Device model
tags: Array of alphanumeric tags (replaces existing tags, minimum 1 required if provided)
metadata: Custom key-value pairs (replaces existing metadata, can be cleared with {})

Non-Updatable Fields:

source: Connection protocol cannot be changed after creation
device_credentials: Generated at creation, cannot be modified

Partial Updates: Only include fields you want to change. Omitted fields remain unchanged. To clear metadata, pass an empty object {}. Note: Tags cannot be cleared - at least one tag is required when updating tags.

Example Request:

{
"name": "Updated Sensor Name",
"tags": ["production", "floor_2"],
"metadata": {"location": "warehouse_b", "zone": "cold_storage"}
}

Authorizations

AuthorizationstringRequired

Enter your API key with the Bearer prefix, e.g. "Bearer QB_your_api_key_here"

Path parameters

project_idstringRequired

Project ID (UUID format)

Example: 3e5c0246-c759-48e8-8345-27db13f11ff7

device_idstringRequired

Device ID

Example: 5f8d0d55b54764ca6f3a1234

Body

brandstringOptional

New device brand

Example: Bosch

descriptionstringOptional

New device description (max 500 characters)

Example: Updated sensor location

modelstringOptional

New device model

Example: BME280

namestringOptional

New device name (max 100 characters)

Example: Temperature Sensor 01

tagsstring[]Optional

New tags (replaces existing, minimum 1 required)

Example: ["warehouse","zone_b","humidity"]

Responses

200

Device updated successfully

application/json

400

Invalid request body - At least one field required

application/json

401

Unauthorized - Invalid or missing API key

application/json

403

Forbidden - API key missing 'update' scope

application/json

404

Device not found or access denied

application/json

put

/v2/projects/{project_id}/devices/{device_id}

PUT /v2/projects/{project_id}/devices/{device_id} HTTP/1.1
Host: api.qubitro.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 196

{
  "brand": "Bosch",
  "description": "Updated sensor location",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "model": "BME280",
  "name": "Temperature Sensor 01",
  "tags": [
    "warehouse",
    "zone_b",
    "humidity"
  ]
}

{
  "avatar": "https://cdn.qubitro.com/avatars/temperature-sensor.png",
  "brand": "Custom",
  "description": "Temperature sensor in warehouse zone A",
  "device_credentials": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "id": "5f8d0d55b54764ca6f3a1234",
  "last_seen": "2024-01-15T14:30:00Z",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "model": "Custom",
  "name": "Temperature Sensor 01",
  "source": "mqtt",
  "tags": [
    "warehouse",
    "zone_a",
    "temperature"
  ]
}

Delete a device

delete

⚠️ WARNING: Permanently deletes a device and ALL associated resources. This action CANNOT be undone.

What Gets Deleted:

Device configuration and metadata
Device credentials (MQTT username/password or HTTP token)
All time-series data from TimescaleDB
All functions: decoder, transform, rules, storage functions, schedules
Storage views associated with the device
Widget references in dashboards
Dashboard associations

What Happens:

Device stops receiving/sending data immediately
All historical data is permanently deleted
Functions stop executing
Dashboards using this device will show "device not found"

Cannot Be Undone: There is no way to recover a deleted device or its data.

Alternative: Use Data PURGE endpoint to delete only data while keeping device configuration

Success Response:

{
"success": true,
"message": "Device deleted successfully",
"action": "delete device"
}

Authorizations

AuthorizationstringRequired

Enter your API key with the Bearer prefix, e.g. "Bearer QB_your_api_key_here"

Path parameters

project_idstringRequired

Project ID (UUID format)

Example: 3e5c0246-c759-48e8-8345-27db13f11ff7

device_idstringRequired

Device ID

Example: 5f8d0d55b54764ca6f3a1234

Responses

200

Device deleted successfully - All associated resources removed

application/json

401

Unauthorized - Invalid or missing API key

application/json

403

Forbidden - Insufficient permissions (requires delete scope)

application/json

404

Device not found or access denied

application/json

delete

/v2/projects/{project_id}/devices/{device_id}

DELETE /v2/projects/{project_id}/devices/{device_id} HTTP/1.1
Host: api.qubitro.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "action": "delete device",
  "message": "Operation completed successfully",
  "success": true
}

hashtagList all devices in a project

hashtagCreate a new device

hashtagGet device details

hashtagUpdate a device

hashtagDelete a device

List all devices in a project

Create a new device

Get device details

Update a device

Delete a device