Public API versioning
What stays stable in version 1 of the Costfluent Public API, and how a change is announced before it reaches your integration.
Every Public API path starts with its version: https://api.costfluent.com/v1/.... Version 1 is the stable version, and the OpenAPI document the API reference renders is its contract.
What can change in version 1
Version 1 changes only by adding to it:
- New operations and new paths.
- New optional request fields and query parameters.
- New fields in a response, including in an error body.
- New values of a field the contract marks
x-extensible-enum, such as a provider key. - New event types on a webhook.
Write your integration to ignore a response field it does not know and to accept an unknown value of an extensible enum, so an addition never breaks it.
How a removal is announced
Removing or changing what version 1 already returns is a breaking change. Before one, the affected operations answer with a Deprecation header, and a Sunset header naming the date the change takes effect, at least six months ahead. A breaking change ships as a new version, v2, while version 1 keeps answering until its sunset date.
How it behaves
- The version is part of the path, never a header or a query parameter.
- The OpenAPI document is published at
/openapi/public.v1.jsonon this portal, and every change to it lands with the release that ships it.