# Versioning & deprecation

> How the EntryBit API is versioned, what stability we promise, and exactly how deprecations are announced: Deprecation and Sunset headers, a six-month minimum window, and the changelog as the canonical record.

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:

1. **The [changelog](/docs/api-reference/changelog/) records it** — the canonical, timestamped announcement, including the migration path.
2. **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.)

3. **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.