Annotations — Mark Deploys, Migrations, Incidents

An annotation is a labeled timestamp + description that shows as a vertical line on every time-series chart. Hovering reveals the description. Compare uses annotations as quick-pick anchors, which is how most teams use them — "diff before and after this deploy" without having to remember the exact timestamp.

Three types

Deploy (green line). Add automatically from your CI:

curl -X POST -H "Authorization: Bearer $MONPG_KEY"   -H "Content-Type: application/json"   -d '{"type":"deploy","title":"Backend v2.34.1","at":"'$(date -u +%FT%TZ)'"}'   https://api.monpg.app/api/v1/annotations

Migration (amber line). Mark schema migrations so you can correlate index and table changes with query plan shifts. Especially useful when a migration introduces a regression — the line on every relevant chart helps you see the cause.

Incident (red line). Mark when an outage starts and ends. Useful for retros, and for the "was this happening before or after that incident" question that always comes up.

Per-server vs. per-org

Annotations are org-wide by default — they show on every server's charts. Scope to a single server with the server_id field. Fleet-wide deploys benefit from org-wide; per-instance maintenance makes more sense scoped to one server.

Auto-import

GitHub deployments via webhook from your repo's deployment events become deploy annotations automatically. Linear and Jira incidents have bidirectional sync via API key. PagerDuty incidents create annotations on incident.triggered and close them on incident.resolved. Most teams set up the deploy webhook on day one and the others later as the use cases come up.