Skip to main content
The REST API is date-versioned. Every response includes X-API-Version, and the OpenAPI document identifies the contract it describes.

​
Compatibility policy

Within a published API version, Perkstar may:
  • add optional response fields;
  • add new endpoints or webhook event types;
  • add optional request fields; and
  • improve validation and error detail without changing successful behaviour.
Integrations should ignore unknown response fields and webhook event types they do not handle. Do not model API objects as closed dictionaries unless your decoder supports forward-compatible fields. A breaking change requires a new version and a migration period. The current OpenAPI description states the active deprecation policy.

​
SDK versions

@perkstar/api-client follows semantic versioning:
  • patch releases contain compatible fixes;
  • minor releases add compatible functionality; and
  • major releases may require code changes or pin a newer API contract.
Pin a supported version range, run contract tests in CI, and review the changelog before upgrading.

​
Detecting drift

Log X-API-Version with request IDs. During deployment, compare the SDK’s exported API_VERSION with the server header and alert on an unexpected value.