Versioning and deprecation

The version is part of the URL. Every endpoint lives under https://www.inkly.so/api/v1, and the OpenAPI document describes that version.

A version only gains things. Inkly can add endpoints, optional request fields, response fields, and webhook event types to it without notice, so ignore response fields and event types you don't recognize. See unknown and new fields.

Removing or renaming an endpoint or field, changing a field's type, or making a parameter required only happens in a new version, such as /api/v2. When a new version ships, the one before it keeps working for at least 6 months.

At least 6 months before an endpoint or version stops working, Inkly emails the owners of every workspace that has an API key. From then on, its responses carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) with the date it stops working, so your code can log a warning before anything breaks.

The one exception is a security fix. If keeping something unchanged would put customer data at risk, Inkly changes it straight away and emails affected workspaces the same day.