Versioning

Version in the URL

All endpoints under the ingestion service include the version in the path:

https://ingestion.lehnz.com/api/v1/...

The recommendations service does not currently include a version segment in its URL — that is the equivalent of v1 behavior. A future /v2 would be served alongside it.

What counts as a breaking change

Any change in this list ships behind a new version:

• Removing or renaming a request field, response field, or endpoint.
• Changing the type of an existing field (e.g., string → number).
• Tightening validation that would reject previously-accepted payloads.
• Changing the default value of a parameter such that the same input produces a different output.
• Changing authentication semantics — e.g., an endpoint that accepted publishable keys now requires secret.

If you maintain a client against this API, your tests should pin to the exact field shapes you depend on. Anything beyond that — new optional fields, new response keys, additive enum values — should be tolerated.

What ships without a version bump

• New endpoints.
• New optional request fields with safe defaults.
• New response fields. (Treat unknown response keys as forward-compatible — don't fail on them.)
• New values added to an enum, including event_name and status.
• Performance and ordering improvements where the response shape is preserved.
• New, non-required HTTP headers (request or response).

Deprecation policy

When a future v2 ships:

1. Both versions run side-by-side for at least 12 months.
2. Endpoints removed or replaced in v2 return a Deprecation response header and a Sunset header pointing to the cutoff date (per RFC 8594).
3. The dashboard surfaces deprecation warnings to OWNERs and ADMINs at least 90 days before sunset.
4. Keys generated under v1 continue to work for v1 endpoints during the deprecation window — no need to regenerate.

How to track changes

All version-relevant changes — additive or breaking — are recorded in the changelog.