# 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.