Versioning & deprecation

The /v1 compatibility policy, deprecation windows, and sunset headers.

Backfill’s public REST API version is the path prefix: /v1.

The OpenAPI info.version describes the generated specification package. It is not a request negotiation mechanism and should not be used to select behavior.

Compatibility rules

Non-breaking changes may ship within /v1:

New endpoints.
New optional request fields.
New response fields.
New list filters or sort options.
More specific validation errors for requests that were already invalid.
New event types for outbound webhooks.

Breaking changes require either a new API version or an explicit compatibility window:

Removing or renaming response fields.
Changing a field type.
Changing the response envelope for an existing endpoint.
Removing enum values or making optional request fields required.
Changing idempotency, auth, tenant isolation, or scope semantics in a way that can reject previously valid requests.

Enum additions are usually additive, but clients with exhaustive enum handling should treat unknown values as forward-compatible.

Deprecation headers

Deprecated endpoints, fields, aliases, or response shapes include these headers whenever the deprecation can be detected at response time:

Deprecation: true
Sunset: Wed, 30 Sep 2026 00:00:00 GMT
Link: <https://backfill.io/changelog#2026-07-02>; rel="deprecation"

Policy:

Default deprecation window: at least 90 days.
Widely used endpoints or envelope changes: target at least 180 days.
Security, legal, or data integrity fixes may have a shorter window or no window when continuing compatibility would be unsafe.

When a deprecated alias remains available — for example POST /v1/invoices/{id}/confirm, the legacy alias for POST /v1/invoices/{id}/mark_paid — responses, docs, and the OpenAPI reference prefer the replacement.

Future versions

The next breaking API version will use a new path prefix such as /v2. If a header-based preview or compatibility mode is introduced before /v2, it will be documented here and in the changelog before clients are asked to depend on it.

Errors →