API versioning

This page proposes a two-axis versioning contract for a future Fibric API. No public v1.0 service or compatibility commitment exists today; the paths, revision headers, and support windows below are target examples.

Shared conventions are defined in the API overview. Changes ship with notes in the changelog.

#The path-pinned major version

Every request names its major version in the path:

curl https://api.fibric.io/v1/receipts \
  -H "Authorization: Bearer $FIBRIC_KEY"

The target versioning policy aims for additive changes within a major version. No public compatibility promise exists today.

A future support window, sunset notice, and migration policy would be published with an available service and confirmed contractually; this reference makes no twelve-month commitment.

#The Fibric-Version revision header

Some changes are additive by the letter of the rule but still change what a default does: a new default page limit, a new default field in a summary object, a stricter default validation. These ship as dated revisions. Pin one with the Fibric-Version header:

curl https://api.fibric.io/v1/plans \
  -H "Authorization: Bearer $FIBRIC_KEY" \
  -H "Fibric-Version: 2026-06-01"

Semantics:

• The value is a date, YYYY-MM-DD, naming a published revision. Unknown dates fail with 400 invalid_parameter; the message lists the valid revisions.
• Omitting the header selects the latest revision. Pin a revision in production so that behavior changes only when you change the pin.
• Every response echoes the revision that served it in a Fibric-Version response header, whether you pinned or not.
• Revisions never gate new endpoints or new fields; those are plainly additive and available to every revision. Revisions gate only changed defaults.
• Revision support windows would be published with an available service; no lifetime commitment is made here.

#What counts as breaking

#The v1.0 stable contract

The version pill on every page of this reference reads v1.0.0 · stable, and it means something specific. The surface documented here is what production tenants run against. The object model, the envelope-to-receipt chain, is frozen for the 1.x line. Within that contract:

• Field-level details may still be adjusted, with notice in the changelog, without a major-version bump.
• Endpoint groups newer than the core chain, such as webhook management and search, gain additive fields more often than the core chain.
• The additive-only rule above is the contract: within 1.x, changes are additive, and anything else ships behind a new major with changelog notice and a migration note.

In practice: pin Fibric-Version, read the changelog when it announces a change to an endpoint you use, and expect no surprises on the core objects.

#Deprecation policy

When an endpoint, parameter, or field is scheduled for removal in the next major, it is marked deprecated first, and the deprecation is observable in three places:

1. The changelog. Every deprecation is announced in the changelog with the replacement, the reasoning, and the earliest version that removes it.
2. This reference. The endpoint or field's documentation is annotated with the same information.
3. The response. Calls that touch a deprecated element carry a Deprecation response header and a Sunset header with the earliest removal date, per the corresponding IETF drafts, plus a Link header pointing at the changelog entry.

HTTP/1.1 200 OK
Fibric-Version: 2026-06-01
Deprecation: true
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://www.fibric.io/docs/changelog>; rel="deprecation"

Nothing deprecated is ever removed within its major version. Deprecation changes documentation and headers, not behavior.

#Discovering versions at runtime

Inspect the response headers on any authenticated request to see the revision that served you:

curl -sI https://api.fibric.io/v1/operators \
  -H "Authorization: Bearer $FIBRIC_KEY" | grep -i '^fibric-version'
# Fibric-Version: 2026-06-01

SDKs pin a revision per SDK release and surface it in their configuration; see SDKs. The CLI reports its pinned revision in fibric --version; see the CLI reference.

#Upgrade checklist

When a new revision or major version is announced:

1. Read the changelog entry. It names every changed behavior and the affected endpoints.
2. For a revision: set Fibric-Version to the new date in a staging environment, run your integration tests, then move the pin in production.
3. For a major: the twelve-month overlap means both paths serve simultaneously. Migrate route by route; there is no flag day.
4. Watch for Deprecation headers in your response logs as an early-warning signal that you depend on something scheduled to go.

#Errors

Neither is retryable unchanged; see retryability in Errors.