Versioning and Stability

The Macha API is versioned at the URL path level: /api/v1/.... Customers can depend on v1 staying compatible with code written today. Breaking changes go to a new major version, we don't break v1 in place.

What's in a version

The v1 contract covers:

• URL structure. Every endpoint URL under /api/v1/ is stable.
• Authentication. Bearer token format and scope catalog.
• Request shape. Field names, types, required/optional, validation rules.
• Response shape. Field names, types, the success/error envelope.
• Error codes. The stable identifiers in error.code.
• Status codes. Which HTTP code is returned for which condition.
• Pagination. Cursor-based, opaque tokens.
• Idempotency. The Idempotency-Key header semantics.
• Rate limits. The headers always exist with this naming.

What's not in the contract:

• Exact rate limit numbers (we may raise the cap freely)
• Exact error message strings (the code is stable; message may be reworded)
• Internal storage formats (e.g. how cursors are encoded)
• Response time, geographical routing, or HTTP/2 push behavior

Non-breaking changes (ship into v1 freely)

The following are considered additive and may ship into v1 without notice:

• Adding a new endpoint
• Adding a new optional request field
• Adding a new response field
• Adding a new error code
• Adding a new query param to a list endpoint
• Adding a new value to an enum that the customer doesn't pass (e.g. a new sync_status value)
• Loosening a constraint (e.g. accepting longer names than before)

Breaking changes (require v2)

The following require a new major version and we will NOT do them in v1:

• Removing or renaming an endpoint
• Removing or renaming a response field
• Removing or renaming an error code
• Changing the type of an existing field (e.g. string → integer)
• Making an optional request field required
• Tightening validation (e.g. shortening the max-length cap for a field)
• Adding a new enum value that the customer DOES pass (e.g. forcing them to handle a new source value)
• Changing the response status code for an existing condition
• Changing the auth scheme

Stability tiers

Within v1, every endpoint is one of:

Tier	Meaning
stable	Shipped. Shape cannot change in a breaking way. Use freely.
beta	Shipped. Shape may change with notice. Tagged in the OpenAPI spec and in the docs page header.
planned	Documented but not yet implemented. Returns 404 or insufficient_scope if called today. Tracks our public roadmap.

The vast majority of v1 endpoints are stable. Any beta or planned endpoint is labeled prominently on its reference page.

How you'll learn about changes

• Additions: appear in the docs and the OpenAPI spec. Nothing else, no email blast for adding a new field.
• Beta → stable: announced in the change log.
• Stability downgrades: we will never downgrade a stable endpoint to beta or planned without a new version. If we made a mistake and need to fix it, we ship the fix as a new endpoint, deprecate the old one (see below), and remove the old one only in v2.

Deprecation

If we need to retire an endpoint or field within v1:

1. The endpoint is marked deprecated in the docs and OpenAPI spec.
2. Responses include a Deprecation header with a date (RFC 9745 / Sunset header pattern).
3. A minimum of 6 months elapse during which the endpoint still works.
4. At the end of the window, the endpoint continues to work until v2. Removal is a breaking change and only happens at version bumps.

In practice, this means we may add a new better endpoint and deprecate the old one within v1, but you have at least 6 months to migrate at your leisure, the old endpoint keeps working until v2 ships (which itself is announced months ahead).

How to know when v2 is coming

v2 is not on the immediate roadmap. When we're seriously considering it, we'll:

1. Publish a v2 proposal as a doc page on this site (/docs/api/v2-preview or similar)
2. Make v2 available at /api/v2/ in beta for a period of months while v1 stays live
3. Announce v1 deprecation only after v2 has been beta for at least 6 months
4. Keep v1 working for a minimum of 12 months after deprecation announcement

You will have at least 18 months from the v2 announcement to migrate. Macha is small enough that we can be conservative about this.

API version vs SDK version vs Macha version

Three different version numbers in the Macha world:

What	Where	Bumps when
API version	/api/v1/ in URL	Breaking changes to the REST contract (rare).
OpenAPI spec version	info.version in openapi.json	Any documented change to v1 (frequent). Follows semver against the spec itself.
Macha product version	Marketing, release notes	Whenever we ship a meaningful new feature (continuous).

The API version is the only one that affects your code's compatibility. Spec and product versions can churn freely.