Versioning and deprecation

Dated API versions, what we count as a breaking change, and how long you get before anything goes away.

Code you write against Tickwire today keeps working. Breaking changes to the native API ship only under a new dated version that you opt into, and nothing is removed without at least six months of notice, in headers and in the API changelog.

Which surfaces are versioned

The compatible surfaces exist so that code written for these API styles runs unchanged. Their request and response shapes are fixed and are never changed by a Tickwire version. We may add fields there when the API style does; we never rename, remove or retype one. Tickwire-Version is ignored on those routes and not echoed.

Dated versions

Versions are dates: YYYY-MM-DD. The current and only version is 2026-09-25.

• Send Tickwire-Version: 2026-09-25 on a /v1 request to choose a version for that call.
• Without the header, the call uses your organisation’s pinned version (see below).
• Every /v1 response echoes the version that served it in Tickwire-Version, errors included.
• A malformed or unknown version is refused with 400 invalid_api_version, listing the supported versions in metadata.supportedVersions. Nothing is forwarded.

Sending the header explicitly is the safest choice: your code then never changes behaviour when the pin does.

Your organisation’s pin

Every organisation is pinned to one version. A /v1 call without Tickwire-Version is served in that version, so a new version never changes how your existing code behaves until you move the pin.

• A new organisation is pinned to the latest version on the day it is created.
• Organisations created before pins existed are pinned to 2026-09-25.
• The header always wins: a call that sends Tickwire-Version gets that version, whatever the pin.

Read the pin with any API key or API token:

curl https://api.tickwire.io/v1/api-version -H "X-API-Key: $TICKWIRE_KEY"

{"apiVersion": "2026-09-25", "latestVersion": "2026-09-25", "supportedVersions": ["2026-09-25"]}

Upgrading the pin

Test your code against the new version first by sending Tickwire-Version: <new date> on its calls. When it passes, move the pin, either in the dashboard (Settings → API version, owners and admins) or with the API:

curl -X POST https://api.tickwire.io/v1/api-version \
  -H "X-API-Key: $TICKWIRE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Actor: deploy-bot" \
  -H "X-Reason: upgrade after the integration tests passed" \
  -H "Content-Type: application/json" \
  -d '{"apiVersion": "2026-09-25"}'

{"apiVersion": "2026-09-25", "previousApiVersion": "2026-09-25", "changed": false,
 "latestVersion": "2026-09-25", "supportedVersions": ["2026-09-25"]}

• It needs a full API key, or a full-access API token with the writer role. Keys are issued by owners and admins; in the dashboard only owners and admins see the upgrade button.
• Idempotency-Key, X-Actor and X-Reason are required (400 missing_header otherwise; percent-encode a non-ASCII value). Repeating the key returns the first answer; the same key with a different body is 409 idempotency_conflict.
• Every change is written to your organisation’s audit log as api_version.pinned, with the old and new version, the actor and the reason.
• An unknown or malformed version is 400 invalid_api_version. A version older than the oldest supported one is 400 api_version_unsupported. The pin is unchanged in both cases.
• You can move the pin back to an older version while it is still supported.
• The new pin applies to calls without the header within 30 seconds.

What counts as breaking

Breaking (only in a new dated version):

• removing or renaming an endpoint, a field, a query parameter or an enum value;
• changing a field’s type, format, units or meaning (for example broker time to UTC);
• making an optional request field required, or adding a new required field;
• changing a success status code, an error code, or when an error is returned;
• changing default values, sort order or pagination behaviour;
• tightening validation so that a request accepted before is now refused.

Not breaking (can ship at any time, in every version):

• new endpoints, new optional request fields and parameters;
• new response fields (ignore fields you don’t know);
• new enum values in fields documented as open-ended, new error codes for new failure modes, new webhook event types (ignore types you don’t know);
• changes to the text of message, to docUrl targets, to the order of JSON keys, or to the length and format of opaque ids;
• raising a rate limit, or adding response headers.

Security fixes are the one exception: if a behaviour is unsafe, we may change it without a new version, and we’ll say so in the changelog the same day.

Deprecation

When an endpoint, a field or a whole version is scheduled to go away:

1. It is announced in the API changelog with the date it stops working.

2. From that day, every response from it carries:

   Header	Standard	Example
   Deprecation	RFC 9745	Deprecation: @1790812800 (when it was deprecated, Unix seconds)
   Sunset	RFC 8594	Sunset: Sat, 01 May 2027 00:00:00 GMT (when it stops working)
   Link	RFC 8288	Link: <https://tickwire.io/docs/changelog-api>; rel="deprecation"

3. The sunset is at least six months after the deprecation is announced. A version stays supported for at least six months after the next version is published, and in practice until usage has moved.

4. We contact organisations we still see calling a deprecated route before its sunset.

Watch for Deprecation in your logs or tests: it is the earliest warning you’ll get.

Changelog

API changelog lists every version and every deprecation, newest first. The general changelog covers the docs and the product.