Versioning

Current version

v1. All endpoints live under /v1/…. If you do not pin a version in your client URLs, your integration will break when we ship v2.

What counts as a breaking change

• Removing a field from a response.
• Renaming a field.
• Changing the type of a field (e.g. number → string).
• Tightening an existing endpoint's validation in a way that rejects previously-accepted requests.
• Changing the URL of an endpoint.

What is not breaking

• Adding new optional response fields.
• Adding new endpoints.
• Adding new query parameters whose defaults preserve current behavior.
• Adding new enum values (e.g. a new allergen). Clients should handle unknown enum values gracefully.

Deprecation policy

When we eventually ship v2:

• v1 remains operational for at least 12 months after v2 ships.
• Deprecation timeline is announced in advance via the changelog and by email to all active accounts.
• Responses on the deprecated version include a Sunset header per RFC 8594.

Beta features

New endpoints may be released under a /v1/beta/… prefix. Anything under beta can change without notice and is excluded from version guarantees until graduated.