Versioning & deprecation

The public API is versioned in the URL path:

/api/public/v1/...

What can change within a version

Within v1 changes are additive only. You should build your client to tolerate:

• new endpoints and new resources;
• new optional fields appearing in responses;
• new optional query parameters;
• new values in the error-code catalog;
• new scopes.

Never assume a response object's field set is closed — parse what you know, ignore what you don't.

What never changes within a version

• Existing fields are never removed or renamed.
• Types and semantics of existing fields never change.
• Existing error codes keep their meaning.
• Authentication and the error envelope stay as documented.

Breaking changes → a new version

Anything that would break the rules above ships as a new path version (/api/public/v2/...). When that happens:

• v1 keeps working for at least 12 months after v2 is announced;
• deprecation is signalled in the changelog and, on the wire, with Deprecation / Sunset response headers on the old version;
• migration notes are published alongside the new version.

Staying informed

Watch the changelog — every addition to the API is recorded there, release by release.