Planned Changes
This page records upcoming public API changes before they affect clients. HollyHR is pre-launch, so the current entries are launch-readiness decisions rather than customer migrations.
Change policy
Planned entries use these fields whenever a change can affect an external client:
Published: the date the plan was added to this page.Earliest effective date: the first date HollyHR may ship the change.Customer action: what an existing client would need to do.Final failure mode: the eventual error, missing field, unsupported event, or SDK behaviour after the transition.
For deprecations after external beta begins, HollyHR should prefer a dated
replacement path over silent removal. Where technically useful, responses can
also carry standard Deprecation, Sunset, or Link headers, but only after
the underlying API contract implements those headers.
Deprecation and sunset notice template
Use this template for any planned deprecation, sunset, or breaking public API change. Keep the dates concrete; do not use relative wording such as "next month" without the calendar date.
Code
Default minimum notice after external beta begins:
deprecated: at least 90 days before sunset unless a security, privacy, or legal issue requires faster action;breaking: at least 120 days before the earliest effective date, plus a migration path and final failure mode;behavioural: dated notice when clients may observe changed semantics even if the wire contract remains compatible.
Before wider API beta
Public API v1 contract lock
Published: 2026-06-21 Earliest effective date: before wider API beta Customer action: none for external users. No external users exist yet.
HollyHR will lock the public API v1 conventions for errors, rate limits, request IDs, pagination, idempotency, ETags, scopes, and webhook payload boundaries before inviting external beta consumers.
Final failure mode: after v1 lock, incompatible public-contract changes should move through this page before they reach external clients.
Field naming audit
Published: 2026-06-21 Earliest effective date: before wider API beta Customer action: none for external users.
HollyHR will run a narrow audit of generated OpenAPI field names and public webhook payload fields before v1 is treated as stable. The audit is limited to the public API contract and should not rename internal domain models.
Final failure mode: field names are treated as stable once the wider beta contract is locked.
Webhook delivery observability
Published: 2026-06-21 Earliest effective date: before wider API beta Customer action: none for external users.
HollyHR now exposes public API webhook health summaries, delivery-log endpoints for delivery status, retry state and attempt history, and manual redelivery of failed or retry-scheduled deliveries, and automatic endpoint disablement after 10 retained terminal failed deliveries with in-app system-admin notifications. Terminal delivery-log rows are retained for 30 days and pruned automatically by the webhook worker. Settings/Integrations/Developer tools exposes endpoint health, delivery counts, latest retained failure summaries, next retry timing, disabled-endpoint reactivation, and sanitized recent attempt history for System Admins. The remaining launch readiness work is operational: a future real-time delivery engine change before a wider beta.
Final failure mode: existing beta endpoints remain additive; broader event coverage should not be marketed until delivery semantics are production-ready.
Metadata discovery
Published: 2026-06-21 Earliest effective date: shipped in beta Customer action: none for external users.
HollyHR now exposes GET /metadata for a generated machine-readable catalogue
of routes, scopes, schema fields, field categories, and webhook event scope
requirements. Future metadata expansion should add filter/sort capability
flags only when those endpoint features exist in the public contract.
Final failure mode: unsupported fields stay absent from metadata rather than appearing as undocumented or hidden capabilities.
Sandbox and test environments
Published: 2026-06-21 Earliest effective date: partially shipped in beta Customer action: none for external users.
HollyHR now distinguishes live and hosted sandbox public API keys. Ordinary
tenant keys use the hhr_live_ prefix and GET /me reports
environment.type = "live" with environment.sandbox = false. Keys created in
the platform-owned sandbox.hollyhr.com synthetic tenant use the hhr_test_
prefix and GET /me reports environment.type = "sandbox" with
environment.sandbox = true. The generated OpenAPI schema includes the sandbox
server so the developer-docs Try-It flow can target it explicitly.
Per-customer self-service sandbox organisation provisioning remains a future candidate. Live keys will not silently become sandbox keys.
Final failure mode: clients must not assume a test key grants access to any
organisation other than the sandbox tenant that created it, and must not use
hhr_live_ keys for destructive sandbox tests.
Future candidates
These are not scheduled commitments:
- richer in-app webhook delivery-history inspection;
- sparse fieldsets and relationship expansion with explicit caps;
- customer-owned self-service sandbox organisation provisioning;
- OAuth partner applications and self-service developer registration;
- published SDK release automation beyond the preview TypeScript SDK;
- richer document read/write flows, including signed downloads, uploads, and e-sign, after storage, retention, DSAR, and access-control decisions are reviewed.