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.
Before wider API beta
Public API v1 contract lock
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.
Expected client impact: none for external users. No external users exist yet.
Field naming audit
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.
Expected client impact: none for external users. Any public-field changes should happen before wider beta.
Webhook delivery observability
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/API now 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.
Expected client impact: none for external users. The existing endpoints are additive.
Metadata discovery
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.
Expected client impact: none for external users. The existing endpoint is additive.
Sandbox and test environments
HollyHR's beta public API is live-only. GET /me exposes
environment.type = "live" and environment.sandbox = false, and the
developer docs now publish safe integration-testing guidance for dedicated keys,
non-production organisations, idempotency, ETags, and webhook test deliveries.
HollyHR also has an internal synthetic demo-tenant provisioning command for
reviewer, partner, and TTFC evidence. A separate hhr_test_ prefix or
self-service public sandbox organisation model remains a future candidate, not
an implicit beta behavior.
Expected client impact: none for external users. No separate sandbox has been promised.
Future candidates
These are not scheduled commitments:
- richer in-app webhook delivery-history inspection;
- sparse fieldsets and relationship expansion with explicit caps;
- self-service sandbox/test API keys or customer-owned sandbox organisation provisioning;
- OAuth partner applications and self-service developer registration;
- published SDK release automation beyond the preview TypeScript SDK.