47 lines
2.4 KiB
Markdown
47 lines
2.4 KiB
Markdown
# 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=...}`.
|