Versioning & changelog

Every API surface is versioned in the URI prefix. What counts as a breaking change is a contract, not a judgement call. Old versions stay live long enough for a real migration — twelve months of parallel operation, minimum.

The version prefix

Versions are URI-prefixed: /api/v1/, /api/v2/, and so on. Two minor versions supported concurrently. Deprecated versions get 12 months of parallel operation before retirement.

Every new endpoint lands under the current prefix. Every existing endpoint stays serving forever under its prefix, until that prefix formally deprecates — see Deprecation policy for the timeline.

What’s safe within a version

Within a version prefix, the substrate may:

• Add new endpoints
• Add new optional fields to request or response shapes
• Add new enum values to fields with explicit “forward-compatible” enums (documented per-field in the OpenAPI spec)
• Add new HTTP headers, both request and response
• Loosen validation (make an invalid input newly-valid)
• Improve error messages while preserving the machine-readable code field

None of these break a client that ignores what it doesn’t know.

What forces a new version

• Removing an endpoint
• Removing a field from a response
• Changing a field’s type or shape
• Tightening validation (making a previously-valid input newly-invalid)
• Changing the semantics of an existing operation
• Changing an authentication requirement (e.g. a former Guest-tier endpoint now requiring Host)

Any of these ships as /api/vN+1. The old /api/vN continues to serve for at least twelve months from the day vN+1 lands.

Changelog

The dated list of every version change is served at:

https://api.nebbos.ai/api/v1/changelog        # human-readable
https://api.nebbos.ai/api/v1/changelog.json   # machine-readable

Entries name the change, the affected endpoints, and the version where it lands. Every breaking-change entry carries a link to the migration guide on the Deprecation policy page.