Skip to content

API reference

github-actions[bot] edited this page Sep 21, 2026 · 19 revisions

API reference

Generated by packaging/scripts/gen-api-docs.py. Do not hand-edit.

core

GET /

Index

GET /api/config

Config

GET /api/health

Health

GET /api/icons

The pinned Lucide subset, for the CLI and test tooling.

GET /api/status

Overall health plus a per-device summary.

name in required type
device_id query False string
timezone query False string

GET /api/version

Public: feeds the lock sweep and findplus version --check.

GET /api/widget

Compact, lock-aware feed for the Tauri menu-bar widget (E16).

lock

GET /api/lock/requirements

Lock Requirements

GET /api/lock/status

Whether the app is locked right now. Always reachable.

name in required type
findplus_session cookie False string

POST /api/lock/lock

Lock immediately (manual button, or the client's idle timer).

name in required type
findplus_session cookie False string

POST /api/lock/unlock

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"
}

settings

DELETE /api/settings/pin

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"
}

GET /api/settings

Read Settings

GET /api/settings/app.start_at_login

Get Start At Login

GET /api/settings/onboarding.completed_at

Get Onboarding Completed At

GET /api/settings/onboarding.last_step

Get Onboarding Last Step

GET /api/settings/widget.show_map

The effective value, resolved exactly as GET /api/widget resolves it.

PATCH /api/settings

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"
}

POST /api/settings/app.start_at_login

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"
}

POST /api/settings/onboarding.completed_at

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"
}

POST /api/settings/onboarding.last_step

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"
}

POST /api/settings/pin

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"
}

POST /api/settings/widget.show_map

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"
}

PUT /api/settings/widget.show_map

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

GET /api/devices

Devices

PATCH /api/devices/{device_id}

Edit one device's label, icon, colour 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."
}

POST /api/devices/default

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"
}

POST /api/devices/refresh

Re-query every authenticated provider for its device list.

POST /api/devices/track

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"
}

history

GET /api/days

Local dates holding data. Omit device_id for every device.

name in required type
device_id query False string
timezone query False string

GET /api/export

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

GET /api/latest

Newest stored observation. Reads local history; does not query Google.

name in required type
device_id query False string
timezone query False string

GET /api/poll-runs

Poll Runs

name in required type
limit query False integer

GET /api/timeline

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

POST /api/history/clear

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"
}

POST /api/history/delete-before

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"
}

POST /api/poll-now

Trigger one immediate Find Hub query. Rate-limited to protect the account.

places

DELETE /api/places/{place_id}

Del Place

name in required type
place_id path True integer

GET /api/places

Get Places

GET /api/places/events

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 /api/places/presence

Get Presence

name in required type
device_id query False string

POST /api/places

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 /api/places/{place_id}

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"
}

groups

DELETE /api/groups/{group_id}

Del Group

name in required type
group_id path True integer

GET /api/groups

Get Groups

GET /api/groups/events

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 /api/groups/{group_id}/presence

Get Presence

name in required type
group_id path True integer
window query False integer

POST /api/groups

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 /api/groups/{group_id}

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 /api/groups/{group_id}/members

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"
}

alerts

DELETE /api/alerts/channels/telegram

Delete Telegram

DELETE /api/alerts/channels/webhook

Delete Webhook

DELETE /api/alerts/channels/whatsapp

Delete Whatsapp

DELETE /api/alerts/rules/{rule_id}

Delete Rule

name in required type
rule_id path True integer

GET /api/alerts/channels

Get Channels

GET /api/alerts/deliveries

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 /api/alerts/rules

Get Rules

POST /api/alerts/channels/telegram/setup

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"
}

POST /api/alerts/deliveries/{delivery_id}/ack

The desktop app confirms it showed a queued native notification.

name in required type
delivery_id path True integer

POST /api/alerts/rules

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
    }
  },
  "type": "object",
  "required": [
    "name",
    "channels"
  ],
  "title": "RuleCreate"
}

POST /api/alerts/test

Post Test

Request body:

{
  "properties": {
    "channel": {
      "type": "string",
      "enum": [
        "telegram",
        "webhook",
        "whatsapp",
        "native"
      ],
      "title": "Channel"
    }
  },
  "type": "object",
  "required": [
    "channel"
  ],
  "title": "AlertTestBody"
}

PUT /api/alerts/channels/telegram

Put Telegram

Request body:

{
  "properties": {
    "bot_token": {
      "type": "string",
      "title": "Bot Token"
    },
    "chat_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Chat Id"
    }
  },
  "type": "object",
  "required": [
    "bot_token"
  ],
  "title": "TelegramPutBody"
}

PUT /api/alerts/channels/webhook

Put Webhook

Request body:

{
  "properties": {
    "url": {
      "type": "string",
      "title": "Url"
    },
    "secret": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Secret"
    }
  },
  "type": "object",
  "required": [
    "url"
  ],
  "title": "WebhookPutBody"
}

PUT /api/alerts/channels/whatsapp

Put Whatsapp

Request body:

{
  "properties": {
    "phone": {
      "type": "string",
      "title": "Phone"
    },
    "apikey": {
      "type": "string",
      "title": "Apikey"
    }
  },
  "type": "object",
  "required": [
    "phone",
    "apikey"
  ],
  "title": "WhatsappPutBody"
}

PUT /api/alerts/rules/{rule_id}

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"
    }
  },
  "type": "object",
  "title": "RuleUpdate"
}

providers

GET /api/providers

List Providers

auth

GET /api/auth/apple/progress

Apple Progress

name in required type
job_id query False string

GET /api/auth/google/progress

Google Progress

name in required type
job_id query False string

GET /api/auth/status

Auth Status

POST /api/apple/accessories

Apple Accessories

POST /api/auth/apple/code

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"
}

POST /api/auth/apple/start

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"
}

POST /api/auth/google/start

Google Start

Clone this wiki locally