ActivePush/docs/API.md

Panel API

Every endpoint except /api/session, /api/login, /api/setup, /metrics and /healthz requires a session (cookie ap_session); methods other than GET additionally need the X-CSRF-Token header (value from /api/session).

Method	Path	Description
GET	/api/session	session state, CSRF token, whether setup is required
POST	/api/setup	{token, username, password} - first administrator
POST	/api/login / /api/logout	sign in / out
POST	/api/password	{current, new} - change password (revokes other sessions)
POST	/api/sessions/revoke-others	sign out other sessions
GET	/api/overview	counters (devices_* = physical devices, users_* = mailboxes, partnerships_total), commands, runtime, database size
GET	/api/timeseries?minutes=60	minute buckets (up to 24 h)
GET	/api/stats/hourly?hours=168	hourly statistics from the database
GET	/api/live	requests in flight, push connections, recent events
GET	/api/events	Server-Sent Events: request event after every request
GET	/api/devices, /api/devices/{id}	partnerships (device x mailbox), details (folders, history)
POST	/api/devices/{id}/{action}	wipe, cancel-wipe, resync, reprovision, block, unblock, approve, remove, notes, recovery-password
GET	/api/users	mailboxes with device names and other mailboxes on the same device
GET/PUT	/api/settings	settings (secrets as __SET__; PUT accepts a full or partial document)
POST	/api/test/{imap,smtp,caldav,carddav}	{login, password, settings?} - connection test
GET	/api/logs?level=WARN&q=text&n=500	log buffer
GET	/api/audit	audit log
GET/POST	/api/lockouts, /api/lockouts/unlock	login lockouts

Health check

GET /healthz on both listeners returns ok (HTTP 200) when the process and the database respond, otherwise HTTP 503.

Prometheus

Set panel.prometheus_token, then:

- job_name: active-push
  metrics_path: /metrics
  authorization: { type: Bearer, credentials: "<token>" }
  static_configs: [{ targets: ["127.0.0.1:9091"] }]

Metrics: activepush_requests_total, errors_total, auth_failures_total, bytes_in/out_total, items_in/out_total, mails_sent_total, pings_active, imap_pool_connections, uptime_seconds, resident_memory_bytes, command_total{command=...}.