Reference Telemetry

telemetry API

Current state, history, positions, maps, health and reports.

Base path /api/v1/telemetry behind the gateway. Authentication, rate limits and the error format are the same for every service: see Scripting MowDeck. Rendered from apps/web/openapi/telemetry.json (OpenAPI 3.1), which you can also load into any OpenAPI tool.

Operations

telemetry

GET /api/v1/telemetry/accounts/me/mowers/capabilities

List Capabilities

Capabilities of every mower of the caller's account that the caller may view and whose gateway has reported them (same bound as the states list).

Status	Meaning	Body
200	Successful Response	application/json MowerCapabilitiesList

GET /api/v1/telemetry/accounts/me/mowers/states

List States

Latest state of every mower of the caller's account that the caller may view.

Status	Meaning	Body
200	Successful Response	application/json MowerStateList

GET /api/v1/telemetry/error-codes/{vendor}/{code}

Explain Vendor Code

Explain one code of a vendor (the lexicon's key, see GET /error-lexicons), e.g. /error-codes/mammotion/1201?locale=de. An unknown vendor or code answers 200 with known false.

Parameter	In	Type	Required	Notes
vendor	path	string	yes	pattern ^[a-z][a-z0-9_]{0,31}$
code	path	string	yes	min length 1; max length 64
locale	query	string or null	no	Language of the texts (de, en; de-DE works too). Default: the first language of Accept-Language, else en; a language without texts falls back to en.

Status	Meaning	Body
200	Successful Response	application/json ErrorExplanation
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/error-lexicons

List Error Lexicons

The installed error lexicons (vendor key and name, connection kinds, number of codes and of unverified ones, locales); empty while the Device-Gateway does not answer.

Status	Meaning	Body
200	Successful Response	application/json ErrorLexiconList

GET /api/v1/telemetry/mowers/{mower_id}/aerial

Get Aerial

Whether an aerial photo can be laid under the mower's map, with its credit line, zoom range and the box where tiles are served; enabled: false without a configured source. 404 no-map-yet before the gateway published a map.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Status	Meaning	Body
200	Successful Response	application/json AerialOut
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/aerial/{z}/{x}/{y}

Get Aerial Tile

One aerial photo tile (Web Mercator, XYZ) around the mower's map. Tiles away from the map or outside the zoom range are 404 tile-outside-map, so this is no open proxy; new tiles are rate limited per account (429).

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
z	path	integer	yes	min 0; max 24
x	path	integer	yes	min 0
y	path	integer	yes	min 0

Status	Meaning	Body
200	Successful Response	image/jpeg any, image/png any
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/battery

Get Battery

Battery percentage over time; with step one point per bin (mean, min, max, charging if any). Same ranges and limits as the history.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
from	query	string (date-time) or null	no	Start of the range (inclusive).
to	query	string (date-time) or null	no	End of the range (exclusive).
step	query	string or null	no	Bin width such as 5s, 1m, 1h or 1d (date_bin); raw rows without.

Status	Meaning	Body
200	Successful Response	application/json BatterySeries
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/capabilities

Get Capabilities

What the mower can do over its connection; 404 no-capabilities-yet before the gateway reported it.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Status	Meaning	Body
200	Successful Response	application/json MowerCapabilitiesOut
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/commands

Get Commands

Status transitions of the mower's commands (accepted, executed, ...), newest first.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
limit	query	integer	no	min 1; max 1000; default 50

Status	Meaning	Body
200	Successful Response	application/json CommandTimeline
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/error

Get Mower Error

The mower's current error (MowerState.error_code) in plain words, with the lexicon of its vendor; error is null while it reports none. 404 "no telemetry yet" before the first state.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
locale	query	string or null	no	Language of the texts (de, en; de-DE works too). Default: the first language of Accept-Language, else en; a language without texts falls back to en.

Status	Meaning	Body
200	Successful Response	application/json MowerErrorOut
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/error-codes

Explain Mower Codes

Explain codes of this mower (e.g. the error counts of its health page) with the lexicon of its vendor. 404 "no telemetry yet" before the first state.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
code	query	array of string	yes	Codes as the mower reports them; repeat the parameter for more.; min items 1; max items 20
locale	query	string or null	no	Language of the texts (de, en; de-DE works too). Default: the first language of Accept-Language, else en; a language without texts falls back to en.

Status	Meaning	Body
200	Successful Response	application/json ErrorExplanationList
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/error-lexicon

Browse Mower Lexicon

Browse the error lexicon of this mower's vendor (picked by its cloud provider, else its connection kind): a page of entries in plain words, ordered by code, filtered by text, category, severity and codes, with the counts per category and severity for filter chips. lexicon is null when no lexicon applies or the Device-Gateway does not answer. 404 "no telemetry yet" before the first state.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
q	query	string	no	Search the code and the texts (every word must match); empty: all.; max length 100; default ""
category	query	MowerErrorCategory or null	no
severity	query	ErrorSeverity or null	no
code	query	array of string or null	no	Only these codes (e.g. the ones this mower reported); repeatable.
offset	query	integer	no	min 0; max 100000; default 0
limit	query	integer	no	min 1; max 100; default 50
locale	query	string or null	no	Language of the texts (de, en; de-DE works too). Default: the first language of Accept-Language, else en; a language without texts falls back to en.

Status	Meaning	Body
200	Successful Response	application/json ErrorLexiconSearchReply
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/health

Get Health

Health totals: blade and mowing hours, distance, battery cycles, charge sessions and errors since the first state; 404 no-telemetry-yet when nothing was recorded.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Status	Meaning	Body
200	Successful Response	application/json MowerHealthOut
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/health/blade-changes

Get Blade Changes

Recorded blade changes, newest first (at most 100).

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Status	Meaning	Body
200	Successful Response	application/json BladeChangeList
422	Validation Error	application/json HTTPValidationError

POST /api/v1/telemetry/mowers/{mower_id}/health/blade-reset

Reset Blade

Record a blade change: the blade hours since the change restart at zero and the threshold reminder is armed again. Works before the first telemetry, too.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Request body (required): application/json BladeResetIn

Status	Meaning	Body
200	Successful Response	application/json MowerHealthOut
422	Validation Error	application/json HTTPValidationError

PUT /api/v1/telemetry/mowers/{mower_id}/health/blade-threshold

Set Blade Threshold

Set the mower's blade reminder threshold in hours (can_manage_mowers, like the blade reset); null drops it, so the mower follows its own warning again (device_blade_warn_hours) when it reports one, else the default (MOWDECK_TELEMETRY_BLADE_HOURS_THRESHOLD); blade_hours_threshold_effective names the threshold in effect. The reminder is armed again when the blade hours shown lie below the new effective threshold. Works before the first telemetry, too. The warning stored on the mower itself is not changed.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Request body (required): application/json BladeThresholdIn

Status	Meaning	Body
200	Successful Response	application/json MowerHealthOut
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/health/daily

Get Health Daily

Health totals per UTC day (default: the last 30 days, at most 366).

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
from	query	string (date) or null	no	First UTC day (inclusive, YYYY-MM-DD).
to	query	string (date) or null	no	Last UTC day (inclusive).

Status	Meaning	Body
200	Successful Response	application/json HealthDaily
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/heatmap

Get Heatmap

A raster layer over the mower's map frame for a time range (default: the last 7 days): cut share and missed areas (coverage), share of fixed RTK samples (rtk) or median signal in dBm (wifi, mnet). 404 no-map-yet before the gateway published a map.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
layer	query	Layer	yes	coverage, rtk, wifi or mnet.
from	query	string (date-time) or null	no	Start of the range (inclusive).
to	query	string (date-time) or null	no	End of the range (exclusive).
cell	query	0.5 | 1 | 2	no	Cell size in metres: 0.5, 1 or 2.; default 1.0

Status	Meaning	Body
200	Successful Response	application/json MowerHeatmap
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/history

Get History

State history; with step one point per bin (last activity and RTK fix, battery mean and range, charging if any, last position).

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
from	query	string (date-time) or null	no	Start of the range (inclusive).
to	query	string (date-time) or null	no	End of the range (exclusive).
step	query	string or null	no	Bin width such as 5s, 1m, 1h or 1d (date_bin); raw rows without.

Status	Meaning	Body
200	Successful Response	application/json StateHistory
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/map

Get Map

The mower's map as the Device-Gateway last read it; 404 no-map-yet before that.

The ETag is the map revision, so a client can revalidate with If-None-Match.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
if-none-match	header	string or null	no

Status	Meaning	Body
200	Successful Response	application/json MowerMapOut
304	Not modified (If-None-Match equals the ETag)	no body
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/path

Get Mow Path

The route the mower planned for its running job (local metres of its map) with the progress along it, as the Device-Gateway last published it; 404 no-path without a job or before the route arrived. Clients poll it while the mower works.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Status	Meaning	Body
200	Successful Response	application/json MowPathOut
404	no-path: no running job whose route is known.	no body
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/positions

Get Positions

The newest limit positions of the range, oldest first.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
from	query	string (date-time) or null	no	Start of the range (inclusive).
to	query	string (date-time) or null	no	End of the range (exclusive).
limit	query	integer	no	min 1; max 100000; default 1000

Status	Meaning	Body
200	Successful Response	application/json PositionTrack
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/state

Get State

Latest state of a mower; 404 "no telemetry yet" before the first state arrived.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Status	Meaning	Body
200	Successful Response	application/json MowerStateSnapshot
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/widget

Get Widget State

A compact state for the iOS widgets and the Live Activity (ADR 0059): activity (offline when stale), battery, rain sensor, error (code, vendor message and, from the error lexicon, title, category and severity, ADR 0067) and the job with progress, area name and remaining time. 404 "no telemetry yet" before the first state.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
locale	query	string or null	no	Language of error_title (de, en). Default: the first language of Accept-Language, else en.

Status	Meaning	Body
200	Successful Response	application/json WidgetStateOut
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/widget-map.png

Get Widget Map

A PNG of the mower's map for the iOS map widget (ADR 0059): areas, no-go zones, the mowed path (the mow path up to its progress, else the last 3 hours of the track), the dock and the mower. Bounded in size, cached for 30 seconds and drawn at most twice at a time. 404 no-map-yet before the gateway published a map.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
width	query	integer	no	Pixels (clamped to 700k in all).; min 160; max 1200; default 640
height	query	integer	no	min 96; max 800; default 384
theme	query	string	no	pattern `^(light
if-none-match	header	string or null	no

Status	Meaning	Body
200	The map picture.	image/png any
304	Not modified (If-None-Match equals the ETag)	no body
422	Validation Error	application/json HTTPValidationError
503	All drawing slots are taken; retry in a few seconds.	no body

GET /api/v1/telemetry/reports/summary

Get Report Summary

Day totals (UTC days, default the last 30, at most 366) of every mower of the caller's account that the caller may view, in one call: blade and mowing hours, distance, jobs, online hours, battery cycles, charge sessions and errors by code. Mowers without data in the range are absent; Telemetry does not know sites, so clients filter by Fleet's site_id (or pass mower_id).

Parameter	In	Type	Required	Notes
from	query	string (date) or null	no	First UTC day (inclusive, YYYY-MM-DD).
to	query	string (date) or null	no	Last UTC day (inclusive).
mower_id	query	array of string (uuid) or null	no	Only these mowers (repeatable); invisible ones are left out silently.

Status	Meaning	Body
200	Successful Response	application/json ReportSummary
422	Validation Error	application/json HTTPValidationError

tracking

GET /api/v1/telemetry/mowers/{mower_id}/tracking

Get Tracking Status

The active tracking session of the mower, else the newest one, with its track and links; after returns only newer positions.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
session_id	query	string (uuid) or null	no
after	query	string (date-time) or null	no	Only positions after this time (polling).

Status	Meaning	Body
200	Successful Response	application/json TrackingStatus
422	Validation Error	application/json HTTPValidationError

POST /api/v1/telemetry/mowers/{mower_id}/tracking

Start Tracking

Start tracking by hand (also the safe way to test the whole chain). Answers 200 with the running session when there is one.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Status	Meaning	Body
201	Successful Response	application/json TrackingSessionOut
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/tracking/links

List Tracking Links

The share links of the session (active ones first by recency; tokens are never shown).

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
session_id	query	string (uuid) or null	no

Status	Meaning	Body
200	Successful Response	application/json array of TrackingLinkOut
422	Validation Error	application/json HTTPValidationError

POST /api/v1/telemetry/mowers/{mower_id}/tracking/links

Create Tracking Link

Issue a secret share link (default 48 h). The token is in this answer only.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Request body (required): application/json TrackingLinkIn

Status	Meaning	Body
201	Successful Response	application/json TrackingLinkCreated
422	Validation Error	application/json HTTPValidationError

DELETE /api/v1/telemetry/mowers/{mower_id}/tracking/links/{link_id}

Revoke Tracking Link

Revoke a share link; it stops working at once.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
link_id	path	string (uuid)	yes

Status	Meaning	Body
204	Successful Response	no body
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/tracking/map/{layer}/{z}/{x}/{y}

Tracking Map Tile

One base map tile (Web Mercator, XYZ) under the track of the active or newest session. Tiles away from the tracked positions, outside the zoom range or of a layer that is not offered are 404 tile-outside-map; new tiles are rate limited per account (429).

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
layer	path	"map" | "aerial"	yes
z	path	integer	yes	min 0; max 24
x	path	integer	yes	min 0
y	path	integer	yes	min 0
session_id	query	string (uuid) or null	no

Status	Meaning	Body
200	Successful Response	image/jpeg any, image/png any
422	Validation Error	application/json HTTPValidationError

POST /api/v1/telemetry/mowers/{mower_id}/tracking/photo

Take Tracking Photo

Take one more camera photo for the active session (it goes into the report).

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Status	Meaning	Body
201	Successful Response	application/json TrackingStatus
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/tracking/report.pdf

Tracking Report

The theft report as a PDF: mower, alarm, track (table and drawing), photos, blank owner fields.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
session_id	query	string (uuid) or null	no
lang	query	"de" | "en"	no	default "en"

Status	Meaning	Body
200	Successful Response	no body
422	Validation Error	application/json HTTPValidationError

GET /api/v1/telemetry/mowers/{mower_id}/tracking/sessions

List Tracking Sessions

Past and current sessions of the mower, newest first (at most 20).

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Status	Meaning	Body
200	Successful Response	application/json array of TrackingSessionOut
422	Validation Error	application/json HTTPValidationError

DELETE /api/v1/telemetry/mowers/{mower_id}/tracking/sessions/{session_id}

Delete Tracking Session

Delete an ended session with its links and photos.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
session_id	path	string (uuid)	yes

Status	Meaning	Body
204	Successful Response	no body
422	Validation Error	application/json HTTPValidationError

POST /api/v1/telemetry/mowers/{mower_id}/tracking/stop

Stop Tracking

End the active session ("Fehlalarm / Ortung beenden").

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Request body (required): application/json TrackingStopIn

Status	Meaning	Body
200	Successful Response	application/json TrackingSessionOut
422	Validation Error	application/json HTTPValidationError

POST /api/v1/telemetry/public/tracking/tile

Public Tracking Tile

One base map tile for the page of a share link, only around the shared track. No login; 404 for any unusable token or a tile away from the track, 429 when asked too often.

Request body (required): application/json PublicTileIn

Status	Meaning	Body
200	Successful Response	image/jpeg any, image/png any
422	Validation Error	application/json HTTPValidationError

POST /api/v1/telemetry/public/tracking/view

Public Tracking View

The live page of a share link: the position, the track since the alarm, the times and the mower's name and model. No login; 404 for any unusable token, 429 when asked too often.

Request body (required): application/json PublicTrackIn

Status	Meaning	Body
200	Successful Response	application/json PublicTrackOut
422	Validation Error	application/json HTTPValidationError

zones

GET /api/v1/telemetry/mowers/{mower_id}/zones

List Zones

The mower's virtual zones, the zone it is in and whether the editor is offered.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Status	Meaning	Body
200	Successful Response	application/json ZonesOut
422	Validation Error	application/json HTTPValidationError

POST /api/v1/telemetry/mowers/{mower_id}/zones

Create Zone

Draw a zone (can_control). The current zone is evaluated again at once.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes

Request body (required): application/json ZoneIn

Status	Meaning	Body
201	Successful Response	application/json ZoneOut
403	The caller sees the mower but has no can_control.	no body
404	The mower (or zone) does not exist or is not visible to the caller.	no body
409	Zones are not offered for this mower (vendor_map, no_position) or it has the most zones (limit); the error's code says which.	no body
422	The ring or the name is not acceptable; the error points at it.	no body

GET /api/v1/telemetry/mowers/{mower_id}/zones/stats

Zone Stats

Time per zone (in it, of that mowing, entries) over the last days days.

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
days	query	integer	no	Whole UTC days, today included.; min 1; max 92; default 7

Status	Meaning	Body
200	Successful Response	application/json ZoneStatsOut
422	Validation Error	application/json HTTPValidationError

PATCH /api/v1/telemetry/mowers/{mower_id}/zones/{zone_id}

Update Zone

Rename, reshape or (un)link a zone (can_control).

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
zone_id	path	string (uuid)	yes

Request body (required): application/json ZonePatch

Status	Meaning	Body
200	Successful Response	application/json ZoneOut
403	The caller sees the mower but has no can_control.	no body
404	The mower (or zone) does not exist or is not visible to the caller.	no body
409	Zones are not offered for this mower (vendor_map, no_position) or it has the most zones (limit); the error's code says which.	no body
422	The ring or the name is not acceptable; the error points at it.	no body

DELETE /api/v1/telemetry/mowers/{mower_id}/zones/{zone_id}

Delete Zone

Delete a zone with its recorded time (can_control).

Parameter	In	Type	Required	Notes
mower_id	path	string (uuid)	yes
zone_id	path	string (uuid)	yes

Status	Meaning	Body
204	Successful Response	no body
403	The caller sees the mower but has no can_control.	no body
404	The mower (or zone) does not exist or is not visible to the caller.	no body
409	Zones are not offered for this mower (vendor_map, no_position) or it has the most zones (limit); the error's code says which.	no body
422	The ring or the name is not acceptable; the error points at it.	no body

Schemas

AerialBounds

A box in WGS84 degrees.

Field	Type	Required	Notes
east	number	yes
north	number	yes
south	number	yes
west	number	yes

AerialOut

The aerial photo under a mower's map.

Field	Type	Required	Notes
attribution	string or null	yes	Credit line to show while the photo is on.
bounds	AerialBounds or null	yes	Where tiles are served: the map's outline plus a margin.
enabled	boolean	yes	False when the installation has no aerial photo source.
max_zoom	integer or null	yes	Highest zoom with real detail; scale beyond it.
min_zoom	integer or null	yes
mower_id	string (uuid)	yes
tile_url	string or null	yes	URL template of the tiles ({z}, {x}, {y}); needs the bearer token.

AnchorOut

Where to centre a map that has no vendor geometry.

Field	Type	Required	Notes
lat	number	yes
lon	number	yes

BaseStationPosition

Where the base station stands (WGS84 degrees), as the mower knows it.

Field	Type	Required	Notes
lat	number	yes	min -90.0; max 90.0
lon	number	yes	min -180.0; max 180.0

BaseStationState

The RTK base station of a mower as its connection sees it (MowerState.base_station).

Null on the mower state when the mower is linked to no base station in Fleet.

Field	Type	Required	Notes
base_station_id	string (uuid) or null	no	Fleet's id of the base station (from the registration).
correction_link	RtkCorrectionLink	no	How the corrections reach the mower now; network means the mower does not use its base station at the moment.; default "unknown"
details_at	string (date-time) or null	no	When the details (satellites, rtk_status, wifi_dbm) were last reported; null when never.
firmware	string or null	no	The base station's firmware, as reported.
firmware_info	FirmwareInfo or null	no	Installed and offered firmware of the base station from the vendor's firmware service, and the update state; null before a check.
link_up	boolean or null	no	Whether the mower receives the base station: over LoRa the radio link the mower reports, over the internet whether corrections arrive; null when the mower does not say (or uses network RTK).
lora_channel	integer or null	no	The LoRa channel of the pairing, if reported.
moved	boolean or null	no	The mower reports that the base station was moved since the map was recorded (positions may be shifted); null when not reported.
position	BaseStationPosition or null	no	Where the base station stands; null while not reported.
rtk_status	GnssSolution	no	The base station's own position solution.; default "unknown"
satellites	integer or null	no	Satellites the base station's receiver uses.
wifi_dbm	integer or null	no	The base station's Wi-Fi signal in dBm; null when not reported.

BatteryPointOut

One bin (or one row) of the battery series.

Field	Type	Required	Notes
at	string (date-time)	yes
battery_max	integer	yes
battery_min	integer	yes
battery_percent	integer	yes
charging	boolean	yes

BatterySeries

Battery percentage of a mower in a time range.

Field	Type	Required	Notes
from	string (date-time)	yes
mower_id	string (uuid)	yes
points	array of BatteryPointOut	yes
step_seconds	number or null	yes	Bin width, null for raw rows.
to	string (date-time)	yes
truncated	boolean	yes

BladeChangeList

Recorded blade changes of a mower, newest first.

Field	Type	Required	Notes
items	array of BladeChangeOut	yes
mower_id	string (uuid)	yes

BladeChangeOut

A recorded blade change.

Field	Type	Required	Notes
changed_at	string (date-time)	yes
changed_by	string (uuid) or null	yes	Subject of the principal who recorded it.
id	string (uuid)	yes
note	string or null	yes

BladeResetIn

Body of the blade reset.

Field	Type	Required	Notes
note	string or null	no	Free text, optional.

BladeThresholdIn

PUT .../health/blade-threshold: the mower's blade reminder threshold.

Field	Type	Required	Notes
hours	number or null	yes	Blade hours after which MowDeck reminds of a blade change; null drops the mower's own threshold: the mower's own warning applies again when it reports one, else the installation's default.

CameraAccess

How a camera stream can be reached, if there is one.

Type: "none" | "cloud" | "local"

CommandEventOut

One status transition of a command.

Field	Type	Required	Notes
at	string (date-time)	yes
command_id	string (uuid)	yes
reason	string or null	yes
status	string	yes

CommandTimeline

The newest command transitions of a mower, newest first.

Field	Type	Required	Notes
items	array of CommandEventOut	yes
mower_id	string (uuid)	yes

ConnectionKind

How the Device-Gateway is connected to the mower.

Type: "ble_bridge" | "wifi" | "cloud" | "simulated"

DockPose

Position and orientation of the charging station in the local frame.

Field	Type	Required	Notes
heading_deg	number	no	Local frame, counter-clockwise from +x.; min 0.0; less than 360.0; default 0.0
x	number	yes
y	number	yes

DriveCalibration

The fitted drive behaviour of one mower, as stored in the drive link's options.

Field	Type	Required	Notes
calibrated_at	string (date-time)	yes
dead_zone	number	no	linear below which the mower stands.; min 0.0; max 0.9; default 0.0
drive_speed_setting	number or null	no	The vendor's manual-driving speed setting during the calibration (MowerState.drive_speed_mps); null when the connection has none.
full_speed_mps	number	yes	Ground speed at linear = 1.; max 5.0; greater than 0.0
full_yaw_rate_dps	number	yes	Yaw rate at angular = ±1 in degrees per second.; max 720.0; greater than 0.0
turn_dead_zone	number	no	angular below which the mower does not turn.; min 0.0; max 0.9; default 0.0

DriveCalibrationResult

What a calibration measured and fitted.

Field	Type	Required	Notes
calibration	DriveCalibration	yes
forward_m	number	no	Ground covered going forward.; min 0.0; default 0.0
steps	array of DriveCalibrationStep	no	max items 32

DriveCalibrationStatus

Progress of the drive calibration on this mower (MowerState.drive_calibration).

Field	Type	Required	Notes
reason	string or null	no
result	DriveCalibrationResult or null	no	The fit, once the calibration is done.
run_id	string (uuid)	yes
started_at	string (date-time) or null	no
state	"preparing" | "measuring" | "stopping" | "done" | "aborted" | "failed"	yes
step_index	integer	no	The step being driven (0-based).; min 0.0; default 0
steps	array of DriveCalibrationStep	no	The steps measured so far.; max items 32
steps_total	integer	no	min 0.0; default 0

DriveCalibrationStep

One measured step of a calibration.

Field	Type	Required	Notes
command	number	yes	linear (forward) or angular (turn).; min -1.0; max 1.0
distance_m	number	no	Ground covered during the step.; min 0.0; default 0.0
duration_s	number	yes	min 0.0; max 60.0
kind	"forward" | "turn"	yes
measured	number or null	no	Ground speed in m/s (forward) or yaw rate in degrees per second, left positive (turn); null when too few reports arrived.
note	string or null	no	Why the step is not measured.
outcome	"measured" | "skipped" | "invalid" | "inconsistent" | "outlier"	no	measured (used by the fit), skipped (not driven), invalid (too few reports in the steady window), inconsistent (the opposite turn disagrees) or outlier (breaks the growth with the stick); the last three are left out of the fit.; default "measured"
report_interval_s	number or null	no	Mean time between those reports.
reports	integer	no	Position reports during the step.; min 0.0; default 0
skipped	boolean	no	Not driven: the forward distance budget was used up (room ahead).; default false
turned_deg	number	no	Heading change during the step.; default 0.0
window_s	number or null	no	Length of the steady window the value was measured over (the step without its settling time at the start).

DriveSpeedSetting

The vendor's speed setting for manual driving, as far as the connection can change it (MowerCapabilities.drive_speed_setting): the accepted range and step in m/s.

Field	Type	Required	Notes
max_mps	number	yes	max 5.0; greater than 0.0
min_mps	number	yes	max 5.0; greater than 0.0
step_mps	number	no	max 1.0; greater than 0.0; default 0.1

ErrorExplanation

A vendor code in plain words, in one locale.

Field	Type	Required	Notes
category	MowerErrorCategory	yes
cause	string or null	no
code	string	yes	min length 1; max length 64
description	string	no	max length 2000; default ""
known	boolean	yes	The lexicon knows the code.
links	array of ErrorLink	no
locale	string	yes	The locale of the texts (after fallback).; pattern ^[a-z]{2}$
severity	ErrorSeverity	yes
steps	array of string	no
title	string	yes	max length 200
user_action	boolean	yes
vendor	string or null	no	The lexicon that explained the code; null when none applied.
vendor_name	string or null	no
verified	boolean	no	False for an entry whose meaning is not verified.; default true

ErrorExplanationList

Explanations in the order of the requested codes.

Field	Type	Required	Notes
explanations	array of ErrorExplanation	yes

ErrorLexiconInfo

Summary of an installed lexicon (no entries).

Field	Type	Required	Notes
cloud_providers	array of string	no	The cloud providers it serves (empty: vendor).
connection_kinds	array of ConnectionKind	no
entries	integer	yes	Number of codes.; min 0.0
locales	array of string	no
source	string or null	no
unverified	integer	yes	Codes whose meaning could not be verified.; min 0.0
vendor	string	yes	pattern ^[a-z][a-z0-9_]{0,31}$
vendor_name	string	yes

ErrorLexiconList

The installed error lexicons, one per vendor.

Field	Type	Required	Notes
lexicons	array of ErrorLexiconInfo	yes

ErrorLexiconSearchReply

A page of a lexicon's entries, ordered by code (numbers numerically).

Field	Type	Required	Notes
categories	map of integer	no	Entries per category in the whole lexicon (for filter chips).
entries	array of ErrorExplanation	no
lexicon	ErrorLexiconInfo or null	no	The lexicon searched; null when none applies (or none answered).
offset	integer	no	min 0.0; default 0
severities	map of integer	no	Entries per severity in the whole lexicon.
total	integer	no	Entries matching the filters.; min 0.0; default 0

ErrorLink

Further reading for an entry (the vendor's help page, a manual chapter).

Field	Type	Required	Notes
label	string	yes	min length 1; max length 120
url	string	yes	max length 500; pattern ^https://

ErrorSeverity

How bad an error is for the user, manufacturer neutral.

Type: "info" | "warning" | "error" | "critical"

FirmwareInfo

The firmware state of a mower (MowerState.firmware_info).

Field	Type	Required	Notes
available	string or null	no	The newest version the vendor offers for this mower; null when none or unknown.
checked_at	string (date-time) or null	no	When the vendor was last asked; null when never.
failure_reason	string or null	no	Why the last update failed, if known.
installed	string or null	no	The version running on the mower.
progress	integer or null	no	Percent done while installing, if reported.
release_notes	string or null	no	Release notes of available, if given.
update_state	"idle" | "available" | "installing" | "failed" | "unknown"	no	default "unknown"

GeoPosition

A WGS84 position.

Field	Type	Required	Notes
alt	number or null	no	Altitude in metres, if known.
heading	number or null	no	Heading in degrees, 0 = north, clockwise.
lat	number	yes	Latitude in degrees.; min -90.0; max 90.0
lon	number	yes	Longitude in degrees.; min -180.0; max 180.0

GeoReference

Anchors the local frame on the earth.

The local point (0, 0) is at (origin_lat, origin_lon). The local axes are the east and north axes rotated counter-clockwise by rotation_deg: a local point (x, y) lies east = x cos(r) - y sin(r) and north = x sin(r) + y cos(r) metres from the origin.

Field	Type	Required	Notes
origin_lat	number	yes	min -90.0; max 90.0
origin_lon	number	yes	min -180.0; max 180.0
rotation_deg	number	no	min -360.0; max 360.0; default 0.0

GnssSolution

The satellite position solution as the receiver reports it (finer than :class:~mowdeck_contracts.v1.RtkFixStatus, which folds single into none).

Type: "none" | "single" | "float" | "fixed" | "unknown"

GnssStatus

The mower's satellite positioning (MowerState.gnss).

Field	Type	Required	Notes
correction_age_s	number or null	no	Age of the last RTK correction data in seconds; null without corrections.
rtk_status	GnssSolution	no	The position solution of the receiver.; default "unknown"
satellites	integer or null	no	Satellites the receiver uses.

HealthDaily

Day totals of an inclusive range of UTC days, oldest first (days without data absent).

Field	Type	Required	Notes
days	array of HealthDayOut	yes
from	string (date)	yes
mower_id	string (uuid)	yes
to	string (date)	yes

HealthDayOut

Totals of one UTC day (battery_cycles is MowDeck's own count).

Field	Type	Required	Notes
battery_cycles	integer	yes
blade_hours	number	yes
charge_sessions	integer	yes
day	string (date)	yes
distance_m	number	yes
errors	map of integer	yes
jobs	integer	no	Jobs started: transitions into mowing (not from paused).; default 0
mowing_hours	number	yes
online_hours	number	no	Time with states arriving and the mower not offline.; default 0.0

HeatmapCellOut

One cell of a heatmap: integer indexes in the map's local frame (floor(metres / cell_m)), the value and the number of samples in it.

Field	Type	Required	Notes
n	integer	yes	Samples located in the cell.
value	number	yes	Cut share or fixed share (0..1), or median dBm.
x	integer	yes
y	integer	yes

HeatmapGapOut

A piece of the map's areas the blades missed (local metres, implicit closing edge).

Field	Type	Required	Notes
area_m2	number	yes
polygon	array of array of any	yes

HeatmapLegendOut

How to colour the values: ratio and fix span 0..1, dbm the response's range (null without cells).

Field	Type	Required	Notes
kind	"ratio" | "fix" | "dbm"	yes
max	number or null	yes
min	number or null	yes

HistoryPointOut

One bin (or one row) of the history.

Field	Type	Required	Notes
activity	string	yes
at	string (date-time)	yes
battery_max	integer	yes
battery_min	integer	yes
battery_percent	integer	yes
charging	boolean	yes
error_code	string or null	yes
lat	number or null	yes
lon	number or null	yes
rtk_fix	string	yes
samples	integer	yes

HTTPValidationError

Field	Type	Required	Notes
detail	array of ValidationError	no

JobProgress

The mowing job the mower runs right now (MowerState.job).

Null on the state when no job runs or the connection reports none. Times have the resolution the vendor reports (Mammotion: whole minutes, given here in seconds).

Field	Type	Required	Notes
area_id	string or null	no	The map area (MowerMap.areas[].id) the mower works in now; null when it is not one of the mower's map areas or not reported.
elapsed_s	integer or null	no	Seconds the job has run so far.
mowed_m2	number or null	no	Area mowed in this job so far, in square metres.
progress_percent	integer or null	no	Share of the job done, 0 to 100.
remaining_s	integer or null	no	Seconds the mower estimates the job still needs.

Layer

What a heatmap shows.

Type: "coverage" | "rtk" | "wifi" | "mnet"

LinkStatus

The state of one additional link as the Device-Gateway reports it in MowerState.links.

Field	Type	Required	Notes
compiled_at	string or null	no	When the bridge firmware was compiled, as ESPHome reports it (free text).
connected	boolean	no	The link is open right now.; default false
esphome_version	string or null	no	Firmware version of the bridge (the ESPHome release it runs).
outdated	boolean	no	The bridge firmware is older than what MowDeck expects; see outdated_reason.; default false
outdated_reason	string or null	no	Why the firmware counts as outdated, e.g. esphome_version, project_version or no_project; null when up to date.
project_version	string or null	no	Version of the MowDeck bridge template the firmware was built from; null when the firmware carries no esphome.project.
rssi	integer or null	no	Signal strength of the mower at the bridge in dBm, if the bridge reports it.
since	string (date-time) or null	no	When the link was opened (or lost), if known.

MapArea

A mowable area (a "zone" in the Mammotion app).

Field	Type	Required	Notes
boundary	array of array of any	yes	min items 3
id	string	yes	Stable id, e.g. the vendor's zone hash.; min length 1; max length 128
name	string or null	no

MapLayerOut

A base map layer offered under the track: map (street map) or aerial (photo). Tiles come from /mowers/{id}/tracking/map/{layer}/{z}/{x}/{y} (owner) or POST /public/tracking/tile (share link), only around the tracked positions.

Field	Type	Required	Notes
attribution	string	yes	Credit line to show while the layer is visible.
coverage	AerialBounds or null	no	The box the source has data in (null: the whole world). Tiles are served only where it overlaps the tracked positions plus margin_m.
covers_last	boolean	no	Whether the source has data at the last known position (false: show another layer; e.g. an aerial photo of one state only).; default true
id	"map" | "aerial"	yes
margin_m	number	no	Metres around the tracked positions where tiles are served; the map keeps its view inside that box (0: no limit known).; default 0
max_zoom	integer	yes	Highest zoom with real detail; deeper zooms scale it.
min_zoom	integer	yes

MapPath

A transfer path between areas (driven with blades off).

Field	Type	Required	Notes
id	string	yes	min length 1; max length 128
name	string or null	no
points	array of array of any	yes	min items 2

MapZone

A polygon the mower must stay out of: a no-go zone or an obstacle.

Field	Type	Required	Notes
boundary	array of array of any	yes	min items 3
id	string	yes	min length 1; max length 128
name	string or null	no

MowerActivity

What the mower is doing right now.

Type: "idle" | "mowing" | "paused" | "returning" | "docked" | "charging" | "error" | "offline" | "updating" | "unknown"

MowerCapabilities

Feature flags and limits of one mower behind one connection.

All fields default to "not supported", so an adapter only declares what it really offers.

Field	Type	Required	Notes
base_station_firmware_update	boolean	no	The connection can ask the manufacturer's firmware service for the linked RTK base station and install its updates (firmware_check with target base_station, base_station_firmware_update; ADR 0047).; default false
blade_height_range_mm	array of any or null	no	Inclusive (min, max) blade height in millimetres, if settable.
camera	CameraAccess	no	default "none"
connection_kinds	array of ConnectionKind	no	Connection kinds this mower can use.
custom_paths	boolean	no	The mower can follow an arbitrary path or boundary.; default false
cutting_width_mm	integer or null	no	Width of the cut swath in millimetres, if known (coverage heatmaps).
dock_keeps_job	boolean	no	ReturnToDock with end_job: false keeps the running job paused, so a later ResumeMow continues it. Without it a client offers no 'keep the job' choice and the controller refuses end_job: false; the mower ends (or forgets) its job on the way home.; default false
drive_reverse	boolean	no	The drive link that carries the joystick frames can drive backwards (a negative ManualDrive.linear). Without it the web joystick offers no reverse and a spot run's multi_point turns fall back to arc (ADR 0043).; default false
drive_speed_setting	DriveSpeedSetting or null	no	The vendor's speed setting for manual driving can be read (MowerState.drive_speed_mps) and changed (set_drive_speed) within this range; null when the connection cannot (ADR 0042).
firmware_update	boolean	no	The connection can ask the manufacturer's firmware service for updates and install them (firmware_check, firmware_update).; default false
light	boolean	no	The mower's light (e.g. the camera's headlamp) can be switched with set_light.; default false
links_supported	array of string	no	Additional link kinds this connection can open next to its primary one (e.g. ble_bridge); empty when the mower has only its primary connection.; max items 8
maintenance	array of "restart_mower" | "sync_map" | "relocate_dock" | "leave_dock" | "resync_rtk"	no	Maintenance commands this connection can send (ADR 0048): restart_mower, sync_map, relocate_dock, leave_dock (only together with undock), resync_rtk. Clients offer only these; empty when the connection has none.
manual_drive	boolean	no	Joystick driving is supported.; default false
manual_drive_blades	boolean	no	Blades may run during manual driving when a frame explicitly asks for it.; default false
max_speed_mps	number or null	no	Highest settable driving speed while mowing.
min_speed_mps	number or null	no	Lowest settable driving speed while mowing, if the model has one.
model	string or null	no	Mower model, if known.
native_patterns	array of string	no	Mowing pattern names the mower runs natively on its own map areas, for example stripes, diagonal, checkerboard, edge_only.
path_spacing_range_mm	array of any or null	no	Inclusive (min, max) distance between neighbouring mowing paths in millimetres (MowPattern.spacing_m), if the model has a settable spacing.
rtk_sources	array of RtkSource	no	RTK correction sources the mower can report.
settings	array of SettingSpec	no	The mower's own settings this connection can read and change with set_setting (ADR 0046), each with its type and range or options; current values in MowerState.settings. Empty when the connection offers none.; max items 32
start_options	StartOptions	no	Job options a native start may carry besides the pattern (obstacle detection, laps around no-go zones, path order, start progress; ADR 0030). Clients show only what is declared here.
start_plans	array of StartPlan	no	Starts the mower offers without map areas (ADR 0066 amendment), in the order a client lists them; each is sent as StartMow.plan_ref. Empty for mowers that start on their map areas.; max items 16
undock	boolean	no	The connection can make the mower leave its charging station by itself (leave_dock), so a spot run may start from the dock (ADR 0041).; default false

MowerCapabilitiesList

Stored capabilities of every mower the caller can view (those that reported any).

Field	Type	Required	Notes
items	array of MowerCapabilitiesOut	yes
truncated	boolean	yes	True when more mowers exist than the configured limit.

MowerCapabilitiesOut

What the mower can do over its current connection (blade height range, speed, ...).

Field	Type	Required	Notes
capabilities	MowerCapabilities	yes
mower_id	string (uuid)	yes
observed_at	string (date-time)	yes	When the gateway read the capabilities (UTC).
received_at	string (date-time)	yes	When Telemetry stored them (UTC).

MowerErrorCategory

What kind of fault MowerState.error_code names, manufacturer neutral.

The same words classify the entries of an error lexicon (ADR 0067), so rules such as the theft alarm can match a category instead of vendor codes.

Type: "trapped" | "obstacle" | "outside" | "wheel_slip" | "lift_tilt" | "collision" | "battery" | "blade_motor" | "rain" | "positioning" | "communication" | "docking" | "firmware" | "other"

MowerErrorOut

GET /mowers/{id}/error: the mower's current error in plain words.

Field	Type	Required	Notes
activity	string	yes	MowerActivity of the state.
error	ErrorExplanation or null	yes	The current error explained; null while the mower reports none.
mower_id	string (uuid)	yes
observed_at	string (date-time)	yes	When the mower reported the state.

MowerHealthOut

Running health totals of a mower (since the first state Telemetry received).

Field	Type	Required	Notes
battery_cycles	integer	yes	Battery charge cycles to show: the mower's own lifetime counter when it reports one (battery_cycles_source device), else MowDeck's count (battery_cycles_tracked).
battery_cycles_source	"device" | "telemetry"	yes	Where battery_cycles comes from: the mower's own counter (device) or MowDeck's count (telemetry, battery_cycles_tracked).
battery_cycles_tracked	integer	yes	MowDeck's own count since the first state it received: discharges below 20 % followed by a charge above 80 %.
blade_changed_at	string (date-time) or null	yes	The last recorded blade change.
blade_hours	number	yes	Hours with running blades (heuristic, see README).
blade_hours_since_change	number	yes
blade_hours_threshold	number	yes	MowDeck's threshold: the one set for the mower in MowDeck, else the installation's default. The reminder uses blade_hours_threshold_effective.
blade_hours_threshold_custom	boolean	no	The mower has its own threshold (PUT .../health/blade-threshold); false: the mower's own warning or the default applies.; default false
blade_hours_threshold_effective	number	yes	The one threshold in effect, used by the reminder and to show: the threshold set in MowDeck (source custom), else the mower's own warning while it reports its own blade counter (device), else the installation's default (default).
blade_hours_threshold_source	"custom" | "device" | "default"	yes	Where blade_hours_threshold_effective comes from.
blade_source	"device" | "telemetry"	yes	Which blade counter to show as hours since the blade change: the mower's own (device) or MowDeck's (telemetry, blade_hours_since_change).
charge_sessions	integer	yes
device_battery_cycles	integer or null	yes	The mower's own lifetime battery cycle counter; null when the mower does not report one.
device_blade_hours	number or null	yes	The mower's own blade counter in hours (reset in the vendor app), as the vendor app shows it; null when the mower does not report one.
device_blade_warn_hours	number or null	yes	The mower's own blade warning threshold in hours; null when not reported.
device_distance_m	number or null	no	The mower's own lifetime distance in metres, as the vendor app shows it; null when the mower does not report one.
device_mowing_hours	number or null	no	The mower's own lifetime working time in hours, as the vendor app shows it; null when the mower does not report one.
distance_m	number	yes	MowDeck's own distance in metres since since.
errors	map of integer	yes	Error count per error code (unknown: none).
mower_id	string (uuid)	yes
mowing_hours	number	yes	MowDeck's own count of hours with activity mowing since since.
since	string (date-time) or null	yes	observed_at of the first state counted; null after a blade reset before any telemetry.
updated_at	string (date-time)	yes

MowerHeatmap

A heatmap layer of a mower over its map's local frame.

Field	Type	Required	Notes
cell_m	number	yes	Cell size in metres; larger than requested when the cells were coarsened to stay within 20 000.
cells	array of HeatmapCellOut	yes
from	string (date-time)	yes
gaps	array of HeatmapGapOut	yes	Missed map areas (coverage only).
layer	"coverage" | "rtk" | "wifi" | "mnet"	yes
legend	HeatmapLegendOut	yes
mower_id	string (uuid)	yes
reference	GeoReference	yes	Geo reference of the map's local frame.
samples	integer	yes	Track rows that contributed to the layer.
to	string (date-time)	yes
truncated	boolean	yes	True when the row limit cut off older positions.

MowerMap

The map of one mower: areas, no-go zones, obstacles, paths and the dock.

Field	Type	Required	Notes
areas	array of MapArea	no
dock	DockPose or null	no
no_go_zones	array of MapZone	no
obstacles	array of MapZone	no
paths	array of MapPath	no
reference	GeoReference	yes
revision	string or null	no	Map version, e.g. the vendor's map hash.

MowerMapOut

The map of a mower as the Device-Gateway last read it (local metres plus reference).

Field	Type	Required	Notes
map	MowerMap	yes
mower_id	string (uuid)	yes
observed_at	string (date-time)	yes	When the gateway read the map (UTC).
received_at	string (date-time)	yes	When Telemetry stored it (UTC).
revision	string	yes	Map revision or content hash; also the ETag.

MowerState

A telemetry snapshot of one mower, published on telemetry.mower.<id>.

Two times: observed_at is when the mower reported the values, heartbeat_at when the gateway's link to it was last alive. A docked mower reports rarely, so old values do not mean an offline mower (ADR 0040).

Field	Type	Required	Notes
account_id	string (uuid)	yes
activity	MowerActivity	yes
base_station	BaseStationState or null	no	The RTK base station the mower is linked to in Fleet, as the mower's connection sees it (correction link, satellites, position, firmware; ADR 0047); null for a mower without a linked base station.
battery_percent	integer	yes	min 0.0; max 100.0
blade_height_mm	integer or null	no
charging	boolean	no	default false
cloud_provider	string or null	no	With connection cloud: the cloud provider (ADR 0066) of the mower's linked account, so consumers pick the vendor's error lexicon (ADR 0067) when several providers share the kind. Set by the Device-Gateway, never by an adapter; null for other kinds and in states from before the field.
connected	boolean	no	False in the state the Device-Gateway publishes right after its connection to the mower ended: the last known values, with heartbeat_at the last time the link was alive. Set by the gateway, never by an adapter.; default true
connection	ConnectionKind	yes
drive_calibration	DriveCalibrationStatus or null	no	The drive calibration MowDeck runs on this mower (DriveCalibrate, ADR 0042), with its final state and result kept until the next one; null when there never was one.
drive_recoverable	boolean	no	With activity error: the error is not a safety sensor stop, so manual driving may free the mower (stuck, wheel slip). Lift, tilt and collision stops are never drive recoverable; the controller refuses drive frames for them.; default false
drive_speed_mps	number or null	no	The vendor's speed setting for manual driving (MowerCapabilities.drive_speed_setting); null when the connection has none or has not read it yet.
error_category	MowerErrorCategory or null	no	With activity error: the manufacturer-neutral kind of the fault; null otherwise or when the connection cannot tell.
error_code	string or null	no
error_message	string or null	no
firmware	string or null	no
firmware_info	FirmwareInfo or null	no	Installed and available firmware and the update state; null when the adapter has not checked (or cannot check) the vendor.
gnss	GnssStatus or null	no	Satellite positioning details (satellites, RTK correction age, solution); null when the connection does not report them.
heartbeat_at	string (date-time) or null	no	When the Device-Gateway last knew its connection to the mower alive (UTC). The gateway sets it on every publish, never an adapter: it advances with each heartbeat while observed_at stays the time of the mower's last report. Clients judge online and offline by it (ADR 0040); null in states from before the field, then observed_at stands in.
job	JobProgress or null	no	The mowing job the mower runs (progress, current area, elapsed and remaining seconds, mowed square metres); null when none runs or the connection does not report it.
light_on	boolean or null	no	Whether the mower's light (the camera's headlamp) is on, as the mower reports it; null when not reported (no light, or no answer yet).
links	map of LinkStatus	no	State of the mower's additional links by kind (e.g. ble_bridge); empty for a mower with only its primary connection.
mower_id	string (uuid)	yes
observed_at	string (date-time)	yes	When the device reported this state (UTC).
position	GeoPosition or null	no
position_source	PositionSource	no	Where position comes from; unknown whenever position is null.; default "unknown"
rain_detected	boolean or null	no	The mower's own rain sensor reports rain right now; null when the connection does not report the sensor (ADR 0046).
raw	object	no	Adapter specific extras. Consumers must not rely on its structure; the typed fields above replace the keys they cover.
rtk_fix	RtkFixStatus	no	default "unknown"
rtk_source	RtkSource	no	default "unknown"
self_check	SelfCheck or null	no	The mower's start self-check (ok or blocked with the reason); null when the connection does not report it.
settings	object	no	Current values of the mower's own settings (ADR 0046) by key, as the mower reported them; a declared setting the mower has not reported yet is missing. Types, ranges and options: MowerCapabilities.settings.
signal	SignalStatus or null	no	The mower's own Wi-Fi and mobile signal in dBm and its uplink; null when the connection does not report them.
speed_mps	number or null	no
spot_run	SpotRunStatus or null	no	The spot run MowDeck drives on this mower right now (SpotMow), with its final state kept until the next run; null when there never was one.
turn_style	TurnStyle or null	no	How the mower turns at lane ends in its own jobs, as its connection reports the vendor setting (read only; ADR 0043). A spot run without its own turn_style uses it; null when the connection does not report one.

MowerStateList

Latest states of every mower the caller can view.

Field	Type	Required	Notes
items	array of MowerStateSnapshot	yes
truncated	boolean	yes	True when more mowers exist than the configured limit.

MowerStateSnapshot

The latest state of a mower.

Field	Type	Required	Notes
mower_id	string (uuid)	yes
received_at	string (date-time)	yes	When Telemetry stored this state (UTC).
stale	boolean	yes	True when the mower is offline: the gateway reported its link lost (state.connected false) or the last link heartbeat (state.heartbeat_at, else observed_at) is older than the stale threshold. Old values of a connected mower are not stale (ADR 0040).
state	MowerState	yes

MowPath

The route a mower planned, in the local metres of its map.

Field	Type	Required	Notes
area_ids	array of string	no	The map areas the route covers, in order.
kinds	array of "mow" | "edge" | "transfer" | "other" or null	no	The kind of every polyline (same length), when known.
path_hash	string	yes	The vendor's id of the planned route.; min length 1; max length 32
planned_at	string (date-time)	yes	When MowDeck received the route (UTC).
points_total	integer	yes	Number of points over all polylines.; min 0.0
polylines	array of array of array of any	no	The route as polylines in driving order.
progress	MowPathProgress or null	no	Progress of the running job; None for a preview.

MowPathOut

The route the mower planned for its running job, with the progress along it.

Field	Type	Required	Notes
mower_id	string (uuid)	yes
observed_at	string (date-time)	yes	When the gateway read the path (UTC).
path	MowPath	yes
received_at	string (date-time)	yes	When Telemetry stored it (UTC).

MowPathProgress

Where the mower is along its path.

Field	Type	Required	Notes
direction	integer	no	The vendor's traversal direction flag (0 or 1).; min 0.0; max 255.0; default 0
index	integer	yes	Points done so far, counted over all polylines in order: the points with a flat index below this value are mowed.; min 0.0

NetworkKind

How the mower itself reaches the internet (its own uplink, not MowDeck's connection to it, which is MowerState.connection).

Type: "wifi" | "mobile" | "ble" | "none"

ObstacleDetection

How eagerly the mower avoids obstacles during a native job (MowPattern).

Which modes a mower offers depends on its model and firmware (MowerCapabilities.start_options.obstacle_detection). The names follow the vendor apps: off is the plain bump-and-turn behaviour, standard avoids obstacles it sees ahead, sensitive additionally avoids areas that are not lawn; slow_touch and less_touch exist only on older firmware.

Type: "off" | "slow_touch" | "less_touch" | "standard" | "sensitive"

PathOrder

Whether the border laps run before or after the fill of a native job.

Type: "border_first" | "grid_first"

PositionOut

One point of the position track.

Field	Type	Required	Notes
alt	number or null	yes
heading	number or null	yes
lat	number	yes
lon	number	yes
observed_at	string (date-time)	yes
rtk_fix	string	yes
rtk_source	string	yes

PositionSource

Where :attr:MowerState.position comes from, so consumers can judge it.

rtk is the mower's own positioning with an RTK fix (fixed or float), gnss the same positioning without an RTK fix (single point, metres of scatter), dock the known pose of the charging station while the mower stands in it (the adapter reports the dock instead of the scattering raw position), unknown when there is no position or its quality is not known.

Type: "rtk" | "gnss" | "dock" | "unknown"

PositionTrack

Position track of a mower in a time range, oldest first.

Field	Type	Required	Notes
from	string (date-time)	yes
mower_id	string (uuid)	yes
positions	array of PositionOut	yes
to	string (date-time)	yes
truncated	boolean	yes

PresenceOut

Where the mower is: in a zone (zone_id) or in none.

Field	Type	Required	Notes
observed_at	string (date-time)	yes	The report the evaluation is based on.
since	string (date-time)	yes	When it entered this zone (or left the last one).
zone_id	string (uuid) or null	yes	The current zone; null outside every zone.
zone_name	string or null	no

PublicTileIn

Body of a public base map tile: the share token and the tile (in the body, so neither the token nor the place reaches an access log).

Field	Type	Required	Notes
layer	"map" | "aerial"	yes
token	string	yes	min length 1; max length 200
x	integer	yes	min 0.0
y	integer	yes	min 0.0
z	integer	yes	min 0.0; max 24.0

PublicTrackIn

Body of the public view.

Field	Type	Required	Notes
token	string	yes	min length 1; max length 200

PublicTrackOut

What a share link shows: nothing else.

Field	Type	Required	Notes
active	boolean	yes
ended_at	string (date-time) or null	no
expires_at	string (date-time)	yes
last	TrackPointOut or null	no
map_layers	array of MapLayerOut	no
mower_model	string or null	no
mower_name	string	yes
server_time	string (date-time)	yes
stale_since	string (date-time) or null	no
started_at	string (date-time)	yes
track	array of TrackPointOut	yes

ReportMowerOut

The day totals of one mower in a report (days without data are absent).

Field	Type	Required	Notes
days	array of HealthDayOut	yes
mower_id	string (uuid)	yes

ReportSummary

GET /reports/summary: day totals of every visible mower with data in the range.

Field	Type	Required	Notes
from	string (date)	yes
items	array of ReportMowerOut	yes
to	string (date)	yes
truncated	boolean	yes	More rows than one report returns; narrow the range.

RtkCorrectionLink

How the RTK corrections reach the mower.

Type: "lora" | "internet" | "network" | "unknown"

RtkFixStatus

Quality of the RTK position fix.

Type: "none" | "float" | "fixed" | "unknown"

RtkSource

Where RTK correction data comes from.

Type: "base_station" | "network" | "unknown"

SelfCheck

The mower's start self-check (MowerState.self_check).

Field	Type	Required	Notes
detail	string or null	no	With blocked: what stops the mower as a lower-case key, e.g. rain, lifted, low_battery, outside_task_area, non_working_hours, rtk_not_ready; the adapter's documentation lists its keys. Null with ok.
result	SelfCheckResult	yes

SelfCheckResult

Outcome of the mower's start self-check.

Type: "ok" | "blocked"

SettingGroup

Where a client shows a setting.

Type: "weather" | "battery" | "lights" | "driving" | "mowing" | "safety" | "voice" | "schedule"

SettingSpec

One setting a mower has, as its connection declares it (MowerCapabilities.settings).

Field	Type	Required	Notes
group	SettingGroup	yes
key	string	yes	Manufacturer-neutral key, one of the known keys.; pattern ^[a-z][a-z0-9_]{0,47}$
max	integer or null	no	Largest value of an int setting.
min	integer or null	no	Smallest value of an int setting.
options	array of string	no	The options of an enum setting, in the order a client offers them.; max items 16
step	integer or null	no	Grid of an int setting, counted from min.
type	SettingType	yes
unit	string or null	no	Unit of an int setting, e.g. % or h.

SettingType

The type of a setting's value.

Type: "bool" | "int" | "enum" | "time_window"

SignalStatus

The mower's own radio signal (MowerState.signal).

Field	Type	Required	Notes
mobile_dbm	integer or null	no	Mobile network (LTE) signal in dBm; null when not reported.
network	NetworkKind or null	no	The uplink the mower uses now; null when not reported.
wifi_dbm	integer or null	no	Wi-Fi signal in dBm; null when not reported.

SpotRunStatus

Progress of the spot run MowDeck drives on this mower (MowerState.spot_run).

Field	Type	Required	Notes
driven_points	integer	no	Points reached so far.; min 0.0; default 0
dry_run	boolean	no	The blades stayed off for the whole run (the default).; default true
planned_points	integer	no	Points of the plan in total.; min 0.0; default 0
progress_percent	integer	no	min 0.0; max 100.0; default 0
reason	string or null	no	Why the run ended early or paused, if so.
run_id	string (uuid)	yes
segment_index	integer	no	The segment being driven (0-based).; min 0.0; default 0
segments_total	integer	no	min 0.0; default 0
state	"preparing" | "undocking" | "waiting_rtk" | "transit" | "spot_mowing" | "paused_rtk" | "returning" | "stopping" | "done" | "aborted" | "failed"	yes

StartOptions

The job options a native start may carry besides the pattern (MowPattern), as one mower declares them (ADR 0030 amendment of 2026-10-24).

Everything defaults to "not offered": a client shows an option only when it is declared here, and the connection refuses a start that sets an option it does not declare. An option a start leaves out (None) is not sent, so the mower keeps its own default.

Field	Type	Required	Notes
obstacle_detection	array of ObstacleDetection	no	Obstacle detection modes the mower offers, in the order a client shows them (MowPattern.obstacle_detection); empty when it offers no choice.; max items 8
obstacle_laps_range	array of any or null	no	Inclusive (min, max) laps around each no-go zone (MowPattern.obstacle_laps), if settable.
orders	array of PathOrder	no	Path orders the mower offers (MowPattern.order); empty when it offers no choice.; max items 2
start_progress_range_pct	array of any or null	no	Inclusive (min, max) progress in percent a job may start at (MowPattern.start_progress_pct), if settable.

StartPlan

One way to start a mower that has no map areas to choose (ADR 0066 amendment).

A mower whose connection knows no area geometry (its vendor keeps the garden to itself) cannot be started by tapping areas. Its connection declares the starts it offers instead; a client sends StartMow {plan_ref: ref} for the one the user picks and labels it by kind (plus name for a zone).

Field	Type	Required	Notes
kind	StartPlanKind	yes
name	string or null	no	The mower's own name of a zone, shown as is; null for the other kinds.
ref	string	yes	Sent as StartMow.plan_ref to start this.; pattern ^[a-z][a-z0-9_]{0,31}(:[A-Za-z0-9_.-]{1,64})?$

StartPlanKind

What a start plan does, so a client can label it without knowing the vendor.

Type: "now" | "zone" | "edge" | "schedule"

StateHistory

History of a mower in a time range.

Field	Type	Required	Notes
from	string (date-time)	yes
mower_id	string (uuid)	yes
points	array of HistoryPointOut	yes
step_seconds	number or null	yes	Bin width, null for raw rows.
to	string (date-time)	yes
truncated	boolean	yes

TimeWindow

A daily window in the mower's local time, HH:MM on a 24-hour clock. end before start crosses midnight (22:00 to 06:00).

Field	Type	Required	Notes
end	string	yes	End, HH:MM (24-hour clock).; pattern `^([01]\d
start	string	yes	Start, HH:MM (24-hour clock).; pattern `^([01]\d

TrackingLinkCreated

A new share link. token is shown only here; the page address is <app>/track#<token>.

Field	Type	Required	Notes
link	TrackingLinkOut	yes
token	string	yes

TrackingLinkIn

Body of a link request.

Field	Type	Required	Notes
hours	number or null	no	Lifetime; at most the server's limit (48 h).
session_id	string (uuid) or null	no

TrackingLinkOut

A share link (never its token).

Field	Type	Required	Notes
active	boolean	yes
created_at	string (date-time)	yes
expires_at	string (date-time)	yes
id	string (uuid)	yes
last_used_at	string (date-time) or null	no
revoked_at	string (date-time) or null	no
session_id	string (uuid)	yes
uses	integer	yes

TrackingSessionOut

A theft tracking session.

Field	Type	Required	Notes
active	boolean	yes
end_reason	"false_alarm" | "stopped" | "max_duration" or null	no
ended_at	string (date-time) or null	no
ends_at	string (date-time)	yes	The automatic end (maximum duration).
id	string (uuid)	yes
interval_seconds	number	yes
last	TrackPointOut or null	no	Newest position seen by the background tick.
mower_id	string (uuid)	yes
mower_model	string or null	no
mower_name	string	yes
mower_serial	string or null	no
points	integer	yes	Positions recorded; final once the session ended.
stale_since	string (date-time) or null	no	Set while the mower has not reported for a while.
started_at	string (date-time)	yes
trigger	"mower_lifted" | "mower_left_dock_unexpectedly" | "geofence_exit" | "manual"	yes

TrackingStatus

The tracking view of a mower: the session, its track and its links.

Field	Type	Required	Notes
links	array of TrackingLinkOut	no
map_layers	array of MapLayerOut	no	Base map layers under the track; empty without any.
photos	integer	no	default 0
server_time	string (date-time)	yes
session	TrackingSessionOut or null	yes	The active session, else the newest one; null when the mower never had one.
track	array of TrackPointOut	no
truncated	boolean	no	default false

TrackingStopIn

Body of the stop request.

Field	Type	Required	Notes
reason	"false_alarm" | "stopped"	no	default "stopped"

TrackPointOut

One position of a track.

Field	Type	Required	Notes
at	string (date-time)	yes
lat	number	yes
lon	number	yes

TurnStyle

How a spot run turns at the end of a lane (ADR 0043).

in_place: the mower rotates on the spot (fast, but an all-wheel-drive mower scuffs the turf). arc: a forward U-turn with a radius of at least half the lane spacing, or a bulb turn over the neighbouring lane when the spacing is narrower than the turning radius. multi_point: a three-point turn (forward arc, reverse arc with the blades off, forward arc); needs a drive link that can reverse (MowerCapabilities.drive_reverse).

Type: "in_place" | "arc" | "multi_point"

ValidationError

Field	Type	Required	Notes
ctx	object	no
input	any	no
loc	array of string or integer	yes
msg	string	yes
type	string	yes

WidgetJobOut

The running job as the iOS widgets and the Live Activity show it.

Field	Type	Required	Notes
area_id	string or null	yes
area_name	string or null	yes	Name of the map area, when the map names it.
elapsed_s	integer or null	yes
mowed_m2	number or null	yes
progress_percent	integer or null	yes
remaining_s	integer or null	yes

WidgetStateOut

GET /mowers/{id}/widget: a compact state (ADR 0059).

Field	Type	Required	Notes
activity	string	yes	MowerActivity; offline replaces the activity while the state is stale.
battery_percent	integer	yes
charging	boolean	yes
error_category	string or null	no	With activity error: the manufacturer-neutral MowerErrorCategory.
error_code	string or null	yes
error_message	string or null	yes
error_severity	string or null	no	With activity error: info, warning, error or critical.
error_title	string or null	no	With activity error: the error in plain words from the vendor's error lexicon in the requested locale (ADR 0067); for a code no lexicon knows the generic title of its category; null when neither is known (show error_message).
job	WidgetJobOut or null	yes
mower_id	string (uuid)	yes
observed_at	string (date-time)	yes
rain_detected	boolean or null	yes
stale	boolean	yes	The mower is offline (see MowerStateSnapshot.stale).

ZoneDayOut

Time in a zone on one UTC day.

Field	Type	Required	Notes
day	string (date)	yes
mowing_seconds	number	yes
seconds	number	yes

ZoneIn

A new zone.

Field	Type	Required	Notes
name	string	yes	min length 1; max length 200
ring	array of array of number	yes	Corners as [lat, lon] (WGS84 degrees), open or closed; edges must not cross.; min items 3; max items 65
start_plan_ref	string or null	no

ZoneLimits

The validation limits, so a client can check a drawing before it is sent.

Field	Type	Required	Notes
max_anchor_distance_m	number	no	default 1000.0
max_area_m2	number	no	default 100000.0
max_corners	integer	no	default 64
max_extent_m	number	no	default 1000.0
max_name_length	integer	no	default 60
max_zones	integer	no	default 32
min_area_m2	number	no	default 1.0
min_corners	integer	no	default 3

ZoneOut

One virtual zone.

Field	Type	Required	Notes
area_m2	number	yes
created_at	string (date-time)	yes
id	string (uuid)	yes
name	string	yes
ring	array of array of number	yes	Corners as [lat, lon], open ring.
start_plan_ref	string or null	no	The vendor zone start (StartPlan of kind zone) this zone is linked to; send it as StartMow.plan_ref to start the mower there.
updated_at	string (date-time)	yes

ZonePatch

Changes to a zone; fields left out stay as they are.

Field	Type	Required	Notes
name	string or null	no
ring	array of array of number or null	no
start_plan_ref	string or null	no	Link the zone to this vendor zone start.
unlink_start_plan	boolean	no	Remove the link to a start.; default false

ZonePlanOut

A vendor zone start a zone can be linked to.

Field	Type	Required	Notes
name	string or null	no
ref	string	yes

ZonesOut

The zones of a mower and whether the editor is offered.

Field	Type	Required	Notes
anchor	AnchorOut or null	no
availability	"available" | "vendor_map" | "no_position"	yes	available: the vendor shares no map areas and the mower reports positions; vendor_map: its vendor's areas are its zones; no_position: it reports no position.
limits	ZoneLimits	no
presence	PresenceOut or null	no	The current zone; null before the first evaluation.
zone_plans	array of ZonePlanOut	no	Vendor zone starts declared by the mower's connection (ADR 0066); empty when it declares none, then zones cannot be linked to a start.
zones	array of ZoneOut	yes

ZoneStatsOut

Time per zone over whole UTC days.

Field	Type	Required	Notes
first_day	string (date)	yes
items	array of ZoneTotalsOut	yes
last_day	string (date)	yes

ZoneTotalsOut

Time in one zone over the period.

Field	Type	Required	Notes
days	array of ZoneDayOut	yes
entries	integer	yes	How often it entered the zone.
mowing_seconds	number	yes	Of that, time it mowed.
name	string	yes
seconds	number	yes	Time the mower was in the zone while it reported.
zone_id	string (uuid)	yes

---

Mirrored from docs/reference/api/telemetry.md at commit ccac8bf3da8a6f86155c29f6cd1aad963968fb68. Edit the file in the repository, not this wiki page.