Versioning & stability

The AxioRank gateway API is v1 and stable, served at /api/v1 (the unversioned /api/... paths alias to it, so existing integrations keep working). We only make backward-compatible changes to v1 without notice; any breaking change ships as a new version with advance notice (see below).

Backward-compatible changes (anytime, no notice)

Write your integration to tolerate these — they will happen:

• New API endpoints and new optional request parameters.
• New fields in JSON responses and in webhook payloads.
• New values in an existing enum (a new decision, signal category, or webhook event type) — ignore values you don't recognize rather than erroring.
• New webhook event types.
• New machine-readable error codes / reasons.

Breaking changes (new version + notice)

We treat these as breaking and will not make them to v1:

• Removing or renaming an endpoint, field, or enum value.
• Changing a field's type, or making an optional field required.
• Changing authentication, or the default behavior of an endpoint.

When a breaking change is unavoidable, we:

1. Announce it in the changelog with at least 90 days' notice.
2. Ship the new behavior under a new version (a /v2 path prefix) while v1 keeps working.
3. Mark the old surface deprecated with Deprecation / Sunset response headers and publish a migration guide before anything is removed.

SDKs

@axiorank/sdk and axiorank follow semantic versioning: patch and minor releases are backward-compatible; a major bump signals a breaking change. Pin a major (^0) and read the changelog before upgrading across majors.

Webhooks

Delivery is at-least-once and unordered — dedupe on the Axiorank-Id header and don't assume order. New event types are additive; subscribe explicitly (or to *) and ignore types you don't handle. See Webhooks.

Staying informed

Watch the changelog for every developer-facing change — breaking changes and deprecations are always called out there first.