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 detections routes are the primary ingestion surface for BLE scan data produced by Raspberry Pi sensor nodes. Each detection record captures a hashed device address, the received signal strength (RSSI in dBm), a proximity zone (near, medium, or far), a timestamp, and the ID of the IoT node that performed the scan. All endpoints are mounted under /api/v1/detections.

​
POST /api/v1/detections/

Create a single detection record. The IoT device ID is passed as a query parameter rather than in the request body so that the same body schema can be reused without coupling it to the sender’s identity. Query parameters
​
device_id
string
required
Unique identifier of the Raspberry Pi that recorded the detection. The device’s last_seen timestamp is updated automatically on every successful call.
Request body
​
device_hash
string
required
SHA-based hash of the detected BLE MAC address. Raw MAC addresses are never stored.
​
rssi
number
required
Received signal strength in dBm. Negative integer, e.g. -65.
​
zone
string
required
Proximity zone assigned by the Pi: near, medium, or far.
​
timestamp
string
ISO 8601 timestamp of when the BLE advertisement was observed. If omitted, the server sets the current time in the Europe/Madrid timezone.
Response Returns the saved detection object as a JSON dictionary.
​
id
number
Auto-incremented primary key of the detection record.
​
device_hash
string
Hashed BLE MAC address.
​
rssi
number
Signal strength in dBm.
​
zone
string
Proximity zone: near, medium, or far.
​
timestamp
string
ISO 8601 timestamp of the detection.
​
device_id
string
ID of the IoT node that submitted the detection.
curl -X POST "http://localhost:8000/api/v1/detections/?device_id=pi-entrance-01" \
  -H "Content-Type: application/json" \
  -d '{
    "device_hash": "a3f1c2b4d5e6f7a8b9c0d1e2f3a4b5c6",
    "rssi": -65,
    "zone": "near",
    "timestamp": "2026-05-15T10:30:00"
  }'

{
  "id": 1042,
  "device_hash": "a3f1c2b4d5e6f7a8b9c0d1e2f3a4b5c6",
  "rssi": -65,
  "zone": "near",
  "timestamp": "2026-05-15T10:30:00+02:00",
  "device_id": "pi-entrance-01"
}

​
POST /api/v1/detections/bulk

Create multiple detection records in a single request. This is the preferred endpoint for Raspberry Pi nodes that batch their scan results before sending. The device is automatically registered or updated with the supplied name and location fields. Request body
​
device_id
string
required
Unique identifier of the Raspberry Pi submitting the batch.
​
detections
object[]
required
Array of detection objects. Each element should contain at minimum device_hash, rssi, and zone. The timestamp field is optional in each element; if absent, the server uses the current time.
​
name
string
Human-readable label for the device, e.g. "Entrance sensor". Updates the stored device name if the device already exists.
​
location
string
Physical location description, e.g. "Floor 1 - Main entrance". Updates the stored device location if the device already exists.
Response
​
message
string
Confirmation string including the count of saved records.
​
device_id
string
ID of the submitting device, echoed back.
​
count
number
Number of detection records that were saved.
curl -X POST "http://localhost:8000/api/v1/detections/bulk" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "pi-entrance-01",
    "name": "Entrance sensor",
    "location": "Floor 1 - Main entrance",
    "detections": [
      {"device_hash": "a3f1c2b4d5e6f7a8b9c0d1e2f3a4b5c6", "rssi": -65, "zone": "near"},
      {"device_hash": "b4e2d3c5f6a7b8c9d0e1f2a3b4c5d6e7", "rssi": -78, "zone": "medium"},
      {"device_hash": "c5f3e4d6a7b8c9d0e1f2a3b4c5d6e7f8", "rssi": -91, "zone": "far"}
    ]
  }'

{
  "message": "Guardadas 3 detecciones",
  "device_id": "pi-entrance-01",
  "count": 3
}

​
GET /api/v1/detections/recent

Return the most recent detection records, optionally filtered by proximity zone. Results are ordered by descending timestamp. Query parameters
​
limit
number
default:"100"
Maximum number of records to return. Must not exceed 1000.
​
zone
string
Filter to a single proximity zone. Accepted values: near, medium, far. Omit to return records from all zones.
Response Returns an array of detection objects. Each element has the same shape as the single-detection response above. 
# Last 50 near-zone detections
curl "http://localhost:8000/api/v1/detections/recent?limit=50&zone=near"

[
  {
    "id": 1042,
    "device_hash": "a3f1c2b4d5e6f7a8b9c0d1e2f3a4b5c6",
    "rssi": -65,
    "zone": "near",
    "timestamp": "2026-05-15T10:30:00+02:00",
    "device_id": "pi-entrance-01"
  }
]

​
GET /api/v1/detections/count

Count the number of unique BLE devices detected within the last N hours, optionally constrained to a single zone. The response also includes a people estimate derived by dividing unique device count by the DEVICES_PER_PERSON ratio (default 1.5). Query parameters
​
hours
number
default:"24"
How far back in time to look, measured in hours from the current moment.
​
zone
string
Filter to a single proximity zone: near, medium, or far. Omit to count across all zones.
Response
​
start_time
string
ISO 8601 timestamp of the start of the counting window.
​
end_time
string
ISO 8601 timestamp of the end of the counting window (current server time).
​
zone
string
The zone filter that was applied, or null if none was requested.
​
unique_devices
number
Count of distinct device_hash values observed within the window.
​
estimated_people
number
People estimate: round(unique_devices / devices_per_person), minimum 1 when at least one device is present.
Supplying an invalid zone value (e.g. zone=basement) returns HTTP 400 with a detail message identifying the unrecognised zone string.
# Unique devices in the near zone over the last 8 hours
curl "http://localhost:8000/api/v1/detections/count?hours=8&zone=near"

{
  "start_time": "2026-05-15T02:30:00+02:00",
  "end_time": "2026-05-15T10:30:00+02:00",
  "zone": "near",
  "unique_devices": 47,
  "estimated_people": 31
}

Build docs developers (and LLMs) love

Get started for freeTalk to us