Versioning & Deprecation Policy

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.

There is exactly one public API version, v1. There is no v2, no version header and no version negotiation: the version is the URL prefix and nothing else.

Additive-only commitment

/v1 only grows. We add endpoints, optional request fields, response fields, query params and error codes; we do not change or remove what /v1 already does except through the deprecation process below.

Breaking (announced, then a grace period of at least 90 days):

• 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
• Removing or renaming an error code (changing the message text is not breaking, so switch on code, never on message)

Non-breaking (ships any time, without notice):

• Adding new endpoints
• Adding optional fields to requests
• Adding new fields to responses (consumers must ignore unknown fields)
• Adding new error code values (always keep a default branch when you switch on code)
• 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:

1. The endpoint or field continues to work exactly as before.
2. The operation is marked deprecated: true in the OpenAPI document, which is where the deprecated routes in the API reference are flagged.
3. The Changelog entry is published at deprecation start.
4. A banner appears in the dashboard for affected stores.

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

The 90 days is a published commitment, not a timer in the code: nothing in the API refuses or alters a call when a window ends. Read the Changelog to learn when a window starts.

There is no deprecation response header. The API emits neither Deprecation nor Sunset nor X-Brainerce-Deprecation on any response, so a client or CI check watching for one will never fire. The deprecated: true flag in the OpenAPI document, the Changelog and the dashboard banner are the deprecation channels that exist.

How to stay current

• Re-read the Changelog before each SDK bump. There is no RSS or email feed for it.
• Pin the SDK to a major version (brainerce@^3) and read the release notes before bumping.
• Ignore unknown response fields and keep a default branch when you switch on an error code or an enum value, because additions to both ship without notice.

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 (a new [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 maintain multiple API versions side-by-side, and we do not plan to: /v1 is the single version and it evolves additively. If a change could never be made additively, it goes through the 90-day deprecation process above rather than into a new version prefix.