# LinkedMash API versioning and deprecation policy

The public LinkedMash REST API is versioned in the URL. The current stable contract uses the `/v1` prefix.

## Compatibility within v1

LinkedMash treats additions such as new optional fields, response properties, endpoints, and enum values as backward-compatible. Clients should ignore response fields they do not recognize.

Breaking changes such as removing or renaming fields, changing field types, or changing authentication requirements require a new major URL version.

## Deprecation notice

LinkedMash will announce a deprecated endpoint in the developer documentation and changelog at least 180 days before its planned removal, unless an urgent security or legal issue requires faster action.

Deprecated HTTP responses will include these standard signals:

- `Deprecation: true` to mark the endpoint as deprecated.
- `Sunset: <HTTP-date>` to state when the endpoint is scheduled to stop serving requests.
- `Link: <successor-url>; rel="successor-version"` when a replacement endpoint is available.

## Migration and removal

The migration guide will identify the replacement operation, request and response differences, and the final supported date. After the published Sunset date, LinkedMash may return `410 Gone` with the standard JSON error schema.

OpenAPI contract: https://www.linkedmash.com/openapi.json
Developer changelog: https://www.linkedmash.com/changelog
Developer portal: https://www.linkedmash.com/developers