Reference Planner

planner API

Mowing patterns, spot paths and plans.

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

Operations

planner

POST /api/v1/planner/coverage/gaps

Coverage Gaps

Covered ground and the gaps of an area from the mower's position track (Telemetry) between start and end, with a remow step for them.

Request body (required): application/json GapsRequestIn

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

GET /api/v1/planner/patterns

List Patterns

Every registered pattern with its settings schema (plug-ins included).

Status	Meaning	Body
200	Successful Response	application/json PatternList

POST /api/v1/planner/plans

Create Plan

The plan ready to start: the SpotMowPlan with its hash and the start_mow command for Fleet. Nothing is stored; the same request gives the same hash. Needs can_control on the mower (Fleet checks it again when the command arrives).

Request body (required): application/json PlanRequestIn

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

POST /api/v1/planner/plans/preview

Preview Plan

Compute and validate a plan and show it: segments, duration, area, warnings, and how the mower can run it. Needs can_view on the mower (404 when invisible).

Request body (required): application/json PlanRequestIn

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

GET /api/v1/planner/templates

List Templates

Saved chains of the caller's account.

Status	Meaning	Body
200	Successful Response	application/json TemplateList

GET /api/v1/planner/templates/{name}

Get Template

One saved chain.

Parameter	In	Type	Required	Notes
name	path	string	yes	min length 1; max length 100

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

PUT /api/v1/planner/templates/{name}

Put Template

Create (201) or replace (200) a saved chain; needs can_control on the account.

Parameter	In	Type	Required	Notes
name	path	string	yes	min length 1; max length 100

Request body (required): application/json TemplateIn

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

DELETE /api/v1/planner/templates/{name}

Delete Template

Delete a saved chain; needs can_control on the account.

Parameter	In	Type	Required	Notes
name	path	string	yes	min length 1; max length 100

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

Schemas

AreaIn

Where to mow. area_id alone is a whole map area; a polygon (local metres or WGS84 [lat, lon]) is a spot, inside area_id when given, else inside the mapped areas.

Field	Type	Required	Notes
area_id	string or null	no
holes	array of array of array of any	no	max items 50
polygon	array of array of any or null	no
polygon_wgs84	array of array of any or null	no	[lat, lon] pairs.

ChainStepIn

