---
title: "API versioning & deprecation policy"
url: "/help/buuk/api-versioning-deprecation-policy"
updated: "2026-10-28T11:23:42.144Z"
---
# API versioning & deprecation policy

Buuk's public API (`/api/public/*`) is versioned so integrations — including AI agents — never break without warning.

## Current version

The current version is **1**. Select a version with the optional `Buuk-Version` request header; omit it to get the current version. Every response carries a `Buuk-Version` header naming the version that served it. Requesting an unsupported version returns `400 unsupported_api_version`. URLs never change between versions.

## What we never change within a version

We don't make breaking changes to a published version. These are **not** breaking, and can ship at any time:

- new endpoints
- new optional request parameters
- new fields in responses
- new enum values

Clients should ignore response fields they don't recognise.

## Deprecation and removal

We give **at least 6 months' notice** before an endpoint, parameter or field is removed or changed incompatibly. During that period:

- the operation is marked `deprecated: true` in the [OpenAPI spec](/openapi.json)
- the change is announced in the changelog
- responses from the deprecated operation include a `Deprecation` header (RFC 9745) with the date it was deprecated, and a `Sunset` header (RFC 8594) with the date it will be removed

Nothing is deprecated today.

## Safe retries

Write requests (`POST /api/public/articles`, `PATCH /api/public/articles/{idOrSlug}`) accept an optional `Idempotency-Key` header. Retrying with the same key and body within 24 hours returns the original response instead of repeating the write.