Repository navigation
API
Home · Variables · Developer guide
The API is useful to HomeyScript users, automation tools and Homey app
developers. You can read or update BLL variables without writing a Homey app.
The app ID is net.i-dev.betterlogic. Call routes through Homey's API
mechanisms and keep credentials private. A route marked public in the
app manifest should not be assumed to be anonymously accessible. See
Homey's Web API guide
for permissions and platform limitations.
The HomeyAPI app object takes options objects and returns promises:
const app = await Homey.apps.getApp({ id: 'net.i-dev.betterlogic' });
const variables = await app.get({ path: '/all' });
console.log(variables);Read and update an existing number variable:
const app = await Homey.apps.getApp({ id: 'net.i-dev.betterlogic' });
const name = encodeURIComponent('DoorCount');
const variable = await app.get({ path: '/' + name });
console.log(variable);
await app.put({ path: '/' + name + '/increment/1' });Handle errors and unexpected results in real scripts. Encode every name and
value placed in a path using encodeURIComponent.
Older community examples may call apiGet or apiPut on the app object.
Those are not the current HomeyScript methods; a
2024 migration question
documents the resulting apiPut is not a function error. Use the options-object
methods shown above and check the current
HomeyScript migration guide
when adapting an older script.
These are separate examples for already-created variables:
const app = await Homey.apps.getApp({ id: 'net.i-dev.betterlogic' });
await app.put({ path: '/' + encodeURIComponent('HouseStatus') + '/' + encodeURIComponent('Away') });
await app.put({ path: '/' + encodeURIComponent('GuestMode') + '/toggle' });
await app.put({ path: '/trigger/' + encodeURIComponent('Doorbell') });HouseStatus must be text, GuestMode boolean, and Doorbell a trigger.
These operations change live values; test with dedicated variables first.
The full app API path for an external client is under
/api/app/net.i-dev.betterlogic/ on Homey. Use the appropriate Homey
authorization mechanism, not a token pasted into a shared Flow or screenshot.
Declare homey:app:net.i-dev.betterlogic in your app manifest. The Homey
Apps SDK uses a path string, unlike HomeyScript's options object:
const api = this.homey.api.getApiApp('net.i-dev.betterlogic');
if (!await api.getInstalled()) throw new Error('Better Logic Library is not installed');
const variables = await api.get('/all');
this.log(variables);For expression decoding and shared libraries, prefer the
betterlogiclibrary package rather than calling its
internal integration routes directly.
Paths are relative to the BLL app API. These routes are marked public in the current app manifest; actual access is subject to Homey's API rules.
| Method | Path | Operation |
|---|---|---|
| GET | /all |
Get all variables. |
| GET | /:variable |
Get one variable as an object with name, type and value. |
| PUT | /:variable/:value |
Set an existing text, number or boolean variable. A boolean also accepts toggle as the value. |
| PUT | /:variable/:action/:value |
Increment or decrement an existing number variable. Actions are increment or i, and decrement or d. |
| PUT | /trigger/:variable |
Execute an existing trigger variable. |
Use the exact variable name, preserving case. The setter returns OK on
success. The single-variable GET returns Incorrect call for a missing
variable, rather than a variable object; do not treat every response as
success. The current handlers use truthiness and numeric-prefix parsing in
some validation, so do not rely on an empty value being accepted or malformed
numeric input being rejected. Validate inputs in the caller.
The current manifest also declares private routes GET /library/:library,
POST /decode, POST /express, POST /date, POST /time, GET /locale,
GET /exports, GET /locales, GET /timezones and
POST /getdownloadurl. POST /internal/ is also declared. These are
integration surfaces used by the app and its client; payloads and behavior
can change. Use the package documentation and source for the version you
integrate, rather than treating them as stable public endpoints.
Support development - If Better Logic Library is useful to you, you can support its
continued development through GitHub Sponsors,
Patreon,
PayPal, or
bunq.
Thank you!