what can change under you, and how you find out

Versioning

What is stable

/v1 is stable once announced. Within it:

Additive changes ship without a bump — a new field on a response, a new optional request field, a new route, a new error code. They appear in the changelog.
New enum values are announced 30 days ahead. Your client must tolerate an unknown value rather than crashing on it. This is the single most common way an integration breaks on an API that never made a breaking change.
Breaking changes go to /v2, and /v1 keeps serving for at least six months.

How notice is delivered

Three channels, because each one reaches a different reader:

channel	reaches
`Deprecation` and `Sunset` response headers, plus `Link: rel="deprecation"`	code that logs them
the Atom feed	the person who has to act
email to a registered client's `contacts`	best-effort, if you gave one

Subscribe to the feed. The headers reach your logs; the feed reaches you.

RFC 9745 for Deprecation, RFC 8594 for Sunset.

The machine contract

bash

curl -s https://api.inittasks.com/openapi.json

OpenAPI 3.1, generated from the same schemas that validate the requests — not a hand-maintained document beside them. Every response carries Link: <…/openapi.json>; rel="service-desc".

If the reference pages here and the document disagree, the document wins: these pages are a build artefact, and a deploy can be newer than the docs you are reading.

Writing a client that survives

[✓] Ignore unknown response fields; never validate a response with a closed schema.
[✓] Treat an unknown enum value as "something new", not as an error.
[✓] Branch on the problem type URI, never on detail or on the status alone — several codes share a status.
[✓] Follow next_cursor; never construct or parse a cursor.
[✓] Send Idempotency-Key on every write, so a retry after a timeout is safe.