Skip to content

API reference

github-actions[bot] edited this page Oct 5, 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/backup

Get Backup Status

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

Post Backup Now

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

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

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

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

icons

DELETE /api/icons/custom/{icon_id}

Delete Custom Icon

name in required type
icon_id path True string

GET /api/icons/custom

Every uploaded icon's id, sorted, so a picker's list is stable.

GET /api/icons/custom/{icon_id}.png

Get Custom Icon

name in required type
icon_id path True string

POST /api/icons/custom

Upload Custom Icon

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/settings/routing.endpoint

Get Routing Endpoint

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

GET /api/trips

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

GET /api/trips/route

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

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.

POST /api/settings/routing.endpoint

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

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

GET /api/places/search

Get Search

name in required type
q query False string

GET /api/places/suggestions

Get Suggestions

name in required type
timezone query False string
date 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": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Color"
    },
    "enter_confirmations": {
      "type": "integer",
      "title": "Enter Confirmations",
      "default": 1
    },
    "exit_confirmations": {
      "type": "integer",
      "title": "Exit Confirmations",
      "default": 2
    },
    "kind": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Kind"
    },
    "notify": {
      "type": "boolean",
      "title": "Notify",
      "default": true
    },
    "notify_channels": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Notify Channels"
    }
  },
  "type": "object",
  "required": [
    "name",
    "latitude",
    "longitude",
    "radius_meters"
  ],
  "title": "PlaceCreate"
}

POST /api/places/notify-defaults

Post Notify Defaults

name in required type
dry_run query False boolean

Request body:

{
  "properties": {
    "place_ids": {
      "anyOf": [
        {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Place Ids"
    }
  },
  "type": "object",
  "title": "Body_post_notify_defaults_api_places_notify_defaults_post"
}

POST /api/places/suggestions/dismiss

Post Dismiss

Request body:

{
  "properties": {
    "latitude": {
      "type": "number",
      "maximum": 90.0,
      "minimum": -90.0,
      "title": "Latitude"
    },
    "longitude": {
      "type": "number",
      "maximum": 180.0,
      "minimum": -180.0,
      "title": "Longitude"
    }
  },
  "type": "object",
  "required": [
    "latitude",
    "longitude"
  ],
  "title": "Dismiss"
}

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"
    },
    "kind": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Kind"
    }
  },
  "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": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Color"
    },
    "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": []
    },
    "kind": {
      "type": "string",
      "title": "Kind",
      "default": "set"
    }
  },
  "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"
    },
    "kind": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Kind"
    },
    "member_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Member Ids"
    }
  },
  "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"
}

people

DELETE /api/people/{group_id}

Del Person

name in required type
group_id path True integer

GET /api/people

Get People

GET /api/people/replay

{state: idle|running|done|failed, done, total}: "Updating past days...".

GET /api/people/settings

Get Settings

GET /api/people/suggestions

Get Suggestions

GET /api/people/{group_id}

Get Person

name in required type
group_id path True integer

GET /api/people/{group_id}/day

One person's day: lines with the trackers behind each, gaps, left-behind, a footer.

name in required type
group_id path True integer
date query False string
timezone query False string

GET /api/people/{group_id}/left-behind

Open episodes plus those cleared in the last 24 hours.

name in required type
group_id path True integer

GET /api/people/{group_id}/now

Get Now

name in required type
group_id path True integer

PATCH /api/people/{group_id}

Patch Person

name in required type
group_id path True integer

Request body:

{
  "properties": {
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Name"
    },
    "kind": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Kind"
    },
    "color": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Color"
    },
    "icon": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Icon"
    },
    "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": "PersonUpdate"
}

POST /api/people

Post Person

Request body:

{
  "properties": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "kind": {
      "type": "string",
      "title": "Kind",
      "default": "person"
    },
    "member_ids": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Member Ids",
      "default": []
    },
    "roles": {
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "type": "object",
      "title": "Roles",
      "default": {}
    },
    "color": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Color"
    },
    "icon": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Icon"
    }
  },
  "type": "object",
  "required": [
    "name"
  ],
  "title": "PersonCreate"
}

