API documentation

Getting started

Base URL: https://depan-bos.lmsg.gr/api/v1. All endpoints use GET and return JSON. Sign in to the admin UI, open API tokens, create a token, and save it securely. The token is shown only once. Send it with every request as Authorization: Bearer <token>. API requests do not use the admin or bOS passwords.

First, discover the device_id:

curl -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://depan-bos.lmsg.gr/api/v1/devices'

PowerShell example:

$headers = @{ Authorization = 'Bearer YOUR_TOKEN' }
Invoke-RestMethod -Uri 'https://depan-bos.lmsg.gr/api/v1/devices' -Headers $headers

1. List devices

GET /api/v1/devices returns all registered devices. Use each device's id in the remaining endpoints.

{
  "devices": [{
    "id": 1,
    "name": "ComfortClick bOS",
    "building": "DePan",
    "point_count": 347,
    "last_refresh_at": "2026-09-24T12:00:00Z",
    "last_refresh_error": null
  }]
}

The JSON examples show response shapes; values and timestamps are illustrative. Timestamps are UTC.

2. List points and current values

GET /api/v1/devices/{device_id}/points returns point metadata without values. GET /api/v1/devices/{device_id}/values returns the same points with their most recently cached values. The existing device has device_id=1.

curl -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://depan-bos.lmsg.gr/api/v1/devices/1/values?limit=500'

{
  "device_id": 1,
  "total": 347,
  "limit": 500,
  "offset": 0,
  "points": [{
    "id": 123,
    "object_path": "Devices/Example/Sensor",
    "value_name": "Value",
    "node_type": "ExampleType",
    "value": 21.5,
    "status": "ok",
    "last_read_at": "2026-09-24T12:00:00Z"
  }]
}

Both endpoints accept limit (default 100, maximum 500), offset (default 0), and q to search object_path or value_name. If total > offset + limit, increase offset to fetch the next page. The points endpoint omits value, status, and last_read_at.

status is ok after a successful read, null when bOS returns JSON null, or error when the latest read failed. Before the first read, status and last_read_at may be null. On error, the last successful cached value is retained, so check status and last_read_at before using it.

Values refresh automatically about every 15 minutes. Depending on bOS, value may be a number, string, boolean, object, array, or null.

3. Read one point live

GET /api/v1/devices/{device_id}/points/{point_id}/live contacts bOS immediately for one point. Find its point_id from /points or /values. A successful live read also updates the cache and appends a history entry.

curl -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://depan-bos.lmsg.gr/api/v1/devices/1/points/123/live'

{
  "device_id": 1,
  "point_id": 123,
  "object_path": "Devices/Example/Sensor",
  "value_name": "Value",
  "value": 21.5
}

Use /values for bulk reads; it serves cached values quickly. The live endpoint depends on the device connection and may take longer.

4. Read history

GET /api/v1/devices/{device_id}/readings returns the newest readings first. limit defaults to 100 and is capped at 1000. Add point_id to filter to one point.

curl -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://depan-bos.lmsg.gr/api/v1/devices/1/readings?point_id=123&limit=100'

{
  "device_id": 1,
  "readings": [{
    "id": 456,
    "point_id": 123,
    "object_path": "Devices/Example/Sensor",
    "value_name": "Value",
    "observed_at": "2026-09-24T12:00:00Z",
    "value": 21.5,
    "status": "ok"
  }]
}

For the next page, set before to the smallest id returned in the previous page, for example ?point_id=123&limit=100&before=456. The next response contains only older IDs. Failed reads appear with status: "error" and value: null.

Errors and operational notes

The API returns 401 for a missing, invalid, or revoked token; 400 for invalid pagination; 404 for an unknown device or point; and 502 when a live bOS read fails. API error responses contain an error field, for example {"error":"Missing bearer token"}. A 404 response may be HTML.

When a new .bos file is uploaded, removed points disappear and their history is deleted. Use point IDs from a recent /points or /values response. object_path and value_name are kept exactly as exported, including any trailing spaces.

The API provides read access to bOS data. Device, file, and token administration is done in the admin UI.