Versioning

The version is part of the path: /api/public/v1/.... One version is available today — v1 — and it is stable.

What counts as breaking

We do not ship changes within v1 that could break a working integration:

• removing or renaming an endpoint, a response field or a parameter;
• changing a field's type (string → number, say) or value format;
• adding a required field to a request body;
• narrowing the set of accepted values;
• changing the error code for an already-documented situation.

Those only ship as a new path version — /api/public/v2/....

What can change without a version bump

Changes that do not break a correctly written client can land in v1 at any time:

• new endpoints;
• new optional fields in responses;
• new optional parameters on requests;
• new dictionary entries (body types, permits, currencies);
• rewording of an error's message.

Two rules for your integration follow:

1. Ignore unknown fields in responses rather than failing on them.
2. Do not rely on JSON key order or on exact message wording — branch on code (Errors).

Opaque values

The pagination cursor (nextCursor) is an opaque string. Its internal format is not part of the contract and may change within v1. Send back exactly what you received and do not parse it.

Deprecation

If a v2 ever appears, the previous version will:

• keep running for at least 6 months after the new one ships;
• start sending Deprecation and Sunset headers carrying the shutdown date;
• stay documented, marked as deprecated.

We notify owners of active keys ahead of such changes and record them in the changelog.

Recommendation

Pin your integration to the version explicitly (that is, to /api/public/v1) instead of building the path dynamically. Moving to the next version should be a deliberate decision, not the side effect of a configuration change.