Skip to content

/v1 API deprecation policy

This page describes how we remove or change in an incompatible way what is published under /v1.

What counts as a breaking change

Breaking:

  • removing or renaming an endpoint, a field or a parameter;
  • changing the type, unit or meaning of a field;
  • requiring new input, or accepting less than before;
  • changing the authentication or the scopes an operation requires.

Not breaking, and may reach /v1 without this notice period: new endpoints, new optional response fields, new optional parameters and new values in open vocabularies (for example status or severity). Your client must tolerate unknown fields and values.

Our commitments

  • At least 12 months between the deprecation notice and the removal or breaking change.
  • An email to the person who created each affected active API key (neither revoked nor expired), if they are still an active member of the organisation, and to the administrators of the tenant that owns the key. Nobody receives it twice.
  • HTTP headers. When we retire something, responses from the affected endpoints will include Deprecation (RFC 9745) and Sunset (RFC 8594) with the removal date.
  • A changelog entry with the notice date and the removal date.

Security exception

A security fix may break a /v1 behaviour before 12 months have passed. When that happens we give as much notice as possible, email the same recipients, and state the reason in the changelog.

An exception announced before this policy

The Spanish values of the severity filter on GET /v1/alerts (critico, alto, medio, bajo) were announced for retirement before this policy existed. Their date, 2027-01-14, does not change. Move to the English values (critical, high, medium, low, info) before that date.

Effective date

This policy takes effect on the day this page is published; changes already decided before then ship under the previous regime: the 400 on unknown query parameters, and the retirement of the Spanish severity values.

Out of scope

Webhooks and rate limits are outside this policy; they have their own lifecycle.

How to stay informed

Follow the changelog and the «Contract changes» section of GET /v1/openapi.json, and watch the Deprecation and Sunset headers on responses.