Custom States

Custom monitor states let you extend the default state machine (up/down/degraded) with domain-specific states such as draining, canary, or rollback. States drive notification routing and status-page badges.

Endpoints

Method	Path	Description	Scope
GET	/api/v1/monitor-states	List custom states defined for the org.	monitors
POST	/api/v1/monitor-states	Create a custom state.	monitors
PATCH	/api/v1/monitor-states/{id}	Update.	monitors
DELETE	/api/v1/monitor-states/{id}	Delete. Fails if rules still reference it.	monitors
GET	/api/v1/monitors/{id}/rules	List the rule set applied to one monitor.	monitors
PUT	/api/v1/monitors/{id}/rules	Replace the rule set for one monitor.	monitors

Create a custom state

POST /api/v1/monitor-states

{
  "name": "draining",
  "label": "Draining",
  "severity": "warning",
  "color": "#f59e0b",
  "visibility": "private"
}

Field	Notes
name	snake_case, unique within the org.
severity	info, warning, critical; drives alerting.
visibility	private (internal only) or public (shown on status pages).

Apply rules to a monitor

PUT /api/v1/monitors/{id}/rules

{
  "rules": [
    {
      "when": {"http_status_in": [429, 503]},
      "set_state": "draining"
    },
    {
      "when": {"response_header_equals": {"x-canary": "true"}},
      "set_state": "canary"
    }
  ]
}

Rules are evaluated in order; the first match wins. If none match, the default state machine applies.

See Monitors → Custom States for the rule grammar.