API Stability & Versioning
How the PacSpace API is versioned, what counts as a breaking change, and how changes are communicated.
The Balance API is versioned in the URL path. Everything documented on this site lives under /api/v1/ and is stable: integrations built against v1 keep working without code changes.
What We Will Do Without Notice
Additive, non-breaking changes ship continuously:
- New endpoints and new optional request parameters.
- New fields in responses and webhook payloads.
- New webhook event types (your handler should ignore event types it does not recognize).
- New enum values in fields documented as extensible.
Write clients that tolerate unknown fields and unknown event types, and none of these will ever affect you.
What We Will Never Do Within v1
- Remove or rename a documented endpoint, request parameter, or response field.
- Change the type or meaning of an existing field.
- Change authentication, signature, or verification semantics.
- Repurpose an existing webhook event.
A change in any of these categories gets a new version path, and v1 keeps working alongside it.
Deprecations
If an endpoint or field is ever deprecated, it will be marked in these docs and announced in the Changelog well before any behavior changes, with a documented migration path. Deprecated does not mean removed: within v1, deprecated surfaces keep functioning.
The Verified Record Is Forever
API versioning never touches recorded data. Deltas, checkpoints, proofs, and receipts committed under any API version remain readable and verifiable under every later version. The record outlives the interface used to write it.