---
title: WatchFor API operations: versioning, deprecation and SLA
description: API versioning, the deprecation policy, rate limits, reliability guarantees, changelog and service status — what to build against in production.
canonical: https://watchfor.io/docs/api/operations
---

# WatchFor API operations: versioning, deprecation and SLA

API versioning, the deprecation policy, rate limits, reliability guarantees, changelog and service status — what to build against in production.

Everything an integration needs to run against WatchFor in production.

## Versioning

The API is versioned in the path: `https://watchfor.io/api/v1`.

- **Additive changes are not breaking** — new endpoints, new optional
  parameters and new response fields can appear within `v1` at any time.
  Parse responses leniently: ignore fields you don't recognize.
- **Breaking changes get a new version path** (`/api/v2`). `v1` keeps
  working alongside it.
- The machine-readable contract is the OpenAPI 3.1 spec at
  [`/openapi.json`](https://watchfor.io/openapi.json) — served from the
  same source as the API, so it is always current. Its `info` block links
  this policy (`x-deprecation-policy`, `x-sunset-policy`).
- The [MCP server](/docs/api/mcp), [A2A](/docs/api/a2a) and the SDKs are
  thin layers over `/api/v1` — they inherit this policy, and their tool
  and skill lists only ever grow within a major version.

## Deprecation policy

If an endpoint or field must ever be retired within a version, it will be:

1. announced in the [changelog](/changelog) (RSS at `/changelog/rss.xml`)
   and marked `deprecated: true` in the OpenAPI spec first,
2. kept working for **at least 90 days** after the announcement,
3. removed only in the next version path if the removal is breaking.

New endpoints, fields, MCP tools and A2A skills are also announced in
the changelog.

## Rate limits

- Per-plan request budget, applied **per API key** (per client + user for
  OAuth tokens). The current budget is `api_requests_per_minute` on
  [`GET /v1/plan`](/docs/api/plan).
- Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
  `X-RateLimit-Reset` and the IETF `RateLimit-*` equivalents.
- `429` responses add `Retry-After` (seconds). Paired with the
  `Idempotency-Key` header on creating POSTs, retries are always safe.
- MCP tool calls, A2A skills and `POST /v1/batch` sub-operations share
  the same budget.

Details and the per-request caps: [Errors & rate limits](/docs/api/errors).

## Reliability

- Checks run from multiple independent probe locations worldwide. A
  failure seen by one location shows as **Degraded**; a monitor is only
  **Down** — and an incident only opens — after confirmation from several
  locations (a few monitor types that observe a single global fact, such
  as domain expiry or heartbeat check-ins, are confirmation-exempt).
  Incident data from the API therefore reflects real outages rather than
  one bad network path.
- The control plane runs on EU infrastructure (GDPR applies) with
  redundant application replicas behind a load balancer; rate-limit and
  idempotency state is shared across replicas.
- Creating POSTs support the `Idempotency-Key` header (24-hour window)
  so network retries can never double-create.
- Write operations are recorded in the organization
  [activity log](/docs/organization/activity-log) with the API key (or
  OAuth user) as the actor — readable via
  [`GET /v1/activity`](/docs/api/activity).
- Metric-backed endpoints (uptime, check history) return
  `500 internal_error` with a "temporarily unavailable — retry shortly"
  message if the metrics store is unreachable, rather than partial data.

## CORS

All API responses carry `Access-Control-Allow-Origin: *` with
`GET, POST, PATCH, DELETE, OPTIONS` allowed and the `Authorization`,
`Content-Type` and `Idempotency-Key` request headers permitted, so
browser-side dashboards and edge functions can call the API directly —
including [idempotent writes](/docs/api#conventions). The preflight
answer is cached for 24 hours (`Access-Control-Max-Age: 86400`).

## Service status

Live platform status, incident history and maintenance announcements:
[status.watchfor.io](https://status.watchfor.io) — a WatchFor status page,
watching WatchFor.

Two machine-readable endpoints sit on the same host, so an agent or a script
never has to scrape the page — and can tell "WatchFor is down" apart from "the
thing WatchFor is watching is down":

| Endpoint | Returns |
| --- | --- |
| [`/status.json`](https://status.watchfor.io/status.json) | Current status and per-component detail, as JSON. CORS-enabled. |
| [`/badge.svg`](https://status.watchfor.io/badge.svg) | A live SVG badge. `?theme=auto` follows the reader's colour scheme. |

Embed the badge anywhere — a README, a docs page, your own footer:

```html
[![WatchFor platform status](https://status.watchfor.io/badge.svg?theme=auto)](https://status.watchfor.io)
```

Every status page you create works the same way; the full contract is in
[status page embeds](/docs/status-pages/embed).

## Support

- Security contact: [`/.well-known/security.txt`](https://watchfor.io/.well-known/security.txt)
- General: hello@watchfor.io
- Error semantics: [Errors & rate limits](/docs/api/errors)
- Changelog: [/changelog](/changelog)

---

Canonical page: https://watchfor.io/docs/api/operations · All docs: https://watchfor.io/docs · Site guide: https://watchfor.io/llms.txt