Versioning & Deprecation Policy

How Brainerce ships breaking changes — what we promise, what we don't, and how to stay current.

URL prefix

The public API lives under /api/v1/*. All external integrations should call this prefix. Internal dashboard routes (under /api/<module>) are subject to change without notice and are not part of the public contract.

What is and isn't a breaking change

Breaking (announced + grace period):

Removing an endpoint
Removing or renaming a JSON field
Tightening validation that was previously accepted (e.g. previously-optional field becomes required)
Changing the type of a field (string → number)
Changing semantics of an existing field
Changing error code values (introducing new codes is non-breaking)

Non-breaking (ships any time):

Adding new endpoints
Adding optional fields to requests
Adding new fields to responses (consumers must ignore unknown fields)
Adding new error code values
Adding new query params (existing requests without them keep working)
Bug fixes that align behaviour with the documented contract

Deprecation grace period

When we deprecate something, you have at least 90 days before removal. During that window:

The endpoint or field continues to work exactly as before.
A banner appears in the dashboard for affected stores.
The Changelog entry is published at deprecation start.

Critical security fixes may bypass this window if the existing behaviour is unsafe. We will email the contact on file when this happens.

There is no deprecation response header. No X-Brainerce-Deprecation header is emitted by the API — if you have seen it documented, it was never implemented, and a CI check watching for it will never fire. The Changelog and the dashboard banner are the two deprecation channels that actually exist.

How to stay current

Subscribe to the Changelog RSS feed (coming soon)
Re-read the Changelog before each SDK bump — it is the only machine-external signal we publish
Pin the SDK to a major version (brainerce@^2) and read the release notes before bumping

API version vs. SDK version

The HTTP API version (/v1/) and the npm SDK version ([email protected]) move independently. The SDK can ship patches without API changes, and the API can add fields without SDK updates. Major SDK releases ([email protected]) are reserved for incompatible client-side changes (resource grouping, idempotency built-in, etc.) and do not imply an API version bump.

Multiple active versions

We do not currently maintain multiple API versions side-by-side. When /v2/ ships, /v1/ will enter a 12-month deprecation window.