API reference
LocalSky exposes REST JSON and SSE at /api/v1. LocalSky 1.0.2 uses response contract 2.5.0. The path prefix and contract version are independent.
Start with the API quick start, or download the OpenAPI read profile. The profile covers selected read operations; the reference below also documents control and administration.
Find an endpoint
| Area | Reference |
|---|---|
| Current weather, forecast windows, extra models, archive | Weather and forecasts |
| Plans, zone state, runs, skips, and commands | Irrigation and history |
| Devices, entity inventory, sensor history, ingest | Devices and data ingest |
| Configuration, setup, accounts, backups, system operations | Configuration and administration |
| Live snapshot subscriptions | SSE streams |
| HTTP failures, request IDs, and source diagnostics | Errors and diagnostics |
| Compatibility and migration history | Versions and migrations |
Authentication
Create a token under Settings → Account and send:
Authorization: Bearer lsk_YOUR_TOKEN
The token is shown once. Store it as a secret. It is not restricted to read operations.
GET /api/v1/info is public and reports whether authentication is required. Anonymous health requests receive reduced liveness information. Full source details and normal application data require the configured access policy.
Authentication details · Browser and SSE authentication
Read the values correctly
| Value | Contract |
|---|---|
| Epoch timestamp | UTC seconds |
| Daily date | Installation’s configured local calendar |
*_f, *_in, *_mph, *_mm | Units named by the field, independent of display preferences |
null | Unknown or unavailable |
| Numeric zero | May be valid; legacy snapshot fields can require accompanying validity flags |
Forecast complete | Hourly timestamps are covered; also check the required measurements |
Zone running_known | Whether reported running state is known |
| Future water plan | Projection, not a command or a historical outcome |
Ignore additive fields your client does not understand. Check the API major before relying on a response shape.
Versioning
The legacy /api alias remains for older clients on supported route families. New integrations should use /api/v1. Some newer routes only have the canonical prefix.
API major versions signal breaking response changes; minor versions add compatible fields or routes. Historical details and deprecated fields are in Versions and migrations.
Client tooling
Python client · JavaScript client · OpenAPI · AI integration guide · llms.txt
PWA notification preferences
Both /api/v1/push and the legacy /api/push prefix expose these routes:
| Method | Route | Behavior |
|---|---|---|
| GET | /status | ready, enabled and effective timezone; no private keys |
| GET | /vapid-key | Public application-server key, or 503 when unavailable |
| POST | /subscribe | Idempotent registration; existing choices are preserved |
| POST | /unsubscribe | Remove a subscription |
| POST | /preferences/read | Read choices for the supplied subscription |
| POST | /preferences | Validate and save choices for the supplied subscription |
Preference requests require endpoint plus keys: {p256dh, auth} matching the
stored subscription. A save also includes preferences: {enabled, events, quiet_hours: {enabled, start, end, allow_urgent}, daily_outlook: {enabled, time}}.
Times use HH:MM in the returned location timezone. Invalid times or an enabled
outlook inside quiet hours return 422; unmatched credentials return 404. These
POST routes retain the normal owner/LAN authorization and Origin checks. The
API does not expose a subscription list or another device’s keys.