Skip to Content
IntegrationDeprecation policy

Deprecation policy

A deprecation is a schedule, not a surprise. Every version deprecation is announced at least twelve months before shutdown, carries a per-endpoint migration guide, and is visible in every response header while the deprecation window is open.

The deprecation timeline

Day 0 · Announcement

A version deprecation lands in the changelog with a target shutdown date at least twelve months out. Every operator with active traffic on the deprecated version gets an email.

Migration window (Day 0 → T−30)

Every response from the deprecated version includes a Deprecation header naming the shutdown date, and a Link header pointing at the migration guide for the specific endpoint. Migration is a shape-change on the client, not a substrate-side change.

HTTP/1.1 200 OK
Deprecation: version="v1"; date="2027-11-01T00:00:00Z"
Link: <https://docs.nebbos.ai/migrations/v1-v2-tasks.html>; rel="deprecation"

Final notice (T−30 days)

A second email lands. The response headers escalate the warning; some non-critical endpoints may begin serving 90% of requests with an inserted 100ms delay so slow-migrating clients feel the pressure without breaking.

Shutdown (T−0)

The deprecated version returns HTTP 410 Gone on every endpoint. The body of the 410 names the current version and the migration guide URL. No silent 404, no ambiguous 500 — the shutdown is loud.

{
  "code": "version.retired",
  "message": "API version v1 was retired on 2027-11-01. Migrate to v2.",
  "current_version": "v2",
  "migration_guide": "https://docs.nebbos.ai/migrations/v1-v2.html"
}

Migration guides

Every breaking change ships with a per-endpoint migration guide. The guide names the old shape, the new shape, and (where the change is more than a rename) an inline example of a request-response pair on each side. Guides live under docs.nebbos.ai/migrations/<version>-<endpoint>.html and are indexed on the version’s deprecation-announcement changelog entry.

SDK version pairing

Each SDK ships an alongside migration: the SDK release that adds support for the new API version lands on the deprecation-announcement day, and stays coexistent with the previous SDK major version for the entire deprecation window. See SDKs & client libraries for the pinning rules.

What never deprecates

The audit-chain read path. Once a chain entry is written, the endpoint that reads it stays live — the chain is an infinite-lifetime record. If an audit-chain endpoint shape needs to evolve, the new shape ships alongside; the old shape does not retire.

Versioning & changelogWebhooks