Reference Assistant

assistant API

Chat control: proposals from typed requests (optional add-on, ADR 0075).

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

Operations

assistant

POST /api/v1/assistant/mowers/{mower_id}/proposals

Propose

Interpret one request for one mower and validate the result against the mower's actions, areas and the caller's rights. Answers a proposal; nothing is executed. The text is neither stored nor logged.

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

Request body (required): application/json ProposalIn

Status	Meaning	Body
200	Successful Response	application/json ProposalOut
404	The mower does not exist or the caller cannot see it.	no body
409	assistant-provider-missing: no AI provider configured.	no body
422	Empty or too long text, or an unknown time zone.	no body
429	assistant-limit: the caller's or the provider's limit.	no body
502	assistant-provider-failed: the model gave no usable answer.	no body
503	A MowDeck service the assistant reads did not answer.	no body

GET /api/v1/assistant/status

Assistant Status

Whether the caller can ask now: with the provider interpreter a configured AI provider (own or the installation's, Settings, AI provider) is needed; the phrase parser is always ready.

Status	Meaning	Body
200	Successful Response	application/json StatusOut

Schemas

ActionKind

What a proposal can contain.

Type: "start_now" | "start_later" | "pause" | "resume" | "dock"

ActionOut

One validated action: exactly what the web app executes after the user confirmed.

Field	Type	Required	Notes
area_ids	array of string	yes	start_now/start_later: the areas in mowing order (every area when the user named none); empty for the other kinds.
areas	array of AreaOut	yes
duration_minutes	integer or null	yes	start_later: the time window.
kind	ActionKind	yes
start_at	string (date-time) or null	yes	start_later: the UTC start.
start_local	string or null	yes	start_later: the start as YYYY-MM-DDTHH:MM in timezone.
timezone	string or null	yes

AreaOut

A map area of the mower.

Field	Type	Required	Notes
id	string	yes
name	string	yes

Note

Why (part of) a request has no action, as the model or the phrase parser reports it.

The web app explains each in the user's language; free text from the model is never shown (it could carry injected instructions or links).

Type: "manual_drive" | "settings" | "timed_resume" | "other_mower" | "unsupported" | "unclear"

ProposalIn

POST /mowers/{mower_id}/proposals: one request in the user's words.

Field	Type	Required	Notes
text	string	yes	What the user typed.; min length 1; max length 500
timezone	string	yes	IANA time zone of the user (the browser's): times like "tomorrow 8:00" are meant in it, and a one-off start is scheduled in it.; min length 1; max length 64

ProposalOut

The validated proposal for one request. Nothing has been executed.

executable is true only when every action passed validation (all or nothing); then the web app shows the actions on a confirmation card and, after the user confirmed, sends them through Fleet's command and the Scheduler's schedule endpoints with the user's token.

Field	Type	Required	Notes
actions	array of ActionOut	yes
areas	array of AreaOut	yes	Every map area of the mower.
created_at	string (date-time)	yes
executable	boolean	yes
expires_at	string (date-time)	yes	Execute before this time, else ask again.
interpreter	"provider" | "phrases"	yes
model	string or null	yes
mower_id	string (uuid)	yes
mower_name	string	yes
notes	array of Note	yes	Why (part of) the request has no action.
rejected	array of RejectedOut	yes
unavailable	map of Unavailable	yes	Kinds not offered for this mower right now, with the reason.

RejectedOut

An action of the interpretation that the validator refused.

Field	Type	Required	Notes
code	Rejection	yes
kind	ActionKind or null	yes

Rejection

Why one action of the model's answer was refused by the validator.

Type: "unknown_kind" | "not_offered" | "unknown_area" | "too_many_areas" | "unexpected_field" | "time_missing" | "time_invalid" | "time_past" | "time_too_far" | "duration_invalid" | "too_many_actions" | "conflict" | "malformed"

StatusOut

GET /status: whether the caller can ask now.

Field	Type	Required	Notes
hosted	boolean or null	yes	The installation's model, not the caller's own.
interpreter	"provider" | "phrases"	yes	provider: the caller's AI provider (Settings, AI provider); phrases: the built-in phrase parser without AI (demo mode or the operator's choice).
model	string or null	yes	The model a request would use (never a key).
ready	boolean	yes
reason	"no_provider" | "provider_unavailable" or null	yes	Why not ready: no provider configured (own or the installation's), or the AI provider settings (Vision) are not reachable.

Unavailable

Why a kind is not offered for this mower right now.

Type: "permission" | "no_areas" | "state" | "not_connected"

---

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