Versioning

The API’s major version lives in the URL — every endpoint is mounted under /api/v1. Alongside it, two headers ride on every response.

X-PB-API-Version

Each response carries an X-PB-API-Version header reporting the exact release version that served it (the current release version — bumped on each release). This is the fine-grained build identifier, distinct from the /v1 major version in the path: /v1 is the compatibility contract, the header is the precise release. Log it — it’s the fastest way to confirm a rollout reached your traffic, or to pin down which release a bug report corresponds to.

Compatibility policy

Within a major version, changes are additive and non-breaking by policy. We may, without a new version:

• add new fields to existing responses;
• add new event types to the webhook catalog;
• add new endpoints;
• add new optional request parameters.

Write tolerant parsers. Ignore fields you don’t recognize, don’t assume an object’s key set is closed, and don’t reject an unfamiliar event type — treat these as forward-compatible growth, not errors.

A change that could break an existing integration — removing or renaming a field, changing a type, tightening validation — never mutates /api/v1 in place. It ships as a new /api/v2 mount, and /api/v1 keeps working. You migrate on your own schedule.

Note

This is why the compatibility contract is /v1, not the release version in the header: the header will tick forward continuously as we ship additive changes, and none of those require anything from you.

Request ids

Every response also carries an X-Request-Id header — a req_... id unique to that request. The same id appears as request_id inside every error envelope. Capture it in your logs, and quote it in any support request — it lets us find the exact request on our side.

Related

• Errors — where request_id shows up in failures.
• Webhooks — new event types are an additive, non-breaking change.
• Interactive reference — the current /v1 contract in full.