API Versioning - Data API

Fiskil's Data API uses major-version numbering. Clients select a single major version — v1 or v2 — per request. Inside a major version, Fiskil ships non-breaking changes (new optional fields, new enum values, new endpoints, and bug fixes) automatically and without requiring any client update.

Breaking changes are never shipped inside a major version. They only appear in a new major version that you opt into on your own schedule.

Live major versions

v1 and v2 are both live. v2 is the current major version for new accounts. v1 is maintained for existing integrations — see Support timeline below.

Selecting a version

There are two places a version gets chosen. The per-request header always wins.

Per-request: `X-Fiskil-Version` header

Send the header on any request to override your team's Console default for that call:

curl https://api.fiskil.com/v1/banking/accounts \
  -H 'X-Fiskil-Version: v2' \
  -H 'Authorization: Bearer {token}'

Use v1 or v2 exactly — the literal major label. Do not send full semantic versions like 1.0.0 or 2.0.0; those will not be accepted.

Team default: Console pinned version

Every team has a pinned version in Console. Requests without X-Fiskil-Version use this pin. New accounts are pinned to the latest live major version at sign-up.

Console upgrades are one-way

Moving your Console pin from v1 to v2 cannot be reversed in settings. Always validate v2 in production with the X-Fiskil-Version: v2 header first, then flip the pin.

The /v1/ in the URL is not the API version

Every request path starts with /v1/ as a URL namespace. The API version is selected by the X-Fiskil-Version header or your Console pin, never by the URL segment.

What counts as a breaking change

A change is breaking (new major version only) if it could cause correctly written client code to fail. Anything else is non-breaking and ships inside the current major version.

Change	Classification
Removing a response field	Breaking
Changing the type of a response field (e.g. number → string)	Breaking
Replacing a nested object with an array (or vice versa)	Breaking
Adding a required request parameter	Breaking
Removing or renaming an endpoint	Breaking
Adding a new optional request parameter	Non-breaking
Adding a new response field	Non-breaking
Adding a new value to a response enum	Non-breaking
Adding a new endpoint	Non-breaking
Bug fixes that align behaviour with documented contract	Non-breaking

Parse responses defensively: treat unknown fields as safe to ignore and unknown enum values as valid. That lets non-breaking additions reach your integration without code changes.

Version switcher in the docs

The version switcher in the top navigation changes which major version's API reference you see in these docs. It affects documentation only — it does not send anything to api.fiskil.com and does not change your team's runtime behaviour. Runtime behaviour is controlled by the X-Fiskil-Version header and your Console pin.

Upgrading to a new major version

The same workflow applies to any future major version. It minimises blast radius by keeping production on the old version while you validate the new one.

Pin production to your current version

Add X-Fiskil-Version: v1 to every production request. This freezes your current response shape so a later Console change can't surprise you.

Read the upgrade guide

Each major release has a dedicated migration doc listing every breaking change. For v1 → v2, see the Upgrade to v2 guide.

Test the new version in production with the header

Send X-Fiskil-Version: v2 on a subset of real production traffic and verify the affected endpoints and downstream parsers before committing.

Flip the Console pin

Once you've validated v2 end-to-end, update your team's pinned version in Console. You can now drop the explicit header if you want — requests default to the pin.

Support timeline

Each major version is supported for at least 12 months from release. When a major version is scheduled for deprecation, the timeline is announced in the Changelog with enough notice to upgrade.

Non-breaking updates inside a live major version are announced in the changelog but require no action.

Changelog — release notes for each major version.
Upgrade to v2 — concrete migration from v1 to v2.
API Reference — per-endpoint shapes. Use the top-nav version switcher to compare v1 and v2.