Versioning & deprecation

The contract in one paragraph: /api/v1 is stable. We add things; we don’t break things. If we ever must break something, you get machine-readable warnings on the wire, at least six months of notice, and a parallel version to migrate to — never a surprise.

Versioning scheme

The version lives in the URL path (https://entrybit.net/api/v1/…). There are no version headers to send and no date-pinned versions to track.

Non-breaking changes ship without a version bump and without notice. Build your client to tolerate them:

New endpoints, new optional request parameters, new scopes.
New fields in response objects — ignore fields you don’t recognize.
New values in fields that are documented as open sets (e.g. event types).

Breaking changes require a new version (/api/v2), which runs in parallel with the old one for the whole deprecation window. Breaking means: removing or renaming a field or endpoint, changing a field’s type or semantics, tightening validation on existing input, or removing a documented enum value.

How deprecation is announced

When an endpoint or version enters deprecation, three things happen, in order:

The changelog records it — the canonical, timestamped announcement, including the migration path.

Responses carry the standard headers so clients and agents detect it programmatically:

Header	Wire format	Meaning
`Deprecation`	`@1767225600` (RFC 9745 — a structured-field Date: `@` + Unix epoch)	When this surface became deprecated.
`Sunset`	`Sat, 1 Aug 2026 00:00:00 GMT` (RFC 8594 — an HTTP-date)	After this, it may stop working.
`Link: <…>; rel="sunset"`	RFC 8288	Where to read the migration notes.

(Yes, the two dates use different formats — that’s the two RFCs, not us.)

Registered app owners are emailed at the contact on their OAuth client / API key.

The gap between the Deprecation and Sunset dates is never less than six months for anything generally available.

Current status

Surface	Status	Sunset
`/api/v1`	GA, stable	none planned
OAuth 2.0 / OIDC endpoints	GA, stable — governed by the same policy	none planned

Nothing has ever been deprecated. When that changes, this table and the changelog change first.

What we ask of clients

Ignore unknown response fields (forward compatibility is a two-way deal).
Watch for Deprecation/Sunset headers if you build long-lived integrations — logging a warning when one appears is a five-line addition that buys you six months of calm.
Pin to /api/v1 explicitly; never scrape versionless paths.