Skip to main content

Changelog and deprecation policy

We publish every API change in the in-product changelog at /manage/developer/docs. This page explains the change types, the deprecation timeline, and how to subscribe.

Change types​

TypeMeaning
addedNew endpoint, new field in a response, new webhook event type
changedBehavior of an existing endpoint changed (non-breaking)
deprecatedEndpoint or field still works but will be removed in a future release
removedEndpoint or field no longer available
fixedBug fix with no contract change (informational)
securitySecurity-relevant fix - read carefully, may require integration changes

Versioning policy​

The URL path prefix (/api/v1/) is the major version. Within v1:

  • Additive changes (new fields, new event types, new endpoints) do not require a version bump. We add fields freely.
  • Breaking changes (removing or renaming fields or endpoints) ship under a new major version (/api/v2/) with at least 90 days overlap.
  • Event payload versions are tracked per (event_type, api_version) pair. The api_version string in the webhook envelope identifies the exact data shape contract.

Deprecation timeline​

When we mark an endpoint or field deprecated:

  1. We publish a deprecated changelog entry naming the affected surface and a recommended migration path.
  2. The in-product changelog at /manage/developer/docs shows a "Deprecated" badge on the entry.
  3. We give you at least 90 days of overlap before removal.
  4. The deprecated entry includes a target removal date.
  5. On the removal date we publish a removed entry and the endpoint returns 410 Gone (or the field is omitted from responses).

We email the agency owner contact address at least 30 days before any removal. If your contact email is not current, update it in /manage/settings/profile.

Reading the changelog​

The in-product feed at /manage/developer/docs is the canonical view - infinite-scroll list, filterable by change type and date range.

The GET /api/v1/agency/changelog endpoint returns the same data programmatically:

GET /api/v1/agency/changelog?limit=20&change_type=deprecated
Cookie: better-auth-session=...
X-CSRF-Token: ...

Note: this endpoint is authenticated via session cookie (it is part of the developer settings UI API), not by API key.

Subscribing to changes​

We are evaluating programmatic subscription options for the v1.1 roadmap:

  • RSS feed at https://docs.valara.cloud/api-reference/developer-settings/changelog.rss
  • A changelog.entry_added webhook event type

Until those ship, check /manage/developer/docs or this page for changes. Critical security entries will always trigger a direct email to the agency owner.

Most recent entries​

The live feed is in the in-product changelog at /manage/developer/docs. This static page does not duplicate the entries - refer to the in-product feed for the current list.

For historic context, the developer settings feature itself launched in June 2026 as part of the Media Agency API Platform initiative (phases F-01..F-07 + E-01..E-08 + D-01..D-07 + W-01..W-06).