# 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:

```yaml
- 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=...}`.