---
title: "Zerocost API Versioning and Deprecation Policy"
description: "How the Zerocost API is versioned, what can change within a version, and how deprecations and removals are announced (Deprecation and Sunset headers, 90 days notice)."
canonical: "https://zerocost.app/developers/versioning"
last_updated: 2026-10-15
---

# Zerocost API Versioning and Deprecation Policy

> How the Zerocost API is versioned, what can change within a version, and how deprecations and removals are announced (Deprecation and Sunset headers, 90 days notice).

## Versioning

- The API version is in the URL path (/api/v1) and in the API-Version response header.
- Within v1, changes are additive only: new endpoints, new optional parameters and new response fields. Clients should ignore fields they do not recognise.
- Breaking changes ship as a new version (/api/v2). The previous version keeps working alongside it.

## Deprecation and sunset

- Before a v1 endpoint or field is removed, its responses carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) at least 90 days before the removal date.
- Deprecated responses also carry a Link header with rel="deprecation" pointing at migration notes.
- Deprecations are announced on this page, in /auth.md and in the OpenAPI spec (operations are marked deprecated: true).

## Current status

- v1 is the current version. No endpoints are deprecated.