Skip to Content
IntegrationDeprecation policy

Deprecation policy

Version deprecations are announced on a scheduled timeline. Each deprecation carries a minimum twelve-month migration window, a per-endpoint migration guide, and continuously visible deprecation headers on responses served from the deprecated version.

Deprecation timeline

Day 0 — Announcement

The deprecation is recorded in the changelog with a shutdown date set at least twelve months forward. Every operator identity with active traffic against the deprecated version receives a written notice.

Migration window (Day 0 to T minus 30 days)

Responses from the deprecated version include a Deprecation header identifying the shutdown date and a Link header pointing to the migration guide for the specific endpoint. Migration is a client-shape change and does not require 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 minus 30 days)

A second written notice is issued. Response-header warnings are escalated. A subset of non-critical endpoints may serve ninety per cent of requests with an inserted one-hundred-millisecond delay to raise migration urgency for slow-migrating clients without producing failures.

Shutdown (T zero)

The deprecated version returns HTTP 410 Gone on every endpoint. The response body identifies the current version and the migration-guide URL.

{ "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 is accompanied by a per-endpoint migration guide identifying the prior request and response shapes, the new shapes, and an inline example pair for changes exceeding a simple rename. Guides are published at docs.nebbos.ai/migrations/<version>-<endpoint>.html and indexed on the version’s deprecation-announcement changelog entry.

SDK version pairing

Each SDK ships an accompanying migration. The SDK release adding support for the new API version is published on the deprecation-announcement date and remains available in parallel with the previous SDK major version through the entire deprecation window. See SDKs & client libraries for the version-pinning contract.

Endpoints not subject to deprecation

The audit-chain read path is not subject to deprecation. Once written, a chain entry is served indefinitely. Where the read-path shape requires evolution, the new shape is published alongside the existing shape; the prior shape does not retire.