Skip to Content
IntegrationVersioning & changelog

Versioning and changelog

Every Nebbos API surface is versioned in the URI prefix. Change classification (safe within a version, or requiring a new version) is contract-defined rather than discretionary. Deprecated versions remain in parallel operation for a minimum of twelve months before retirement.

Version prefix

Versions are URI-prefixed: /api/v1/, /api/v2/, and so on. Two consecutive major versions are supported concurrently. Deprecated versions continue to serve for at least twelve months following the deprecation announcement.

New endpoints are added under the current prefix. Existing endpoints continue serving under their prefix through the formal deprecation timeline specified in Deprecation policy.

Safe changes within a version

Within a version prefix, the following changes are contract-permitted:

  • Addition of new endpoints
  • Addition of new optional fields to request or response shapes
  • Addition of new enumerated values to fields explicitly declared “forward-compatible” in the OpenAPI specification
  • Addition of new request and response headers
  • Loosening of validation (accepting inputs previously refused)
  • Improvement of error messages while preserving the machine-readable code field

None of the above break a client that ignores fields not addressed in the client’s schema.

Changes that require a new version

The following changes ship as /api/vN+1:

  • Removal of an endpoint
  • Removal of a field from a response
  • Change to a field’s type or shape
  • Tightening of validation (refusing inputs previously accepted)
  • Change to the semantics of an existing operation
  • Change to an authentication requirement — for example, a Guest-tier endpoint elevated to Host tier

Version vN continues to serve for a minimum of twelve months from the date vN+1 is published.

Client implementations must ignore unknown fields. Client-side validation asserting that a response contains only known fields is contract-incompatible; the platform adds fields freely within a version.

Changelog

The dated version-change record is served at:

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

Each entry names the change, the affected endpoints, and the version in which it lands. Breaking-change entries carry a link to the corresponding migration guide referenced from Deprecation policy.