Versioning

The Trimline API uses date-based versions. When we make a change that could break existing integrations, we release it as a new version. Your integration keeps the behavior it was built against until you choose to upgrade.

Current version

2026-11-01

The URL prefix /v1 only changes for a complete redesign of the API, which we don’t expect. Within v1, versions are dates.

Choosing a version

Each API key is pinned to the latest version on the day it was created. To override that for one request, send the Trimline-Version header. This is useful when testing an upgrade.

curl https://api.trimline.tech/v1/renewals \
  -H "Authorization: Bearer $TRIMLINE_API_KEY" \
  -H "Trimline-Version: 2026-11-01"

Every response includes the version that was used in its own Trimline-Version header.

What counts as breaking

We’ll release a new version for:

• Removing or renaming a field, endpoint or parameter
• Changing a field’s type, or making an optional parameter required
• Changing the meaning of an existing value, such as a status

These changes are not breaking, and can ship to every version at any time, so build your integration to tolerate them:

• Adding new endpoints, optional parameters or response fields
• Adding new values to an enum, such as a new renewal status or event type
• Changing the order of fields in a response, or the length and format of IDs

During the beta

While the API is in beta we may need to change things faster than we’d like. We’ll still version every breaking change, keep the previous version working for at least 60 days, and post each change in the changelog with an email to everyone holding a live key. Once we reach general availability in June 2027, older versions will be supported for at least 12 months.