Skip to content

API reference

github-actions[bot] edited this page Sep 19, 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/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/widget.show_map

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

POST /api/settings/app.start_at_login

Toggle the desktop app's LaunchAgent via the shared service code.

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/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

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

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

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 Find Hub for the account's 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"
    },
    "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"
    },
    "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/rules/{rule_id}

Delete Rule

name in required type
rule_id path True integer

GET /api/alerts/channels

Get Channels

GET /api/alerts/deliveries

Get Deliveries

name in required type
limit query False integer

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/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
    },
    "channel": {
      "type": "string",
      "enum": [
        "telegram",
        "webhook"
      ],
      "title": "Channel"
    },
    "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",
    "channel"
  ],
  "title": "RuleCreate"
}

POST /api/alerts/test

Post Test

Request body:

{
  "properties": {
    "channel": {
      "type": "string",
      "enum": [
        "telegram",
        "webhook"
      ],
      "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/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"
    },
    "channel": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "telegram",
            "webhook"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Channel"
    },
    "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

Clone this wiki locally