Versioning & Changes

The version is part of every URL: /api/v1. Within a version, the API only changes in ways that keep existing integrations working.

Changes made within v1

These are additive and can happen at any time without notice. Write your integration so they do not break it:

• New endpoints.
• New optional request parameters and body fields.
• New fields in responses.
• New values in fields that are documented as open-ended, such as event types.
• New error codes. Treat an unknown code according to its HTTP status.
• New scopes, and existing scopes becoming grantable as their endpoints are released.
• New webhook event types.
• Changes to the wording of error.message and descriptions.
• Changes to rate limits. Always read the RateLimit-* headers rather than hard-coding numbers.

To stay compatible:

• Ignore response fields you do not recognise.
• Do not depend on the order of keys in a JSON object.
• Treat ids and cursors as opaque strings.
• Branch on error.code, not on error.message.

Breaking changes

A breaking change is one that could stop a correctly written integration from working, for example:

• Removing or renaming a field, endpoint or parameter.
• Changing a field's type or format.
• Making an optional parameter required.
• Changing what an existing error code means.

Breaking changes are not made to v1. They would be released as a new version under a new path, /api/v2, with v1 continuing to work alongside it.

Deprecation

When an endpoint or field is going to be retired, it is first marked deprecated in the API Reference and the OpenAPI document. A deprecated endpoint keeps answering; it is not removed from v1.

Staying informed

• The API Reference on this site is regenerated from the API as endpoints are released.
• The live specification at https://app.bookyourpto.com/api/v1/openapi.json always describes what is running. Compare it with a saved copy in your test suite to spot additions.