"description":"Return all configuration sections. Secret field values are masked (empty string).",
"operationId":"get_config_api_config_get",
"responses":{
"200":{
"description":"Successful Response",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ConfigResponse"
}
}
}
}
}
},
"put":{
"tags":[
"api-config"
],
"summary":"Put Config",
"description":"Save configuration updates.\n\n- Blank secret value keeps the existing stored value (no change).\n- Invalid values return 422 and nothing is written to the database.",
"description":"Send a test SMTP email using the current runtime settings.\n\nReturns a structured result indicating success or the category of failure.\nThree possible outcomes:\n- 200 { \"result\": \"success\", \"message\": ... }\n- 400 { \"result\": \"config-error\", \"message\": ... } (EmailConfigurationError)\n- 502 { \"result\": \"failed\", \"message\": ... } (EmailDeliveryError)\n\nSMTP credentials are never echoed in the response.",
"description":"Return location records with optional time-window filtering and pagination.\n\n- ``start`` / ``end`` are ISO8601 strings; filtering is **inclusive** on both bounds.\n- Results are ordered by ``datetime`` ascending.\n- ``limit`` is capped at 5000 to prevent full-table exports.",
"operationId":"get_locations_api_locations_get",
"parameters":[
{
"name":"limit",
"in":"query",
"required":false,
"schema":{
"type":"integer",
"maximum":5000,
"minimum":1,
"default":1000,
"title":"Limit"
}
},
{
"name":"offset",
"in":"query",
"required":false,
"schema":{
"type":"integer",
"minimum":0,
"default":0,
"title":"Offset"
}
},
{
"name":"start",
"in":"query",
"required":false,
"schema":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Start"
}
},
{
"name":"end",
"in":"query",
"required":false,
"schema":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"End"
}
}
],
"responses":{
"200":{
"description":"Successful Response",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/LocationsResponse"
}
}
}
},
"422":{
"description":"Validation Error",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/api/poo":{
"get":{
"tags":[
"api-data"
],
"summary":"Get Poo",
"description":"Return poo records ordered by timestamp descending (most recent first).\n\n``limit`` is capped at 1000 to prevent full-table exports.",
"operationId":"get_poo_api_poo_get",
"parameters":[
{
"name":"limit",
"in":"query",
"required":false,
"schema":{
"type":"integer",
"maximum":1000,
"minimum":1,
"default":100,
"title":"Limit"
}
},
{
"name":"offset",
"in":"query",
"required":false,
"schema":{
"type":"integer",
"minimum":0,
"default":0,
"title":"Offset"
}
}
],
"responses":{
"200":{
"description":"Successful Response",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/PooResponse"
}
}
}
},
"422":{
"description":"Validation Error",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/api/public-ip":{
"get":{
"tags":[
"api-data"
],
"summary":"Get Public Ip",
"description":"Return the current public IP state and recent history.\n\n- ``state`` is ``null`` if no IP check has been performed yet.\n- ``history`` is ordered by ``observed_at`` descending (most recent first).\n- ``limit`` applies to the history list and is capped at 1000.",
"description":"Update the non-PK fields of a single location record.\n\n- ``person`` and ``datetime`` identify the row (composite PK) and are immutable.\n- Only ``latitude``, ``longitude``, and ``altitude`` may be updated.\n- Omitted body fields are left unchanged.\n- Returns **404** if the PK does not exist.",
"description":"Delete the single location record identified by its composite PK.\n\n- Exactly one row is deleted; **404** if the PK does not exist.\n- No batch delete / truncate path is available.",
"description":"Update the non-PK fields of a single poo record.\n\n- ``timestamp`` is the PK and is immutable.\n- Only ``status``, ``latitude``, and ``longitude`` may be updated.\n- Omitted body fields are left unchanged.\n- Returns **404** if the PK does not exist.",
"description":"Delete the single poo record identified by its PK.\n\n- Exactly one row is deleted; **404** if the PK does not exist.\n- No batch delete / truncate path is available.",
"description":"Authenticate with username and password.\n\nOn success, sets an HttpOnly session cookie and returns the session user + CSRF token.\nOn failure, returns 401 with no cookie set.\nRepeated failures trigger exponential back-off (429 + Retry-After).\nNo X-CSRF-Token required (unauthenticated endpoint).",
"description":"Revoke the current session and clear the session cookie.\nRequires authentication and X-CSRF-Token header.\nReturns 204 No Content.",
"operationId":"post_logout_api_auth_logout_post",
"parameters":[
{
"name":"X-CSRF-Token",
"in":"header",
"required":false,
"schema":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"X-Csrf-Token"
}
}
],
"responses":{
"200":{
"description":"Successful Response",
"content":{
"application/json":{
"schema":{}
}
}
},
"422":{
"description":"Validation Error",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/api/auth/password":{
"post":{
"tags":[
"api-session"
],
"summary":"Post Change Password",
"description":"Change the current user's password.\nRequires authentication and X-CSRF-Token header.\nOn AuthPasswordChangeError returns 400 with a generic message.\nOn success, force_password_change becomes False (handled by the service).\nReturns 204 No Content.",
"description":"Generate a new pending TOTP secret, otpauth URI, and one-time recovery codes.\n\nThe secret is stored in the DB but TOTP is NOT yet enabled (totp_enabled stays\nFalse until the user confirms with POST /api/auth/totp/enable).\n\nRecovery codes are returned here as plaintext exactly once; their Argon2 hashes\nare persisted immediately so enable only needs to flip the enabled flag.\n\nRepeating this call replaces any prior pending secret and regenerates codes.\n\nRequires: session cookie + X-CSRF-Token.",
"description":"Enable TOTP by confirming with the current 6-digit code from the authenticator app.\n\nRequires a prior call to POST /api/auth/totp/setup (so that a pending secret\nexists). On success, totp_enabled becomes True.\n\nReturns 400 if the code is wrong or there is no pending secret.\nRequires: session cookie + X-CSRF-Token.",
"description":"Disable TOTP. The caller must provide exactly one of:\n- ``password``: the user's current login password, OR\n- ``code``: the current 6-digit TOTP code.\n\nOn success: totp_enabled=False, totp_secret cleared, all recovery codes deleted.\nReturns 400 if neither credential matches or neither is provided.\nRequires: session cookie + X-CSRF-Token.",
"description":"Return the current TOTP status for the authenticated user.\n\nResponse contains only ``{\"enabled\": bool}``.\nSecret and recovery codes are NEVER returned here.\nRequires: session cookie only (no CSRF — read-only).",
"description":"Disable TOTP by proving identity.\n\nExactly one of ``password`` or ``code`` must be provided."
},
"TotpEnableRequest":{
"properties":{
"code":{
"type":"string",
"title":"Code"
}
},
"type":"object",
"required":[
"code"
],
"title":"TotpEnableRequest",
"description":"The user confirms setup by providing the 6-digit TOTP code."
},
"TotpSetupResponse":{
"properties":{
"secret":{
"type":"string",
"title":"Secret"
},
"otpauth_uri":{
"type":"string",
"title":"Otpauth Uri"
},
"recovery_codes":{
"items":{
"type":"string"
},
"type":"array",
"title":"Recovery Codes"
}
},
"type":"object",
"required":[
"secret",
"otpauth_uri",
"recovery_codes"
],
"title":"TotpSetupResponse",
"description":"Returned once after a setup call.\n\n``secret`` and ``recovery_codes`` are **one-time plaintext values**.\nThey are never returned again by any subsequent API call.\nThe frontend must display and instruct the user to save them before confirming."
},
"TotpStatusResponse":{
"properties":{
"enabled":{
"type":"boolean",
"title":"Enabled"
}
},
"type":"object",
"required":[
"enabled"
],
"title":"TotpStatusResponse",
"description":"Minimal status response — never exposes secret or recovery codes."
