Tirth API · Guide
Versioning
What changes without a new version, and the notice before a version retires.
The version is in every path: /v2. Within a version, the API only grows, so code written against it keeps working.
Changes that keep the version
These are made within /v2 and listed in the changelog:
- a new operation or a new path;
- a new optional field in a request, or a new field in an answer;
- a new error code, a new event type or a new enum value;
- a new optional header or query parameter.
Write your code so these never break it:
- ignore fields you do not know in answers and in webhooks;
- treat an unknown error
codeby its HTTP status; - treat an unknown event
typeor status as something to read withGET /v2/bookings/{id}, not as a failure.
Error codes are never renamed or removed within a version.
Breaking changes
A change that could break working code, such as removing or renaming a field, an operation or a code, needs a new version. Tirth's build checks every change to /v2 against the published API description and refuses one that would break it.
Retiring a version
- A version is retired only with at least 12 months' notice.
- A version is never retired during a code freeze.
- The notice is posted in the changelog and its RSS feed.
The old /v1/partner API is already retired: it answers 410. Applications that used it move to /v2.
Webhook versions
Each webhook carries api_version, the date its shape was set, such as 2026-11-03. Keep it with the events you store.