One pattern of a chain with its settings (validated by the pattern's schema).

Field	Type	Required	Notes
pattern	string	yes	max length 64; pattern ^[a-z][a-z0-9_]*$
settings	object	no

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

ExecutionOut

How the mower can run the plan.

Field	Type	Required	Notes
mode	"custom_paths" | "native" | "unsupported" | "unknown"	yes	custom_paths: the mower follows the route; native: it runs native_job on the map area; unsupported: it cannot run this plan; unknown: no capabilities (a raw map).
native_job	object or null	no	StartMow.pattern settings of the native form, if any.
reason	string	yes

GapsOut

Covered ground and gaps; remow is a ready chain step for the gaps.

Field	Type	Required	Notes
area_id	string or null	yes
area_m2	number	yes
coverage_ratio	number	yes
covered_area_m2	number	yes
gap_area_m2	number	yes
gaps	array of array of array of any	yes	Gap polygons in local metres.
gaps_wgs84	array of array of array of any	yes	The same as [lat, lon].
remow	ChainStepIn or null	no	A remow step over the gaps (None without gaps).
track_points	integer	yes
truncated	boolean	yes

GapsRequestIn

Which parts of an area did the mower miss between start and end?

Field	Type	Required	Notes
area	AreaIn or null	no	Default: the map area with the most track points.
cutting_width_m	number or null	no
end	string (date-time)	yes
min_gap_m2	number	no	min 0.0; max 100.0; default 0.05
mower_id	string (uuid)	yes
start	string (date-time)	yes

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

HTTPValidationError

Field	Type	Required	Notes
detail	array of ValidationError	no

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

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

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.

MowerSpecIn

Overrides of the mower data (defaults: the Planner's settings and the mower's speed).

Field	Type	Required	Notes
cutting_width_m	number or null	no
max_speed_mps	number or null	no
overlap_m	number or null	no
safety_margin_m	number or null	no
transfer_speed_mps	number or null	no
turning_radius_m	number or null	no

MowerSpecOut

The mower data a plan was computed with.

Field	Type	Required	Notes
cutting_width_m	number	yes
max_speed_mps	number	yes
overlap_m	number	yes
safety_margin_m	number	yes
spacing_m	number	yes
transfer_speed_mps	number	yes
turning_radius_m	number	yes

PatternList

Every registered pattern, by key.

Field	Type	Required	Notes
items	array of PatternOut	yes

PatternOut

A registered pattern: the app builds the settings form from settings_schema.

Field	Type	Required	Notes
description	string or null	no
key	string	yes
name	string	yes
native	string or null	no	Name of the native pattern a mower may run instead (on a whole map area); whether a mower supports it is in its capabilities (native_patterns).
settings_schema	object	yes	JSON Schema (draft 2020-12).

PlanOut

A plan ready to start: send command to Fleet (POST /api/v1/fleet/mowers/{mower_id}/commands with {"command": ...}).

Field	Type	Required	Notes
area_m2	number	yes
command	StartMow	yes
coverage_ratio	number	yes
covered_area_m2	number	yes
estimated_duration_s	number	yes
execution	ExecutionOut	yes
mow_length_m	number	yes
mower	MowerSpecOut	yes
pattern_chain	array of string	yes
plan_bytes	integer	yes
plan_hash	string	yes
preview	object	yes	FeatureCollection: one LineString per segment with kind, blades_on, reverse, speed_mps; coordinates local metres, or [lon, lat] with wgs84.
segment_count	integer	yes
spot_plan	SpotMowPlan	yes
transfer_length_m	number	yes
transit	TransitOut or null	no	The transit of a spot run, when the request asked for it.
turn_style	TurnStyle or null	no	The turn style the lane ends were shaped with (after the multi_point fallback); null without a requested style.
warnings	array of string	yes

PlanRequestIn

A plan for a mower (mower_id: its map and capabilities) or for a raw map.

Field	Type	Required	Notes
area	AreaIn	yes
chain	array of ChainStepIn	no	max items 8
map	MowerMap or null	no	A map instead of a mower's.
mower	MowerSpecIn or null	no
mower_id	string (uuid) or null	no
template	string or null	no	Use the chain of a saved template instead of chain.
transit	TransitIn or null	no	Also plan the transit of a spot run from the dock or a position to the plan's first point (ADR 0041).
turn_style	TurnStyle or null	no	Shape the lane ends for a spot run that turns this way (ADR 0043): arc (U-turn or bulb turn), multi_point (three-point turn; arc when the mower's drive link cannot reverse) or in_place; null keeps the straight connections.
wgs84	boolean	no	Preview coordinates as [lon, lat].; default false

PreviewOut

A validated plan: totals, how it runs, and the segments as a GeoJSON-like collection.

Field	Type	Required	Notes
area_m2	number	yes
coverage_ratio	number	yes
covered_area_m2	number	yes
estimated_duration_s	number	yes
execution	ExecutionOut	yes
mow_length_m	number	yes
mower	MowerSpecOut	yes
pattern_chain	array of string	yes
plan_bytes	integer	yes
plan_hash	string	yes
preview	object	yes	FeatureCollection: one LineString per segment with kind, blades_on, reverse, speed_mps; coordinates local metres, or [lon, lat] with wgs84.
segment_count	integer	yes
transfer_length_m	number	yes
transit	TransitOut or null	no	The transit of a spot run, when the request asked for it.
turn_style	TurnStyle or null	no	The turn style the lane ends were shaped with (after the multi_point fallback); null without a requested style.
warnings	array of string	yes

SpotMowPlan

A computed mowing route for StartMow.spot_plan.

Field	Type	Required	Notes
covered_area_m2	number	no	min 0.0; default 0.0
estimated_duration_s	number	no	min 0.0; default 0.0
native	SpotNativeJob or null	no
pattern_chain	array of string	yes	min items 1; max items 16
plan_hash	string	yes	SHA-256 of the chain and the segments (spot_plan_hash); must match.; pattern ^[0-9a-f]{64}$
segments	array of SpotSegment	yes	min items 1; max items 10000

SpotNativeJob

The plan expressed as a native job of the mower: whole map areas and one pattern.

Present only when the chain is exactly one pattern the mower may run by itself (stripes, diagonal, checkerboard, edge_only, or border_fill with one of them) on map areas, so a mower without custom_paths can still execute it as an ordinary StartMow(area_ids, pattern).

Field	Type	Required	Notes
area_ids	array of string	yes	min items 1
pattern	object	yes	Settings in the form of StartMow.pattern (name, angle_deg, spacing_m, border_laps, order).

SpotSegment

One part of a spot plan: drive along path with the blades on or off (backwards with reverse: the mower faces against the direction of travel, part of a three-point turn).

Field	Type	Required	Notes
blades_on	boolean	yes
kind	"mow" | "turn" | "transfer"	no	default "mow"
path	string	yes	Encoded polyline of local metres (x, y), centimetre precision (encode_polyline), at least two points.; min length 4; max length 200000
reverse	boolean	no	Drive the polyline backwards (negative linear speed, the mower faces against the direction of travel); always with the blades off (ADR 0043).; default false
speed_mps	number	yes	max 2.0; greater than 0.0

StartMow

Start mowing the given areas, a stored plan or an inline spot plan (exactly one).

Field	Type	Required	Notes
area_ids	array of string	no	Map area ids to mow, in order.
kind	"start_mow"	no	default "start_mow"
pattern	object or null	no	Pattern settings (validated by the pattern's own JSON Schema).
plan_ref	string or null	no	Reference to a stored mowing plan.
spot_plan	SpotMowPlan or null	no	A route computed by the Planner (spot mowing). Runs only on mowers with custom_paths, or natively when the plan carries a native job.

TemplateIn

A saved chain.

Field	Type	Required	Notes
chain	array of ChainStepIn	yes	min items 1; max items 8
description	string or null	no

TemplateList

Templates of the account, by name.

Field	Type	Required	Notes
items	array of TemplateOut	yes

TemplateOut

A saved chain of the account.

Field	Type	Required	Notes
chain	array of ChainStepIn	yes
created_at	string (date-time)	yes
description	string or null	yes
name	string	yes
updated_at	string (date-time)	yes

TransitIn

Where a spot run's transit would start (ADR 0041): from_dock for a docked mower (the map's dock, as the Device-Gateway plans it), else the mower's position in local metres.

Field	Type	Required	Notes
from_dock	boolean	no	default false
position	array of any or null	no

TransitOut

The transit a spot run would drive from the start to the plan's first point (blades off), planned by the same algorithm as the Device-Gateway's run.

Field	Type	Required	Notes
found	boolean	yes	A route exists (the web app's route condition).
from_dock	boolean	yes
length_m	number	yes
reason	string or null	no	no_route: ... without a route.
route	array of array of number	yes	The route, local metres or [lon, lat] with wgs84; empty without one.

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

---

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