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

Chronograph API

Home · Flow actions · Widgets

Chronograph exposes an app API to list, start, inspect, pause, resume and stop stopwatches, timers and transitions. Calls address a chronograph by its type and name. A timer and stopwatch can have the same name without being the same chronograph.

Contents

Breaking change: individual app API endpoints now use names instead of IDs. Generic individual endpoints also require a type. Update existing HomeyScript and other integrations; the old ID-based paths no longer work.

The app ID is nl.fellownet.chronograph. The app API is not public: callers must use Homey's authorized API mechanisms. Keep credentials and tokens private. Homey Cloud does not support apps exposing a Web API; see Homey's Web API documentation.

Calling from HomeyScript

Install HomeyScript and use its HomeyAPI app object. Methods take an options object and return promises. The response is already parsed:

const app = await Homey.apps.getApp({ id: 'nl.fellownet.chronograph' });
const timers = await app.get({ path: '/timers/' });
console.log(timers);

Start a previously configured timer and then pause it:

const app = await Homey.apps.getApp({ id: 'nl.fellownet.chronograph' });
const name = 'Kitchen fan';
await app.post({
  path: '/timers/',
  body: { name, time: 10, unit: 'minutes' }
});
await app.put({
  path: '/timers/' + encodeURIComponent(name),
  body: { running: false }
});

This fails if the timer is already active. Add replace: true to the start body only when you intend to reset it. Resume with { running: true }, or stop it with:

const app = await Homey.apps.getApp({ id: 'nl.fellownet.chronograph' });
await app.delete({ path: '/timers/' + encodeURIComponent('Kitchen fan') });

The HomeyAPI app object supports get({ path }), put({ path, body }), post({ path, body }), delete({ path }), and call({ method, path, body }). See the HomeyAPI app reference. Old apiGet and apiDelete examples are obsolete.

Calling from another Homey app

Declare homey:app:nl.fellownet.chronograph in the calling app's manifest. The Homey Apps SDK client uses a path string, unlike HomeyScript's HomeyAPI options object:

const api = this.homey.api.getApiApp('nl.fellownet.chronograph');
if (!await api.getInstalled()) throw new Error('Chronograph is not installed');
const timers = await api.get('/timers/');
this.log(timers);

The SDK client also provides post(path, body), put(path, body), and delete(path). See Homey's Web API guide for permissions and client details.

App API reference

Use the exact configured name, including case, and URL-encode it when it appears in a path: encodeURIComponent(name). Wildcards are not supported by these endpoints. Collections contain active instances, including paused ones; finished and stopped instances are removed.

Method Path Operation
GET /stopwatches/ List active stopwatches.
POST /stopwatches/ Start a configured stopwatch.
GET /stopwatches/:name Get an active stopwatch.
PUT /stopwatches/:name Pause or resume an active stopwatch.
DELETE /stopwatches/:name Stop an active stopwatch.
GET /timers/ List active timers.
POST /timers/ Start a configured timer.
GET /timers/:name Get an active timer.
PUT /timers/:name Pause or resume an active timer.
DELETE /timers/:name Stop an active timer.
GET /transitions/ List active transitions.
POST /transitions/ Start a configured transition.
GET /transitions/:name Get an active transition.
PUT /transitions/:name Pause or resume an active transition.
DELETE /transitions/:name Stop an active transition.
GET /chronographs/ List all active instances.
GET /chronographs/:type/:name Get an active instance.
PUT /chronographs/:type/:name Pause or resume an active instance.
DELETE /chronographs/:type/:name Stop an active instance.
GET /allchronographs/ List configured names grouped by type.

For generic paths :type is stopwatch, timer, or transition (singular, lowercase). GET /allchronographs/ returns an object of name arrays, not active states; keys reflect the app's configuration. Names can come from saved Flow cards or saved start values. Configure a name in an enabled, saved Flow before starting it through the API. A configured name is not necessarily active.

Start request

POST returns the started chronograph object. A start uses the same lifecycle and Flow triggers as a Flow start and saves the values used by widget defaults.

Field Applies to Meaning
name All Required, exact configured name; it must not be blank or contain *.
replace All Optional boolean; defaults to false. Set true to replace an active or paused instance.
time Timer, transition Required number or supported Math expression. Timer duration must be positive; transition duration must be non-negative.
unit Timer, transition Required: milliseconds, seconds, minutes, hours, or days.
from, to Transition Required numeric start and end values.
steps Transition Required integer of at least 2. Short transitions may use fewer effective steps.

Example stopwatch request: { "name": "Workout" }.

Example transition request:

{ "name": "Living room dim", "time": 5, "unit": "minutes", "from": 0, "to": 1, "steps": 10, "replace": false }

Start rejects unknown names, invalid parameters and existing instances unless replace is true. A failed validation does not replace the active instance. A transition produces values; use a step-trigger Flow to apply them to a device.

Pause, resume and stop

Send { "running": false } to pause or { "running": true } to resume. running must be a boolean. The response is the updated chronograph object. DELETE stops the instance and returns true. An operation on a missing or finished instance fails; a timer can finish between a list and a later call, so handle errors.

Response fields

An active or newly started object contains name, data, duration, targetDuration, and running. data.type identifies the type. Transition data includes from, to, and effective steps; saved flowValues may be present. Durations are in milliseconds: duration is elapsed time, and timer/transition remaining time is targetDuration - duration. Stopwatches have no target; a non-finite target may be represented as null in JSON. Running values are snapshots and continue to change after the response.

Realtime events

The chronograph_event lifecycle event and periodic chronograph_event_multi updates omit data.flowValues. When saved Flow/API start values actually change, chronograph_flow_values_changed sends type, name, and flowValues. Widget starts do not change these saved values.

In a lifecycle event, removed means the active instance has ended. It can mean it was stopped explicitly, or that a timer or transition finished naturally; it does not mean the configured chronograph was deleted.

Clone this wiki locally