Versioning - Usertick

The version is in the path: /api/public/v1. Within v1, changes are additive only:

new endpoints,
new optional parameters,
new fields in HTTP responses and webhook payloads,
new values where a field lists its values, such as a new event or a new error code.

To keep working through these changes, your code should ignore fields it doesn’t know and treat an unknown value as “other”. Within v1, nothing is renamed or removed without notice. Anything that will go away is announced at least six months ahead.

How a deprecation is announced

From the day of the deprecation, every HTTP response from the affected endpoint carries these headers:

Header	Example	Meaning
`Deprecation`	`@1798761600`	The Unix time it was deprecated (RFC 9745)
`Sunset`	`Sat, 03 Jul 2027 00:00:00 GMT`	When it stops working (RFC 8594), at least 182 days later
`Link`	`<https://docs.usertick.com/changelog/developers>; rel="deprecation"`	Where to read about the change and what replaces it, when there is a note

A client that logs a warning whenever an HTTP response has a Deprecation header learns about a change long before its sunset. Every deprecation is also listed in the developer changelog. No part of v1 is deprecated.

Webhook payloads

A webhook delivery is { id, type, createdAt, data }, where data is the Response resource, or the spike on theme.spiking. These four keys stay the same within v1. New fields can appear in data, and new event types can be added, so a receiver should check type, or the X-Usertick-Event header, before handling a delivery.