Repository navigation
API
Home · Flow actions · App settings
Use Homey's app API to read, query, add or clear log entries. The app ID is
nl.nielsdeklerk.log. HomeyScript and other Homey apps should call the app
through Homey's API rather than relying on a direct network URL. See
Homey's Web API guide.
The community forum topic
also includes an earlier API example; use the endpoint paths and response
details on this page as the current reference.
Homey's API returns parsed responses:
const app = await Homey.apps.getApp({ id: 'nl.nielsdeklerk.log' });
const result = await app.get({ path: '/' });
console.log(result.logs);For the full file-backed query, use Better Logic Library and wait for log
storage to be ready. In basic mode GET / can return the backlog as an array
instead of the full response object.
Add a message. The community discussion used an older API spelling; this version uses the current HomeyScript method. This writes to the log, not the Timeline:
const app = await Homey.apps.getApp({ id: 'nl.nielsdeklerk.log' });
await app.put({
path: '/addlog/',
body: {
log: 'Door opened',
group: 'Entry',
severity: 6,
facility: 16,
hostname: 'Homey'
}
});
HomeyScript setup for running the API example. Install HomeyScript before using the code on this page.
Paths are relative to the app API.
| Method | Path | Operation | Access |
|---|---|---|---|
GET |
/api-ready |
Check whether app initialization is complete. | Homey authorization |
GET |
/ |
Get log entries. The response is limited to about 900 KB. | Public |
POST |
/ |
Query log entries with filters and paging. | Homey authorization |
PUT |
/addlog/ |
Add a log entry. | Homey authorization |
GET |
/clearlog/ |
Clear the complete log. This is destructive. | Homey authorization |
GET |
/getlogdownloadurl/:returnType |
Create a temporary download for csv, xlsx or json. |
Public |
Homey protects app API endpoints by default, but the current app manifest marks
GET / and GET /getlogdownloadurl/:returnType as public. Homey's
Web API documentation
explains that public endpoints can be called without an API token. The other
routes above use Homey's normal app authorization.
The readiness route returns { "ready": true } after app initialization
and does not wait for BLL's file storage. A request that needs that storage
can still report that BLL is not ready.
Because the public GET / route returns log data, do not store passwords,
access tokens or other sensitive information in entries. Use Homey's API
client where possible rather than sharing direct endpoint URLs.
A basic query response contains a logs array and, when available, a count.
Each entry can include timestamp, message, app, severity, facility
and hostname. The app field corresponds to the Flow action's group.
Without an export returnType, severity and facility are numeric values and
the timestamp is returned as a date value (serialized as an ISO string by the
API). For example:
{
"logs": [
{
"timestamp": "2026-11-13T12:00:00.000Z",
"message": "Door opened",
"app": "Entry",
"severity": 6,
"facility": 17,
"hostname": "Homey"
}
],
"count": 1
}The count is included when the request does not filter by severity, facility,
hostname, app, message or timestamp. Both read endpoints limit a response to
about 900 KB; use skip and take to page through larger logs.
Send JSON to PUT /addlog/ with a non-empty log field:
{
"log": "Door opened",
"group": "Entry",
"severity": 6,
"facility": 16,
"hostname": "Homey",
"timestamp": "2026-11-13T12:00:00.000Z"
}group, severity, facility, hostname and timestamp are optional.
Omitting the timestamp records the current time. Use the numeric values in the
severity-level and category references. A group name
is limited to 100 characters.
POST / accepts filters, paging and output options. Common fields are:
| Field | Meaning |
|---|---|
app |
Match an app/group name |
message |
Match message text |
severity, facility
|
Filter by numeric value |
hostname |
Match a hostname |
timestamp_fromUTC, timestamp_toUTC
|
Restrict the timestamp range |
skip, take
|
Select a page |
timestampFormat |
Add a formatted timestamp_formatted field to each entry |
returnType |
Return json, json_base64, csv, csv_base64, xlsx or xlsx_base64
|
App/group, message and hostname filters match text without case sensitivity.
The timestamp fields represent dates: the app converts them to local calendar days and includes the end date, rather than applying exact timestamp boundaries. When returnType is set, the response contains
the corresponding json, csv or xlsx value instead of the default logs
array; Base64 variants return encoded content. Exported severity and facility
values are names rather than numeric IDs. The current facility-name map is incomplete, so some selected facilities can have no name in exports.
For example, request the first 100 entries for a group:
const app = await Homey.apps.getApp({ id: 'nl.nielsdeklerk.log' });
const result = await app.post({
path: '/',
body: { app: 'Entry', skip: 0, take: 100 }
});
console.log(result.logs);
The log-viewer menu lists the available fields and export formats.
GET /clearlog/ removes existing entries. With file storage, the app then
records a confirmation entry. Treat the endpoint as a destructive operation
even though it uses GET.
The download endpoint returns a temporary download reference. The app settings view handles the associated ready event; the initial reference does not mean the file is ready. In an Advanced Flow use Get log export URL to receive a temporary local link after upload, or Get the (whole) log for file contents. Base64 output is encoded, not encrypted.
Support development - If Simple (Sys) Log is useful to you, you can support its
continued development through GitHub Sponsors,
Patreon,
PayPal, or
bunq.
Thank you!