POST /api/people/suggestions/accept

Post Accept

Request body:

{
  "properties": {
    "accept": {
      "items": {
        "$ref": "#/components/schemas/AcceptItem"
      },
      "type": "array",
      "title": "Accept",
      "default": []
    },
    "dismiss": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Dismiss",
      "default": []
    }
  },
  "type": "object",
  "title": "AcceptBody"
}

POST /api/people/{group_id}/day/send

Send that day's summary to the connected Telegram chat now.

name in required type
group_id path True integer

Request body:

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/DaySendBody"
    },
    {
      "type": "null"
    }
  ],
  "title": "Body"
}

POST /api/people/{group_id}/left-behind/{episode_id}/dismiss

Post Dismiss

name in required type
group_id path True integer
episode_id path True integer

PUT /api/people/settings

Put Settings

Request body:

{
  "properties": {
    "left_behind_alerts": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Left Behind Alerts"
    }
  },
  "type": "object",
  "title": "PeopleSettings"
}

PUT /api/people/trackers/{device_id}

Put Tracker

name in required type
device_id path True string

Request body:

{
  "properties": {
    "role": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Role"
    },
    "carry_weight": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Carry Weight"
    }
  },
  "type": "object",
  "title": "TrackerBody"
}

PUT /api/people/{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/channels/telegram/updates

"Find chat IDs": distinct chats seen in the saved bot's pending updates.

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
    },
    "telegram_targets": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Telegram Targets"
    }
  },
  "type": "object",
  "required": [
    "name",
    "channels"
  ],
  "title": "RuleCreate"
}

POST /api/alerts/rules/dry-run

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

PUT /api/alerts/channels/telegram/targets

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 /api/alerts/channels/webhook

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 /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"
    },
    "telegram_targets": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Telegram Targets"
    }
  },
  "type": "object",
  "title": "RuleUpdate"
}

providers

GET /api/providers

List Providers

auth

DELETE /api/auth/{provider}

S11/WP8: disconnect a provider. Same Origin guard as the sign-in

name in required type
provider path True string

GET /api/auth/apple/progress

Apple Progress

name in required type
job_id query False string

GET /api/auth/apple/status

The sheet's phase for one job, or for the newest job when none is named.

name in required type
job_id query False string

GET /api/auth/google/native/progress

Where the in-app sign-in stands; the dashboard card polls this.

GET /api/auth/google/progress

Google Progress

name in required type
job_id query False string

GET /api/auth/google/unlock/progress

Google Unlock Progress

name in required type
job_id query False string

GET /api/auth/status

Auth Status

GET /auth/google/begin

Begin Page

name in required type
state query False string

GET /auth/google/success

Success Page

name in required type
kind query False string

GET /auth/google/unlock/begin

Unlock Begin Page

name in required type
state query False string

POST /api/apple/accessories

Apple Accessories

POST /api/auth/apple/cancel

Cancel an Apple sign-in that is running or waiting for a code; nothing is saved.

Request body:

{
  "properties": {
    "job_id": {
      "type": "string",
      "title": "Job Id",
      "default": ""
    }
  },
  "type": "object",
  "title": "AppleJobBody"
}

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

Text me instead: Apple sends the code by text message to a number it offered.

Request body:

{
  "properties": {
    "job_id": {
      "type": "string",
      "title": "Job Id",
      "default": ""
    },
    "phone_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Phone Id"
    }
  },
  "type": "object",
  "title": "AppleTextBody"
}

POST /api/auth/google/cancel

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

POST /api/auth/google/helper/begin

Helper Begin

POST /api/auth/google/helper/folder

Copy the extension to its stable folder and return the path. Opens nothing:

POST /api/auth/google/helper/open-extensions

Legacy: open chrome://extensions in the user's Google Chrome. No 1.2 screen

POST /api/auth/google/helper/reveal

