What we promise and how we deprecate
Root Herald's wire protocol is versioned and additive-only within a major version. Here is exactly what we won't break inside v1, when we will deprecate something, and how to read the OpenAPI document that defines the contract.
Versioning model
The API base path is /api/v1/. Within v1, we follow a strict additive policy:
- New fields in responses: allowed, may ship at any time.
- New endpoints: allowed, may ship at any time.
- New optional request fields: allowed.
- New required request fields: never shipped inside v1. Always v2.
- Removing or renaming response fields: never inside v1.
- Changing the meaning of an existing field: never inside v1.
The schema contract
The machine-authoritative contract is the OpenAPI document itself, served at /api/v1/openapi.json — it is the source of truth for every endpoint, request, and response field. Pin your SDK to a wire version and diff against that document to detect server-side schema drift. For the error model, see the error-codes page: errors are stable string identifiers, not numeric codes.
Deprecation notice & windows
Every wire-protocol deprecation gives you a 90-day window (measured from announcement to removal) regardless of tier. Higher tiers just add notification channels:
| Tier | Deprecation window | Notification channel |
|---|---|---|
| Free | 90 days | Dashboard banner · email · blog |
| Pro | 90 days | Dashboard banner · email · blog |
| Business | 90 days | All of the above + shared Slack ping |
| Enterprise | 90 days | All of the above + dedicated CSM walkthrough |
Headers that signal deprecation
When you hit a deprecated endpoint or pass a deprecated field, we add the standardDeprecation and Sunset response headers (RFC 8594, RFC 9745):
HTTP/1.1 200 OK
Deprecation: Tue, 17 Nov 2026 00:00:00 GMT
Sunset: Mon, 15 Feb 2027 00:00:00 GMT
Link: <https://rootherald.io/changelog/2026-11-deprecation>; rel="deprecation"
Content-Type: application/json
…Wire these into your observability stack. SDKs emit a one-time warning to stderron first encounter; we don't spam, but we do tell you.
This isn't a promise that the platform never changes: it's a promise about how and when. New features ship regularly; what they don't do is silently change existing behavior or remove fields you depend on.