Skip to content
Arie J. Godschalk edited this page Nov 15, 2026 · 6 revisions

Simple (Sys) Log 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.

Calling from HomeyScript

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);

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'
  }
});

Endpoints

Paths are relative to the app API.

Method Path Operation Access
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

Access and privacy

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.

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.

Add a log entry

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.

Query the log

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);

GET /clearlog/ removes existing entries and 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; for most integrations, the Flow export action or a POST / query with returnType is simpler. Base64 output is encoded, not encrypted.

Clone this wiki locally