API stability

Versioning

Endpoints live at /api/<resource> — that path is the v1 baseline. Additive changes ship in place:

• New endpoints.
• New optional request fields and new response fields.

Breaking changes are announced via email to active API-key holders ahead of any rollout, with overlap windows long enough for callers to migrate.

Stable surface

These are part of the public contract:

• HTTP method + path of every endpoint listed in the API reference.
• The error field in error bodies (the short code: Validation failed, Unauthorized, etc.).
• HTTP status codes documented per operation.
• The bearer-token auth scheme and ug_live_ key prefix.

Unstable / explicitly-not-promised

• The exact text of message in error bodies.
• The order of fields in responses.
• Performance characteristics (latency, body size).
• Field shape inside notification_channel.config is opaque — its keys depend on type (slack/discord/webhook → webhook_url; telegram → chat_id; email → email_addresses).
• Internal endpoints under /api/internal/* (worker → web app communication, not authenticated with API keys).

Pagination

List endpoints return all records the caller has access to, with implicit upper bounds (GET /incidents returns up to 50 most recent). When cursor-based pagination ships, it'll arrive as new optional limit and cursor query parameters — current responses keep their shape, callers opt in when they need it.

Idempotency

PUT operations are idempotent — re-issuing the same payload is safe. DELETE is also idempotent: a second delete returns 404 rather than erroring on already-gone state.

For POST operations (creates), if a network failure leaves you unsure whether the call succeeded, follow up with the matching GET and dedupe on the natural key (e.g. name + url for monitors, slug for status pages). An Idempotency-Key header is on the way for the create endpoints where it matters.

Deprecations

When a field or endpoint is deprecated:

1. It's marked deprecated in the API reference.
2. The deprecation is announced via email to active API-key holders.
3. The deprecated surface keeps working — exact sunset window is communicated alongside the announcement.

Reporting issues

Email support@obzerv.xyz with the failing endpoint, response body, and the date/time of the call. For suspected breaking changes, also include the date you first observed the regression.