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"
  ]
}

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
}