Deprecations
We announce breaking changes here before they take effect, each with a date and what to do. A deprecated API version keeps working until its published sunset; a behavior we are retiring keeps working until its cutover. Two things are on the clock today.
Plain HTTP is going away
The API is served over HTTPS. Today a plain-HTTP request is redirected to its HTTPS URL. From 31 August 2026, plain-HTTP requests are refused outright, with no redirect to follow.
The reason is your credentials. A plain-HTTP request travels in cleartext,
including the API key or token in its Authorization header, before any
redirect can upgrade it. By the time the redirect arrives, anyone on the network
path has already seen it. Refusing the request closes that window instead of
papering over it.
What to do: send every request to https://. A client that follows
redirects works today and will simply stop being redirected, so point it at the
HTTPS URL directly and nothing changes on the cutover. If any part of your
integration still hardcodes http://, fix it before then.
v1 is deprecated
v1 is deprecated, with a sunset of 31 January 2027. It is the original Trefle-compatible surface; its replacement is v2. Plan your move before the sunset: the breaking change is authentication, and beyond that it is the base URL and a few response-shape adjustments. The migration guide walks through it, and Versioning explains how the versions relate.
Deprecation headers
When an API version is deprecated, its responses carry headers that say so, so a client can detect it in code instead of tracking dates by hand. Today that is v1; the same headers apply to any version we deprecate later.
Deprecationmarks that the version is deprecated, as a structured-field date (@<unix-seconds>) of when it took effect.Sunsetis the date the version stops working, as an HTTP date, for exampleSun, 31 Jan 2027 00:00:00 GMT.Linkcarries arel="successor-version"pointer to the replacement, so tooling can find it automatically.FC-Deprecation-Noticeis a plain-language sentence for logs and dashboards. Branch on the standard headers above, not on this text.