API versioning

Fibric versions the API on two axes. The major version is pinned in the URL path, so an upgrade is never silent. Within a major, an optional dated revision header freezes additive-but-default-changing behavior. This page defines both mechanisms, states exactly what counts as breaking, and explains what the v1.0 stable contract does and does not promise.

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"

Within a major version, changes are additive only. You will see new fields, new endpoints, new enum members, and new optional parameters appear; you will never see a field removed, a type changed, a required parameter added, or an existing enum member disappear. A request that is valid today stays valid for the life of the major.

A breaking change ships as a new major, at a new path. The previous major is supported for at least twelve months after its successor is declared stable, and the sunset date is announced in the changelog the day the successor ships.

#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.
• Published revisions remain valid for the life of the major version.

#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://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.