API Reference

The ObsrvHQ API gives you programmatic access to baseline data, deployment event notifications, decision history, and rule management. The dashboard uses the same API: everything the UI shows is available via these endpoints.

Base URL: https://api.obsrvhq.com/v1

Authentication: all requests require a bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Rate limits: 1,000 req/min on Free, 10,000 req/min on Pro, 100,000 req/min on Scale. Rate limit headers are returned on every response: X-RateLimit-Remaining and X-RateLimit-Reset.

Endpoints

Method	Path	Description
GET	/v1/baselines	Fetch baseline envelope data for one or more metric series
POST	/v1/events/deployment	Notify ObsrvHQ of a deployment event to widen envelopes temporarily
GET	/v1/decisions	Query recent suppress vs. page decisions
POST	/v1/rules	Create or update a custom suppression rule
GET	/v1/workspace/status	Get workspace status, series count, and learning state

GET /v1/baselines

Returns the current baseline envelope for a metric series. Envelope is expressed as per-hour min/max for the current day-of-week.

Query parameters

Parameter	Type	Description
service	string	Service label value
metric	string	Metric name
window	string	Lookback window: 48h, 7d, 30d

Example request

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.obsrvhq.com/v1/baselines \
  ?service=checkout-api&metric=error_rate&window=7d"

Example response

{
  "series": "checkout-api.error_rate",
  "window": "7d",
  "envelope": {
    "monday": { "09:00": { "min": 0.001, "max": 0.012 }, "... ": "..." },
    "tuesday": { "09:00": { "min": 0.001, "max": 0.014 }, "...": "..." }
  },
  "sensitivity": 1.5,
  "last_updated": "2026-07-04T03:14:00Z"
}

POST /v1/events/deployment

Notifies ObsrvHQ of a deployment event. For the specified service, ObsrvHQ widens the baseline envelope for suppress_window_min minutes, then returns to learned baseline.

Request body

{
  "service": "checkout-api",
  "version": "v2.14.3",
  "environment": "production",
  "suppress_window_min": 15,
  "widen_multiplier": 2.0
}

GET /v1/decisions

Returns the most recent suppress vs. page decisions. Useful for SIEM integration and audit logging.

Query parameters

Parameter	Type	Description
limit	integer	Max records to return (default 100, max 1000)
from	ISO8601	Start timestamp
decision	string	Filter: suppressed or paged

POST /v1/rules

Create or update a custom suppression rule. Rules are evaluated in order; first match wins. See Alerting Rules for the full YAML schema.

{
  "name": "checkout-api-error-rate",
  "service": "checkout-api",
  "metric": "error_rate",
  "sensitivity": 2.0,
  "enabled": true
}