# Public API versioning

Every Public API path starts with its version: `https://api.costfluent.com/v1/...`. Version 1 is the stable version, and the [OpenAPI document](/openapi/public.v1.json) the [API reference](/api) 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](/api/webhooks).

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.json` on this portal, and every change to it lands with the release that ships it.

## Related

- [API reference](/api)
- [Data formats](/api/formats)
- [Errors](/api/errors)