Use the Observe-Api-Version header

Observe-Api-Version lets a single endpoint serve more than one response shape, so the API can evolve without breaking callers who have not opted in. You choose a shape by naming a release date; the API gives you the behavior as of that date.

Rules

The value is a date in YYYY-MM-DD form. The spec enforces the pattern ^\d{4}-\d{2}-\d{2}$.
Omit the header and you get the original, stable response. This default never changes, so existing integrations keep working untouched and indefinitely.
Send a date on or after a version's date to get that version's behavior.
Send an earlier date, or an unparseable one, and you get the default response. This is not an error.
A version may need to be enabled for your account. If it is not, the request returns 403 rather than silently falling back.
Currently defined versions: 2026-08-04.

Example — default (no header)

curl -H "Authorization: Bearer $OBSERVE_TOKEN" \
  "https://api.observeinc.com/v1/monitors"

Returns the legacy bare array:

[
  { "id": "41007429", "name": "Checkout latency", "disabled": false },
  { "id": "41007430", "name": "Ingest lag",       "disabled": false }
]

Example — opting in to version 2026-08-04

curl -H "Authorization: Bearer $OBSERVE_TOKEN" \
     -H "Observe-Api-Version: 2026-08-04" \
  "https://api.observeinc.com/v1/monitors?limit=2&orderBy=name"

Returns the paginated envelope:

{
  "monitors": [
    { "id": "41007429", "name": "Checkout latency", "disabled": false },
    { "id": "41007430", "name": "Ingest lag",       "disabled": false }
  ],
  "meta": { "totalCount": 47, "limit": 2, "offset": 0 }
}

Example — using the CEL filter this version enables

filter must be URL-encoded. Unencoded, the expression below is label.matches("latency") && !disabled:

curl -H "Authorization: Bearer $OBSERVE_TOKEN" \
     -H "Observe-Api-Version: 2026-08-04" \
  "https://api.observeinc.com/v1/monitors?filter=label.matches%28%22latency%22%29%20%26%26%20%21disabled"

Guidance for callers

Pin the header to a specific date in your client rather than tracking "latest". That is the point of the mechanism: your integration only changes shape when you change the date.
Do not send the header at all if you want maximum stability and do not need the newer shape.
If you get an unexpected 403 on a request that works without the header, the version is not enabled for your account — contact Observe support rather than retrying.
If you send the header and still receive the legacy shape, check the date format; an unparseable value is silently treated as "no header".