Tase
Sign in
Docs
API reference

Deprecation policy

How Tase retires an endpoint, field or model: how deprecation is announced, what the deprecation window looks like, and what happens to traffic after sunset.

Deprecation is the process of retiring something that exists today. It is separate from versioning: versioning says what may change inside /v1, this page says what happens when we decide to take something away.

A deprecated surface is not a broken surface. It keeps working exactly as documented for the whole deprecation window. Deprecation is a signal to start migrating, not an outage.

Notice period

The minimum notice period between announcing a deprecation and the sunset date is [NOTICE PERIOD TO BE CONFIRMED]. Until that number is published here and in the API Terms, treat every sunset date announced in the changelog as the authoritative one for that specific surface.

How a deprecation is announced

Every deprecation is announced through all four of these channels on the same day, so no single missed email decides whether you find out.

  • Changelog entry: a dated entry on the API changelog naming the surface, the sunset date, and the replacement.
  • Documentation: the page describing the surface is marked deprecated and points at the replacement. Nothing is deprecated silently in the reference.
  • Response headers: calls that touch a deprecated surface may carry deprecation metadata on the response, so your logs can tell you before a human does.
  • Email to key owners: sent to the account owner of every key that actually called the deprecated surface in the recent past, plus a notice in the console.

Response headers on a deprecated surface

Where a deprecation is announced with headers, the response carries a Deprecation header and, once a removal date is fixed, a Sunset header with that date.

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://tase.app/docs/api-changelog>; rel="deprecation"

Make the header do the work

Log a warning whenever a response carries a Deprecation header, keyed by endpoint. That turns a policy you have to remember into an alert that finds you.

The lifecycle

  1. 1

    Announced

    The surface is marked deprecated in the docs and the changelog, and a replacement is named. Behaviour does not change on this day.
  2. 2

    Deprecation window

    The surface keeps working as documented. It stops receiving new features, and it may start returning deprecation headers. This is the window you migrate in.
  3. 3

    Sunset date

    The date, published in the changelog entry, on which the surface stops serving traffic.
  4. 4

    After sunset

    Calls fail rather than silently doing something different. A removed endpoint or model returns the same error you would get for one that never existed, and a removed request field is rejected as an invalid request. See the Errors page for the exact shapes.

Silence is not a reprieve

We do not fall back to a replacement on your behalf after sunset. Silently rerouting your traffic to a different model or a different endpoint would change your results without your knowledge, which is worse than a clear failure.

What is excluded

  • Anything labelled beta, preview or experimental. These carry no deprecation window and can change or disappear at any time. Do not put them on a critical path without a fallback.
  • Changes forced by security, safety or legal compliance, which can take effect immediately.
  • Surfaces that depend on an upstream provider: if the provider withdraws it, we cannot keep it alive past their date.
  • Undocumented behaviour. If it is not in these docs, it is not part of the contract, even if your integration currently relies on it.

What we ask of you

  • Keep a reachable account owner email on the account. It is the only channel we can push to you.
  • Send an explicit model id on every request so a model deprecation is a one-line change rather than an investigation.
  • Watch for deprecation headers in your logs, and check the changelog before a major release.
  • Migrate during the window, not on the sunset date. The window exists so that the switch is boring.

Related pages

  • Versioning: what /v1 guarantees and which changes need a new version.
  • API changelog: where deprecations and sunset dates are announced.
  • Errors: what a call to a removed surface returns.
  • Rate limits: the other operational contract worth reading before you scale up.
  • Legal: where the contractual terms governing API use are published.
VersioningAPI changelog