Reference Entitlements

entitlements API

What the account's plan allows; usage and limits.

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

Operations

entitlements

GET /api/v1/entitlements/accounts

Accounts

Accounts with a plan row, oldest first, with their effective plans (operators).

Parameter	In	Type	Required	Notes
offset	query	integer	no	min 0; default 0
limit	query	integer	no	min 1; max 200; default 50

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

GET /api/v1/entitlements/accounts/{account_id}

Get Account

One account: what applies, the assignment and its history (operators).

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

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

PUT /api/v1/entitlements/accounts/{account_id}/plan

Assign Plan

Assign a plan by hand (operators): history row, entitlements.plan.changed.

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

Request body (required): application/json AssignmentIn

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

GET /api/v1/entitlements/features

Features

Every feature key the modules declare (retired keys included).

Status	Meaning	Body
200	Successful Response	application/json array of FeatureOut

GET /api/v1/entitlements/me

Me

The plan, status, limits and features that apply to the caller's account now.

Status	Meaning	Body
200	Successful Response	application/json ResolvedOut

GET /api/v1/entitlements/plans

Plans

The plans on offer (public: a pricing page needs no login).

Status	Meaning	Body
200	Successful Response	application/json array of PlanOut

GET /api/v1/entitlements/plans/{key}

Get Plan

One plan (operators), also an inactive one.

Parameter	In	Type	Required	Notes
key	path	string	yes

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

PUT /api/v1/entitlements/plans/{key}

Put Plan

Create or replace a plan (operators); every service drops its cached snapshots.

Parameter	In	Type	Required	Notes
key	path	string	yes

Request body (required): application/json PlanIn

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

Schemas

AccountDetailOut

One account for operators: what applies, the assignment and its history.

Field	Type	Required	Notes
account_id	string (uuid)	yes
account_name	string or null	yes
assigned	AssignedOut or null	yes
effective	ResolvedOut	yes
history	array of HistoryOut	yes

AccountOut

An account in the operator list: its assignment and what applies (no mower data).

Field	Type	Required	Notes
account_id	string (uuid)	yes
account_name	string or null	yes
assigned	AssignedOut	yes
effective	ResolvedOut	yes

AccountPageOut

A page of accounts (offset/limit).

Field	Type	Required	Notes
billing_enabled	boolean	yes
items	array of AccountOut	yes
limit	integer	yes
offset	integer	yes
total	integer	yes

AssignedOut

The stored assignment of an account.

Field	Type	Required	Notes
grace_until	string (date-time) or null	yes
plan	string	yes
since	string (date-time)	yes
source	PlanSource	yes
status	PlanStatus	yes	Stored status (time does not change it).
trial_until	string (date-time) or null	yes
updated_at	string (date-time)	yes

AssignmentIn

Body of PUT /accounts/{id}/plan.

Field	Type	Required	Notes
account_name	string or null	no
grace_until	string (date-time) or null	no	End of a grace period; default now plus the grace days.
plan	string	yes	min length 1; max length 64
reason	string	yes	Why (kept in the history).; min length 1; max length 500
status	PlanStatus	no	default "active"
trial_until	string (date-time) or null	no	End of a trial; default now plus the plan's trial days.

FeatureOut

A feature of the catalogue.

Field	Type	Required	Notes
description	string	yes
key	string	yes
module	string	yes
retired	boolean	yes

HistoryOut

One assignment.

Field	Type	Required	Notes
actor	string or null	yes
at	string (date-time)	yes
grace_until	string (date-time) or null	yes
plan	string	yes
reason	string or null	yes
source	PlanSource	yes
status	PlanStatus	yes
trial_until	string (date-time) or null	yes

HTTPValidationError

Field	Type	Required	Notes
detail	array of ValidationError	no

PlanDetailOut

A plan for operators: also the features no module declares and where it came from.

Field	Type	Required	Notes
active	boolean	yes
created_at	string (date-time) or null	yes
description	string or null	yes
features	array of string	yes	Feature keys; * grants every feature.
from_plan_file	boolean	yes	Seeded from the plan file (a changed file entry overwrites it at the next start).
is_default	boolean	yes
key	string	yes
limits	PlanLimits	yes	Limits; null means unlimited.
name	string	yes
trial_days	integer	yes
unknown_features	array of string	yes	Feature keys of the plan that no module declares (kept, they gate nothing until a module enforcing them is deployed).
updated_at	string (date-time) or null	yes

PlanIn

Body of PUT /plans/{key}: the whole plan.

Field	Type	Required	Notes
active	boolean	no	default true
description	string or null	no
features	array of string or string	no	max items 500
is_default	boolean	no	default false
limits	PlanLimits	no
name	string	yes	min length 1; max length 200
trial_days	integer	no	min 0.0; max 365.0; default 0

PlanLimits

The limits of a plan; None means unlimited.

Field	Type	Required	Notes
history_days	integer or null	no
max_groups	integer or null	no
max_mowers	integer or null	no
max_schedules	integer or null	no
max_sites	integer or null	no
max_users	integer or null	no

PlanOut

A plan as offered.

Field	Type	Required	Notes
active	boolean	yes
description	string or null	yes
features	array of string	yes	Feature keys; * grants every feature.
is_default	boolean	yes
key	string	yes
limits	PlanLimits	yes	Limits; null means unlimited.
name	string	yes
trial_days	integer	yes

PlanSource

Who set an account's plan.

Type: "default" | "manual" | "billing"

PlanStatus

Status of an account's plan.

Type: "active" | "trial" | "grace" | "expired"

ResolvedOut

The plan that applies to an account now.

Field	Type	Required	Notes
account_id	string (uuid)	yes
billing_enabled	boolean	yes	False: billing is disabled on this installation and every account has the plan unlimited, whatever was assigned.
features	array of string	yes
grace_until	string (date-time) or null	no
limits	PlanLimits	yes
plan	string	yes
plan_name	string	yes
since	string (date-time) or null	no
source	PlanSource	yes
status	PlanStatus	yes	Effective status (an ended trial is expired).
trial_until	string (date-time) or null	no

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/entitlements.md at commit d31bb5cc2fa17ace35f89531465b76d8f888ece6. Edit the file in the repository, not this wiki page.