Developer documentation
API and SDK policies
The public contract is published at/openapi/v1.json. These policies describe how that contract can change without warning, how long deprecated operations stay callable, and how long the official SDKs are supported.
API versioning
A version segment in the URL (/v1) signals a stability contract. The following rules apply.
| Change | Policy |
|---|---|
| Backwards-compatible additions | Allowed inside /v1: new endpoints, new optional request fields, new response fields, new error codes. |
| Breaking changes | Require a new API version. Examples: removing or renaming a field, changing the meaning of an existing field, making an optional field required, narrowing the HTTP status returned for an existing error. |
| Beta SDK changes | Beta SDKs may add methods in a minor release; existing documented methods keep compatible call and error behavior within the same major version. |
Deprecation notice
A deprecated operation or field is announced in the changelog and documentation; this page is the public summary. Default window is 180 days; shorter windows are permitted only when continued availability creates an active security or legal risk.
| Aspect | Policy |
|---|---|
| Notice channel | The changelog and this documentation page. Runtime responses may additionally carry deprecation and sunset headers before removal. |
| Default notice window | 180 days. A deprecated operation or field remains callable for at least 180 days after the announcement. |
| Shorter window | Permitted only when continued availability creates an active security or legal risk. The reason is recorded in the changelog entry that announces the deprecation. |
SDK support
The official SDKs are @blitzglobaltech/pulsepigeon on npm and pulsepigeon on PyPI. The current major line is 1.0.0 in both packages.
| Aspect | Policy |
|---|---|
| TypeScript runtime | Maintained Node.js LTS releases beginning with Node 18. |
| Python runtime | Python 3.11 and later; 3.11, 3.12 and 3.13 are tested. |
| Compatibility commitments | Typed errors, webhook signature verification, and documented authentication behavior are compatibility commitments within the same major SDK version. |
| Previous major versions | When a new major SDK version reaches general availability, the previous major version receives security and critical bug fixes for 12 months. After that it is unsupported, though existing releases stay installable. |
| Beta methods in a GA SDK | Individual methods can be marked beta in the reference. Beta methods can change or be removed in a minor release. When a beta method is promoted to general availability, the promotion ships in a minor release, is announced in the changelog, and the method then follows the compatibility commitments above. |
See also
Developer guide: request and response contracts.
API reference: searchable index of public operations.
SDK reference: TypeScript and Python method surface.
Webhook verification: signed delivery contract and replay rules.