Versioning

The public API is versioned in the URL path:

/api/public/v1/...

What can change within v1

Within v1, changes are additive only. Build your client to tolerate:

• new endpoints and resources — v1 is read-only today, and write endpoints would arrive as additions;
• new optional fields in responses;
• new optional query parameters;
• new codes in the error catalogue;
• new scopes;
• new webhook event types.

Never assume a response object's set of fields is closed: read the fields you know and ignore the rest. Handle an error code you do not know by its HTTP status.

What never changes within v1

• Existing fields and endpoints are never removed or renamed.
• The type and meaning of an existing field never change.
• An existing error code keeps its meaning.
• Authentication (X-Api-Key), the error envelope and the pagination shapes stay as documented.

Breaking changes → a new version

Anything that would break the rules above ships under a new path version, /api/public/v2/..., announced in the changelog together with migration notes and how long v1 stays available.

Webhooks

Webhook payloads carry no version. Read them the same way: take the fields you know, ignore the rest, and treat an event type you do not know as one to skip.

Staying informed

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