API Reference
Authentication
Obtain a bearer token from the pgSentinel UI or create one via SQL. Include the token in the Authorization header for every request.
Create API token
INSERT INTO pgsentinel.api_tokens (name, token_hash, created_by)
VALUES ('terraform', crypt('my-token', gen_salt('bf')), 'admin');Example request
curl -H "Authorization: Bearer <token>" \
https://pgsentinel.example.com/api/v1/poolsTokens inherit the roles of the issuing user. Rotate credentials regularly and revoke via DELETE /api/v1/tokens{id} when compromised.
System Health
/healthReturn application health, service status, and build metadata.
/statusDetailed runtime stats (uptime, memory usage, connected pools).
Pools & Clients
/poolsList pgBouncer pools with current usage, wait queue, and limits.
/pools/{pool}/clientsActive clients within a pool including state, duration, and backend.
/pools/{pool}/reloadReload pool configuration from pgBouncer admin console.
Metrics
/metricsAggregated metrics per pool (TPS, response time, saturation).
/metrics/timeseriesTime-series data for graphing or external dashboards (Prometheus-friendly).
Alerts
/alertsList alert rules currently active in pgSentinel.
/alertsCreate or update an alert rule (queue length, latency, errors).
/alerts/testFire a test notification to validate webhook integrations.
Pagination & Query Parameters
Collection endpoints support ?page=, ?page_size=, and ?sort= (e.g. sort=-latency). Use ?from=&to= for time range filters on metrics endpoints.
Webhooks & Integrations
Configure Slack, PagerDuty, or custom webhooks by POSTing to /webhooks. Each webhook can subscribe to alert categories (queue, latency, errors) and includes signed payloads for tamper detection.