API policy

Melatone Skin Clinic API Versioning & Deprecation Policy

This page states how the Melatone Skin Clinic API is versioned and how any change that could break an integration is announced in advance, so agents and developers can rely on the surface they build against.

Versioning

The API is versioned in the URL path. The current version is /api/v1/.
Every response carries an X-API-Version header with the dated contract, currently 2026-08-21.
Additive changes (new endpoints, new optional fields) ship within v1 and never break existing clients.
Breaking changes ship under a new path prefix (/api/v2/). The previous version keeps running through the deprecation window below.

Deprecation & sunset

When a version is scheduled for retirement, it is signalled two ways at once:

The RFC 8594 Deprecation response header is set on the affected endpoints, carrying the date deprecation began.
The RFC 8594 Sunset response header carries the date after which the version stops responding.

The window between the Deprecation date and the Sunset date is at least six months. During that window the deprecated version continues to serve requests unchanged. A Link header with rel="deprecation" on every response points here.

HTTP/2 200
X-API-Version: 2026-08-21
Deprecation: Wed, 01 Apr 2026 00:00:00 GMT
Sunset: Sat, 03 Oct 2026 00:00:00 GMT
Link: <https://www.melatoneskinclinic.co.uk/api-versioning-policy>; rel="deprecation"

Today no version is deprecated, so no Deprecation or Sunset header is present; every response still carries the Link pointer to this policy.

Where this is documented

OpenAPI 3.1 spec: /openapi.json (the Deprecation and Sunset headers are defined under components.headers).
Developer portal: /developers
Agent guide: /llms.txt