Legacy (1.1 CLI and older pages): copy the extension and reveal the folder.

POST /api/auth/google/helper/seen

Helper Seen

Request body:

{
  "properties": {
    "state": {
      "type": "string",
      "title": "State",
      "default": ""
    }
  },
  "type": "object",
  "title": "HelperSeenBody"
}

POST /api/auth/google/helper/token

Helper Token

Request body:

{
  "properties": {
    "state": {
      "type": "string",
      "title": "State",
      "default": ""
    },
    "oauth_token": {
      "title": "Oauth Token",
      "default": ""
    }
  },
  "type": "object",
  "title": "HelperTokenBody"
}

POST /api/auth/google/helper/unlock

Helper Unlock

Request body:

{
  "properties": {
    "state": {
      "type": "string",
      "title": "State",
      "default": ""
    },
    "vault_keys": {
      "title": "Vault Keys",
      "default": ""
    }
  },
  "type": "object",
  "title": "HelperUnlockBody"
}

POST /api/auth/google/helper/unlock-begin

Helper Unlock Begin

POST /api/auth/google/native/begin

Start an in-app sign-in (or unlock): a single-use state and the window's settings.

Request body:

{
  "properties": {
    "mode": {
      "title": "Mode",
      "default": "signin"
    },
    "if_idle": {
      "title": "If Idle",
      "default": false
    }
  },
  "type": "object",
  "title": "BeginBody"
}

POST /api/auth/google/native/cancel

Cancel the in-app sign-in: its state stops working at once.

POST /api/auth/google/native/classify

Did Google block the window? The shell sends a host, a path and a title class only.

Request body:

{
  "properties": {
    "state": {
      "title": "State",
      "default": ""
    },
    "host": {
      "title": "Host",
      "default": ""
    },
    "path": {
      "title": "Path",
      "default": ""
    },
    "title_class": {
      "title": "Title Class",
      "default": "unknown"
    }
  },
  "type": "object",
  "title": "ClassifyBody"
}

POST /api/auth/google/native/event

The window opened, is waiting, was blocked, closed or failed.

Request body:

{
  "properties": {
    "state": {
      "title": "State",
      "default": ""
    },
    "event": {
      "title": "Event",
      "default": ""
    },
    "reason": {
      "title": "Reason"
    }
  },
  "type": "object",
  "title": "EventBody"
}

POST /api/auth/google/native/token

The shell hands over Google's sign-in value once; Find+ exchanges it, never stores it.

Request body:

{
  "properties": {
    "state": {
      "title": "State",
      "default": ""
    },
    "oauth_token": {
      "title": "Oauth Token",
      "default": ""
    }
  },
  "type": "object",
  "title": "TokenBody"
}

POST /api/auth/google/native/unlock

The shell relays the unlock page's vault keys; Find+ keeps only the location key.

Request body:

{
  "properties": {
    "state": {
      "title": "State",
      "default": ""
    },
    "vault_keys": {
      "title": "Vault Keys",
      "default": ""
    },
    "account_hint": {
      "title": "Account Hint"
    }
  },
  "type": "object",
  "title": "UnlockBody"
}

POST /api/auth/google/open

Open Google's sign-in page (EmbeddedSetup) in the user's own Chrome.

POST /api/auth/google/start

Google Start

POST /api/auth/google/token

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

POST /api/auth/google/unlock/cancel

Google Unlock Cancel

Request body:

{
  "properties": {
    "job_id": {
      "type": "string",
      "title": "Job Id"
    }
  },
  "type": "object",
  "required": [
    "job_id"
  ],
  "title": "GoogleUnlockCancelBody"
}

POST /api/auth/google/unlock/start

Google Unlock Start

updates

GET /api/update/status

Where the update stands: found, downloaded, ready, or blocked by a failed attempt.

POST /api/update/apply

Verify the staged update and back up the database. Desktop shell only.

POST /api/update/check

Check GitHub (and the developer folder) now, in the background.

Clone this wiki locally