Versioning

/v1 is the current version.

What can change

• Additive changes ship as they land. A new field on a response, a new optional request field, a new route, a new error code. The reference and these pages change with them, and openapi.json is always current.
• New enum values can appear. Your client must tolerate an unknown value rather than crash on it. An unhandled new enum value is the most common way an integration breaks on an API that never made a breaking change.

Deprecated routes

A route on its way out answers with Deprecation and Sunset response headers, plus Link: rel="deprecation", so code that logs them sees it. The changelog and its feed (changelog.xml) say what changed and when.

RFC 9745 for Deprecation, RFC 8594 for Sunset.

The machine contract

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

OpenAPI 3.1, generated from the same schemas that validate the requests rather than maintained 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. See errors and retries.
• Follow next_cursor. Never construct or parse a cursor.
• Send Idempotency-Key on every write, so a retry after a timeout is safe.

See errors and retries for the last two in practice.