Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AngelAmoSanchez/TFG-RaspberryPi-BLE/llms.txt

Use this file to discover all available pages before exploring further.

The devices routes manage the inventory of Raspberry Pi sensor nodes that submit BLE scan data. Each device is identified by a unique string device_id chosen by the operator. Devices are registered automatically when the bulk detection endpoint is called, or explicitly via POST /register. All endpoints are mounted under /api/v1/devices.

​
Device model

The following fields are returned by every endpoint that returns a device object.
​
id
number
Auto-incremented integer primary key.
​
device_id
string
Operator-assigned unique identifier, e.g. "pi-entrance-01". Maximum 50 characters.
​
name
string
Human-readable label. null if not set.
​
location
string
Physical location description. null if not set.
​
is_active
boolean
true when the device is active, false when deactivated. Stored as an integer (1/0) in the database and serialised as a boolean in responses.
​
last_seen
string
ISO 8601 timestamp of the most recent detection submission from this device. null if the device has never submitted data.
​
created_at
string
ISO 8601 timestamp of when the device record was first created.
​
updated_at
string
ISO 8601 timestamp of the most recent update to the device record.

​
POST /api/v1/devices/register

Register a new device or update the metadata of an existing one. If a device with the given device_id already exists it is updated in place; otherwise a new record is created. Request body
​
device_id
string
required
Unique identifier for the Raspberry Pi node.
​
name
string
Human-readable label for the device.
​
location
string
Physical location description.
Response Returns the registered or updated device object. 
curl -X POST "http://localhost:8000/api/v1/devices/register" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "pi-entrance-01",
    "name": "Entrance sensor",
    "location": "Floor 1 - Main entrance"
  }'

{
  "id": 1,
  "device_id": "pi-entrance-01",
  "name": "Entrance sensor",
  "location": "Floor 1 - Main entrance",
  "is_active": true,
  "last_seen": null,
  "created_at": "2026-05-15T09:00:00+02:00",
  "updated_at": "2026-05-15T09:00:00+02:00"
}

​
GET /api/v1/devices/

Return all registered devices. Query parameters
​
active_only
boolean
default:"false"
When true, returns only devices whose is_active flag is set. When false (the default), all devices are returned regardless of active state.
Response Returns an array of device objects. 
# All devices
curl "http://localhost:8000/api/v1/devices/"

# Only active devices
curl "http://localhost:8000/api/v1/devices/?active_only=true"

​
GET /api/v1/devices/active

Return devices that have submitted at least one detection within the last N minutes. This is distinct from active_only on the list endpoint, which filters by the stored is_active flag rather than recent activity. Query parameters
​
threshold_minutes
number
default:"60"
Number of minutes to look back from the current time. A device is considered active if its last_seen timestamp falls within this window.
Response Returns an array of device objects for devices seen within the threshold. 
# Devices seen in the last 30 minutes
curl "http://localhost:8000/api/v1/devices/active?threshold_minutes=30"

​
GET /api/v1/devices/

Return a single device by its device_id. Path parameters
​
device_id
string
required
The device’s unique identifier.
Response Returns a single device object, or HTTP 404 if no device with that ID exists. 
curl "http://localhost:8000/api/v1/devices/pi-entrance-01"

{
  "id": 1,
  "device_id": "pi-entrance-01",
  "name": "Entrance sensor",
  "location": "Floor 1 - Main entrance",
  "is_active": true,
  "last_seen": "2026-05-15T10:28:00+02:00",
  "created_at": "2026-05-15T09:00:00+02:00",
  "updated_at": "2026-05-15T10:28:00+02:00"
}

​
GET /api/v1/devices//stats

Return detection statistics scoped to a single device. Path parameters
​
device_id
string
required
The device’s unique identifier.
Response Returns a stats object for the device, or HTTP 404 if the device does not exist. The exact shape is produced by DeviceService.get_device_stats. 
curl "http://localhost:8000/api/v1/devices/pi-entrance-01/stats"

​
PUT /api/v1/devices/

Update the name and/or location of an existing device. Both fields are optional; supply only the ones you want to change. Path parameters
​
device_id
string
required
The device’s unique identifier.
Request body
​
name
string
New human-readable label for the device.
​
location
string
New physical location description.
Response Returns the updated device object, or HTTP 404 if the device does not exist. 
curl -X PUT "http://localhost:8000/api/v1/devices/pi-entrance-01" \
  -H "Content-Type: application/json" \
  -d '{"name": "Main entrance (updated)", "location": "Floor 1 - Lobby"}'

​
POST /api/v1/devices//deactivate

Set is_active to false for the device. Deactivated devices stop appearing in responses filtered by active_only=true, but their detection history is preserved. Path parameters
​
device_id
string
required
The device’s unique identifier.
Response Returns the updated device object with is_active: false, or HTTP 404 if not found. 
curl -X POST "http://localhost:8000/api/v1/devices/pi-entrance-01/deactivate"

​
POST /api/v1/devices//activate

Set is_active to true for a previously deactivated device. Path parameters
​
device_id
string
required
The device’s unique identifier.
Response Returns the updated device object with is_active: true, or HTTP 404 if not found. 
curl -X POST "http://localhost:8000/api/v1/devices/pi-entrance-01/activate"
Use POST /{device_id}/deactivate and POST /{device_id}/activate instead of PUT /{device_id} for toggling device state. The dedicated activation endpoints provide a cleaner audit trail and avoid accidentally overwriting name or location in the same request.

Build docs developers (and LLMs) love

Get started for freeTalk to us