Versioning policy

Pin a dated API version per request. Breaking changes ship only in a new version, with at least 90 days of notice.

Applies to

v1 + v2

Pin a version

1# Placeholder: Fernway is a fictional API.
2curl https://api.fernway.example/v2/messages \
3  -H "Authorization: Bearer $FERNWAY_API_KEY" \
4  -H "Fernway-Version: 2026-10-01"

Major and dated versions

The URL carries the major version (v1, v2). Inside a major version, the Fernway-Version header pins a dated release so your integration only changes when you choose.

What counts as breaking

Removing or renaming a field, endpoint or enum value.
Changing a field type or making an optional field required.
Changing default behaviour, such as pagination size.

Adding endpoints, optional fields, enum values or webhook event types is not breaking. Write clients that ignore fields they do not know.

Deprecation timeline

Deprecations are announced in the changelog and by email at least 90 days ahead. Retired major versions return 410 Gone.

Placeholder API

Fernway is a fictional product used to show how this template works. Replace these docs with your own in the CMS.

← Idempotency

Message statuses →