---
updatedAt: 2026-08-24T11:36:50.000Z
agentTools:
  projectIndex: https://developers.zentag.ai/llms.txt
---

# Versioning & deprecation policy

How the Partner API versions changes and communicates deprecations.

## Versioning

The Partner API is versioned in the URL path: `/api/v1/partner`.

* **Additive, backwards-compatible changes** ship within the current major
  version (`v1`): new endpoints, new optional request fields, new response
  fields, and new webhook event types. Integrations must tolerate unknown fields.
* **Backwards-incompatible changes** ship under a new major version
  (`/api/v2/partner`). Examples: removing/renaming a field or endpoint, changing
  a type, tightening validation, or changing default behavior.

Every change is tracked in the [Changelog](../CHANGELOG.md), and the OpenAPI spec
is the single source of truth. CI runs Spectral lint and an `oasdiff` breaking-
change check on every change to the spec.

## Deprecation & sunset

When we deprecate an endpoint or field:

1. It is marked `deprecated: true` in the OpenAPI spec and annotated in the
   changelog with a replacement and timeline.
2. Responses include standard HTTP headers:
   * `Deprecation: true` (or an HTTP-date when deprecation takes effect)
   * `Sunset: <HTTP-date>` - the date after which the endpoint may be removed
   * `Link: <docs-url>; rel="deprecation"` - migration guidance
3. We provide a **minimum 90-day** window between announcing a sunset and removal
   for `v1` endpoints.

## Recommendations for integrators

* Pin to a major version and read the changelog before upgrading.
* Ignore unknown response fields rather than failing.
* Monitor for `Deprecation`/`Sunset` response headers and alert on them.