Repository navigation
API reference
Generated by packaging/scripts/gen-api-docs.py. Do not hand-edit.
Index
Config
Health
The pinned Lucide subset, for the CLI and test tooling.
Overall health plus a per-device summary.
| name | in | required | type |
|---|---|---|---|
| device_id | query | False | string |
| timezone | query | False | string |
Public: feeds the lock sweep and findplus version --check.
Compact, lock-aware feed for the Tauri menu-bar widget (E16).
Lock Requirements
Whether the app is locked right now. Always reachable.
| name | in | required | type |
|---|---|---|---|
| findplus_session | cookie | False | string |
Lock immediately (manual button, or the client's idle timer).
| name | in | required | type |
|---|---|---|---|
| findplus_session | cookie | False | string |
Exchange a correct PIN for a session cookie. Rate-limited.
Request body:
{
"properties": {
"pin": {
"type": "string",
"title": "Pin"
}
},
"type": "object",
"required": [
"pin"
],
"title": "Body_unlock_api_lock_unlock_post"
}Remove the PIN and disable the lock. Requires the current PIN.
Request body:
{
"properties": {
"current_pin": {
"type": "string",
"title": "Current Pin"
}
},
"type": "object",
"required": [
"current_pin"
],
"title": "Body_remove_pin_api_settings_pin_delete"
}Read Settings
Get Start At Login
Get Onboarding Completed At
Get Onboarding Last Step
The effective value, resolved exactly as GET /api/widget resolves it.
Write Settings
Request body:
{
"properties": {
"theme": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Theme"
},
"idle_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Idle Minutes"
},
"lock_enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Lock Enabled"
},
"poll.interval_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Poll.Interval Minutes"
},
"history.retention_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "History.Retention Days"
},
"alerts.native_detail": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Alerts.Native Detail"
},
"onboarding.completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Onboarding.Completed At"
},
"onboarding.last_step": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Onboarding.Last Step"
}
},
"type": "object",
"title": "Body_write_settings_api_settings_patch"
}Toggle the desktop app's LaunchAgent through findplus.service.
Request body:
{
"properties": {
"value": {
"type": "boolean",
"title": "Value"
}
},
"type": "object",
"required": [
"value"
],
"title": "Body_set_start_at_login_api_settings_app_start_at_login_post"
}Stamp or clear the onboarding completion time (specs/onboarding.md § 2).
Request body:
{
"properties": {
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Value"
}
},
"type": "object",
"title": "Body_set_onboarding_completed_at_api_settings_onboarding_completed_at_post"
}Record the wizard's resume point, one of the eight known step ids.
Request body:
{
"properties": {
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Value"
}
},
"type": "object",
"title": "Body_set_onboarding_last_step_api_settings_onboarding_last_step_post"
}Set or change the PIN. Changing it requires the existing one.
Request body:
{
"properties": {
"new_pin": {
"type": "string",
"title": "New Pin"
},
"current_pin": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Current Pin"
}
},
"type": "object",
"required": [
"new_pin"
],
"title": "Body_set_pin_api_settings_pin_post"
}Say whether current_pin is the PIN, changing nothing.
Request body:
{
"properties": {
"current_pin": {
"type": "string",
"title": "Current Pin"
}
},
"type": "object",
"required": [
"current_pin"
],
"title": "Body_check_pin_api_settings_pin_check_post"
}Persist whether the widget renders a map snapshot.
Request body:
{
"properties": {
"value": {
"type": "boolean",
"title": "Value"
}
},
"type": "object",
"required": [
"value"
],
"title": "Body_set_widget_show_map_api_settings_widget_show_map_post"
}Persist whether the widget renders a map snapshot.
Request body:
{
"properties": {
"value": {
"type": "boolean",
"title": "Value"
}
},
"type": "object",
"required": [
"value"
],
"title": "Body_set_widget_show_map_api_settings_widget_show_map_put"
}Devices
Edit one device's label, icon, color or tracked flag.
| name | in | required | type |
|---|---|---|---|
| device_id | path | True | string |
Request body:
{
"properties": {
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Label"
},
"icon": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Icon"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Color"
},
"tracked": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Tracked"
}
},
"type": "object",
"title": "DevicePatch",
"description": "The editable fields of a device row.\n\nValidation lives in the model, not the route body, which is what makes\nFastAPI answer with api-contract.md's pinned\n`{\"detail\":[{\"loc\":[...],\"msg\":...}]}` shape. Raising an HTTPException from\nthe handler instead would produce `{\"detail\": \"<text>\"}` and break it."
}Set which device the dashboard focuses on first.
Request body:
{
"properties": {
"device_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device Id"
}
},
"type": "object",
"title": "Body_choose_default_api_devices_default_post"
}Re-query every authenticated provider for its device list.
Replace the tracked set. all_devices=true tracks everything.
Request body:
{
"properties": {
"device_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Device Ids"
},
"all_devices": {
"type": "boolean",
"title": "All Devices",
"default": false
}
},
"type": "object",
"title": "Body_set_tracked_api_devices_track_post"
}Delete Custom Icon
| name | in | required | type |
|---|---|---|---|
| icon_id | path | True | string |
Every uploaded icon's id, sorted, so a picker's list is stable.
Get Custom Icon
| name | in | required | type |
|---|---|---|---|
| icon_id | path | True | string |
Upload Custom Icon
Local dates holding data. Omit device_id for every device.
| name | in | required | type |
|---|---|---|---|
| device_id | query | False | string |
| timezone | query | False | string |
Export History
| name | in | required | type |
|---|---|---|---|
| fmt | query | False | string |
| day | query | False | string |
| start | query | False | string |
| end | query | False | string |
| device_id | query | False | string |
| group_id | query | False | string |
| timezone | query | False | string |
Newest stored observation. Reads local history; does not query Google.
| name | in | required | type |
|---|---|---|---|
| device_id | query | False | string |
| timezone | query | False | string |
Poll Runs
| name | in | required | type |
|---|---|---|---|
| limit | query | False | integer |
Get Routing Endpoint
One day of history, as one INDEPENDENT track per device.
| name | in | required | type |
|---|---|---|---|
| day | query | False | string |
| device_id | query | False | string |
| group_id | query | False | integer |
| movement_threshold_meters | query | False | number |
| gap_threshold_minutes | query | False | number |
| timezone | query | False | string |
Stays (with a saved-place label), trips between them, and no-sighting gaps.
| name | in | required | type |
|---|---|---|---|
| device_id | query | True | string |
| date | query | False | string |
| days | query | False | integer |
| gap_minutes | query | False | number |
| timezone | query | False | string |
A likely road route for one trip, or dashed straight segments.
| name | in | required | type |
|---|---|---|---|
| device_id | query | True | string |
| trip_id | query | True | string |
| date | query | False | string |
| days | query | False | integer |
| timezone | query | False | string |
Delete ALL history, optionally for one device.
Request body:
{
"properties": {
"confirm": {
"type": "boolean",
"title": "Confirm",
"default": false
},
"device_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device Id"
}
},
"type": "object",
"title": "Body_clear_history_api_history_clear_post"
}Delete observations older than a date. Requires explicit confirmation.
Request body:
{
"properties": {
"before": {
"type": "string",
"title": "Before",
"description": "YYYY-MM-DD, local date"
},
"confirm": {
"type": "boolean",
"title": "Confirm",
"default": false
}
},
"type": "object",
"required": [
"before"
],
"title": "Body_delete_before_api_history_delete_before_post"
}Trigger one immediate Find Hub query. Rate-limited to protect the account.
Set (or clear, with an empty value) the OSRM-compatible routing server.
Request body:
{
"properties": {
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Value"
}
},
"type": "object",
"title": "Body_set_routing_endpoint_api_settings_routing_endpoint_post"
}Del Place
| name | in | required | type |
|---|---|---|---|
| place_id | path | True | integer |
Get Places
Get Events
| name | in | required | type |
|---|---|---|---|
| place_id | query | False | integer |
| device_id | query | False | string |
| group_id | query | False | integer |
| since | query | False | string |
| until | query | False | string |
| limit | query | False | integer |
Get Presence
| name | in | required | type |
|---|---|---|---|
| device_id | query | False | string |
Get Search
| name | in | required | type |
|---|---|---|---|
| q | query | False | string |
Post Place
Request body:
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"latitude": {
"type": "number",
"title": "Latitude"
},
"longitude": {
"type": "number",
"title": "Longitude"
},
"radius_meters": {
"type": "integer",
"title": "Radius Meters"
},
"color": {
"type": "string",
"title": "Color",
"default": "#2f80ed"
},
"enter_confirmations": {
"type": "integer",
"title": "Enter Confirmations",
"default": 1
},
"exit_confirmations": {
"type": "integer",
"title": "Exit Confirmations",
"default": 2
}
},
"type": "object",
"required": [
"name",
"latitude",
"longitude",
"radius_meters"
],
"title": "PlaceCreate"
}Put Place
| name | in | required | type |
|---|---|---|---|
| place_id | path | True | integer |
Request body:
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"latitude": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Latitude"
},
"longitude": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Longitude"
},
"radius_meters": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Radius Meters"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Color"
},
"enter_confirmations": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Enter Confirmations"
},
"exit_confirmations": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Exit Confirmations"
}
},
"type": "object",
"title": "PlaceUpdate"
}Del Group
| name | in | required | type |
|---|---|---|---|
| group_id | path | True | integer |
Get Groups
Get Events
| name | in | required | type |
|---|---|---|---|
| group_id | query | False | integer |
| place_id | query | False | integer |
| since | query | False | string |
| until | query | False | string |
| limit | query | False | integer |
Get Presence
| name | in | required | type |
|---|---|---|---|
| group_id | path | True | integer |
| window | query | False | integer |
Post Group
Request body:
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"color": {
"type": "string",
"title": "Color",
"default": "#27ae60"
},
"icon": {
"type": "string",
"title": "Icon",
"default": "lucide:users"
},
"quorum": {
"type": "string",
"title": "Quorum",
"default": "majority"
},
"cluster_radius_meters": {
"type": "integer",
"title": "Cluster Radius Meters",
"default": 150
},
"stale_after_minutes": {
"type": "integer",
"title": "Stale After Minutes",
"default": 90
},
"member_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Member Ids",
"default": []
}
},
"type": "object",
"required": [
"name"
],
"title": "GroupCreate"
}Put Group
| name | in | required | type |
|---|---|---|---|
| group_id | path | True | integer |
Request body:
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Color"
},
"icon": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Icon"
},
"quorum": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Quorum"
},
"cluster_radius_meters": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Cluster Radius Meters"
},
"stale_after_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Stale After Minutes"
}
},
"type": "object",
"title": "GroupUpdate"
}Put Members
| name | in | required | type |
|---|---|---|---|
| group_id | path | True | integer |
Request body:
{
"properties": {
"member_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Member Ids"
}
},
"type": "object",
"required": [
"member_ids"
],
"title": "MembersBody"
}Delete Telegram
Delete Webhook
Delete Whatsapp
Delete Rule
| name | in | required | type |
|---|---|---|---|
| rule_id | path | True | integer |
Get Channels
"Find chat IDs": distinct chats seen in the saved bot's pending updates.
The delivery log, and the queue the desktop native poller drains.
| name | in | required | type |
|---|---|---|---|
| limit | query | False | integer |
| since | query | False | integer |
| channel | query | False | string |
Get Rules
Post Telegram Setup
| name | in | required | type |
|---|---|---|---|
| wait | query | False | integer |
Request body:
{
"properties": {
"bot_token": {
"type": "string",
"title": "Bot Token"
}
},
"type": "object",
"required": [
"bot_token"
],
"title": "TelegramSetupBody"
}The desktop app confirms it showed a queued native notification.
| name | in | required | type |
|---|---|---|---|
| delivery_id | path | True | integer |
Post Rule
Request body:
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"place_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Place Id"
},
"group_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Group Id"
},
"device_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device Id"
},
"on_enter": {
"type": "boolean",
"title": "On Enter",
"default": true
},
"on_exit": {
"type": "boolean",
"title": "On Exit",
"default": true
},
"channels": {
"items": {
"type": "string"
},
"type": "array",
"title": "Channels"
},
"cooldown_minutes": {
"type": "integer",
"maximum": 1440.0,
"minimum": 0.0,
"title": "Cooldown Minutes",
"default": 30
},
"enabled": {
"type": "boolean",
"title": "Enabled",
"default": true
},
"also_notify_members": {
"type": "boolean",
"title": "Also Notify Members",
"default": false
},
"telegram_targets": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Telegram Targets"
}
},
"type": "object",
"required": [
"name",
"channels"
],
"title": "RuleCreate"
}Post Dry Run
Request body:
{
"properties": {
"place_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Place Id"
},
"device_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device Id"
},
"group_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Group Id"
},
"on_enter": {
"type": "boolean",
"title": "On Enter",
"default": true
},
"on_exit": {
"type": "boolean",
"title": "On Exit",
"default": true
},
"cooldown_minutes": {
"type": "integer",
"maximum": 1440.0,
"minimum": 0.0,
"title": "Cooldown Minutes",
"default": 30
},
"hours": {
"type": "integer",
"maximum": 72.0,
"minimum": 1.0,
"title": "Hours",
"default": 24
}
},
"type": "object",
"title": "DryRunBody"
}Post Test
Request body:
{
"properties": {
"channel": {
"type": "string",
"enum": [
"telegram",
"webhook",
"whatsapp",
"native"
],
"title": "Channel"
}
},
"type": "object",
"required": [
"channel"
],
"title": "AlertTestBody"
}Put Telegram
Request body:
{
"properties": {
"bot_token": {
"type": "string",
"title": "Bot Token"
},
"targets": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targets"
},
"chat_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Chat Id"
}
},
"type": "object",
"required": [
"bot_token"
],
"title": "TelegramPutBody"
}Edit the target list alone, no bot-token round trip.
Request body:
{
"properties": {
"targets": {
"type": "string",
"title": "Targets"
}
},
"type": "object",
"required": [
"targets"
],
"title": "TelegramTargetsBody"
}Put Webhook
Request body:
{
"properties": {
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url"
},
"secret": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Secret"
}
},
"type": "object",
"title": "WebhookPutBody"
}Put Whatsapp
Request body:
{
"properties": {
"phone": {
"type": "string",
"title": "Phone"
},
"apikey": {
"type": "string",
"title": "Apikey"
}
},
"type": "object",
"required": [
"phone",
"apikey"
],
"title": "WhatsappPutBody"
}Put Rule
| name | in | required | type |
|---|---|---|---|
| rule_id | path | True | integer |
Request body:
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"place_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Place Id"
},
"on_enter": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "On Enter"
},
"on_exit": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "On Exit"
},
"channels": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Channels"
},
"cooldown_minutes": {
"anyOf": [
{
"type": "integer",
"maximum": 1440.0,
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Cooldown Minutes"
},
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enabled"
},
"also_notify_members": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Also Notify Members"
},
"telegram_targets": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Telegram Targets"
}
},
"type": "object",
"title": "RuleUpdate"
}List Providers
S11/WP8: disconnect a provider. Same Origin guard as the sign-in
| name | in | required | type |
|---|---|---|---|
| provider | path | True | string |
Apple Progress
| name | in | required | type |
|---|---|---|---|
| job_id | query | False | string |
Google Progress
| name | in | required | type |
|---|---|---|---|
| job_id | query | False | string |
Google Unlock Progress
| name | in | required | type |
|---|---|---|---|
| job_id | query | False | string |
Auth Status
Begin Page
| name | in | required | type |
|---|---|---|---|
| state | query | False | string |
Success Page
| name | in | required | type |
|---|---|---|---|
| kind | query | False | string |
Unlock Begin Page
| name | in | required | type |
|---|---|---|---|
| state | query | False | string |
Apple Accessories
Apple Code
Request body:
{
"properties": {
"job_id": {
"type": "string",
"title": "Job Id"
},
"code": {
"type": "string",
"title": "Code"
}
},
"type": "object",
"required": [
"job_id",
"code"
],
"title": "AppleCodeBody"
}Apple Start
Request body:
{
"properties": {
"apple_id": {
"type": "string",
"title": "Apple Id"
},
"password": {
"type": "string",
"title": "Password"
}
},
"type": "object",
"required": [
"apple_id",
"password"
],
"title": "AppleStartBody"
}UAT6 N23: Cancel while waiting on Chrome. Same Origin guard as start.
Request body:
{
"properties": {
"job_id": {
"type": "string",
"title": "Job Id"
}
},
"type": "object",
"required": [
"job_id"
],
"title": "GoogleCancelBody"
}Helper Begin
Open chrome://extensions in the user's Google Chrome (their explicit ask).
Copy the extension to a stable folder and reveal it in the file manager.
Helper Seen
Request body:
{
"properties": {
"state": {
"type": "string",
"title": "State",
"default": ""
}
},
"type": "object",
"title": "HelperSeenBody"
}Helper Token
Request body:
{
"properties": {
"state": {
"type": "string",
"title": "State",
"default": ""
},
"oauth_token": {
"title": "Oauth Token",
"default": ""
}
},
"type": "object",
"title": "HelperTokenBody"
}Helper Unlock
Request body:
{
"properties": {
"state": {
"type": "string",
"title": "State",
"default": ""
},
"vault_keys": {
"title": "Vault Keys",
"default": ""
}
},
"type": "object",
"title": "HelperUnlockBody"
}Helper Unlock Begin
Open Google's sign-in page (EmbeddedSetup) in the user's own Chrome.
Google Start
Exchange a pasted oauth_token for a Find Hub session.
Request body:
{
"properties": {
"email": {
"type": "string",
"title": "Email",
"description": "The Google email you signed in with.",
"default": ""
},
"oauth_token": {
"type": "string",
"title": "Oauth Token",
"description": "The Value of the oauth_token cookie. Starts with oauth2_4/.",
"default": ""
}
},
"type": "object",
"title": "GoogleTokenBody",
"description": "The Google email and the oauth_token cookie value copied from Chrome."
}Google Unlock Cancel
Request body:
{
"properties": {
"job_id": {
"type": "string",
"title": "Job Id"
}
},
"type": "object",
"required": [
"job_id"
],
"title": "GoogleUnlockCancelBody"
}Google Unlock Start