Copy page

Resources

API Changelog

This changelog records customer-visible changes to the HollyHR public API. HollyHR is currently pre-launch and the public API is in beta, so there are no external-client migrations to announce yet.

How to read entries

Entries are dated by publication date. Each customer-impacting entry should name the affected endpoint, scope, webhook event, SDK package, field family, or docs/runtime surface, and classify the change as one of:

• additive: new endpoint, field, event, docs guide, or helper that should not break existing clients;
• behavioural: compatible behaviour change that clients may want to notice;
• deprecated: an old field, endpoint, event, or behaviour remains available but has a dated replacement path;
• breaking: a removed or incompatible public contract change.

HollyHR has not launched external API consumers yet, so the current entries are launch-readiness records. Machine-readable feeds are generated from this page:

• RSS feed
• Atom feed

Treat this page, those feeds, and Planned changes as the release-communication source of truth.

2026-08-19

Truthful hosted MCP executable-surface discovery

Classification: behavioural

• Hosted MCP operation discovery now reports one explicit execution disposition for every public API operation: executable, policy-blocked, missing a reviewed MCP projection, missing an MCP dispatcher, or disabled by the live write mode.
• The embedded alias catalogue distinguishes real tools/list registrations from conceptual aliases that remain available only through generic operation tools. No alias, operation, scope or data projection has been added.
• Compound aliases are advertised only when the authenticated principal can call every constituent operation. In particular, get_person_context requires both people:read and time_off:read in discovery as well as at execution.

The public REST API, OpenAPI contract, TypeScript SDK, MCP field projections and default-off write posture are unchanged. Clients should treat tools/list as the callable tool-name authority and the operation catalogue as generic-call capability metadata.

2026-08-18

Person-bound idempotency for leave-balance adjustments

Classification: behavioural

• POST /v1/people/{personId}/time-off-balance/adjustments now binds the target personId into its idempotency fingerprint.
• Reusing one idempotency key and request body for a different person now returns the standard HTTP 409 idempotency conflict instead of replaying the first person's stored success response.
• Same-person retries remain idempotent. Unexpired receipts created before this change are replayed only after HollyHR validates that the stored adjustment belongs to the requested person and organisation.

Clients should use a distinct idempotency key for each intended person-level adjustment. No request or response schema changed.

2026-08-13

Active time-off date conflicts

Classification: behavioural

• POST /v1/time-off and PATCH /v1/time-off/{timeOffId} now return the standard conflict error with HTTP 409 when any selected date overlaps the person's pending or approved standard time off.
• The response remains content-free: it does not identify the conflicting record or expose its category, notes, or sickness state.

Clients should preserve the draft and ask the user to choose different dates.

2026-08-06

Stable time-off status codes

Classification: additive

• Public time-off list and item responses now include status_code with one of pending, approved, rejected, or cancelled.
• The existing human-readable status field remains available for display; clients should use status_code for workflow logic.

No customer action is required.

2026-08-02

Effective-dated employment commands replace mutable profile history

Classification: breaking

• PATCH /v1/people/{personId} is now identity-only. Employment changes use the dedicated employment and employment-history routes.
• Current-employment changes and new history facts require an effective start_date, If-Match, and Idempotency-Key. History updates are factual corrections, require correction_reason, and return a new immutable fact.
• Ending employment records an inclusive final day. Reactivation is now a true rehire and requires a new start_date after the prior period.
• Employment and history responses include timeline_version; their ETags are bound to that version so a correction that leaves visible terms unchanged still invalidates a stale write.

HollyHR remains pre-launch with no external API consumers, so the beta contract and generated SDK move directly to this canonical model without a legacy compatibility period.

2026-08-01

Bounded read-event webhooks for instant integrations

Classification: behavioural

• webhooks:manage and bounded signed read-event delivery are now available on every plan. Event families still require the corresponding read scope; programmatic employee writes remain Standard plus exact HollyHR approval.
• New deliveries get a best-effort request-context fast attempt. A fair one-minute durable worker remains authoritative for retries and recovery.
• Each organisation may have up to 10 active endpoints, 500 pending deliveries per endpoint and 5,000 pending deliveries in total. Lifecycle mutations have dedicated API-key and organisation limits; overload is recorded explicitly and disables the affected endpoint rather than silently dropping rows.
• Person events now include public-projection employment edits and committed spreadsheet imports. Bulk imports retain durable recovery without scheduling hundreds of request-lifetime callbacks.

Existing webhook URLs, signing, event envelopes and read-scope requirements are unchanged. No customer action is required.

Minimise hosted MCP absence data

Classification: behavioural

• Hosted MCP time-off-balance results no longer include explicit sickness totals. Ordinary leave totals remain available; raw absence categories, medical content and joinable category identifiers remain excluded.
• The public REST API, OpenAPI contract and TypeScript SDK are unchanged.

No customer action is required.

2026-07-30

Universal read-only AI connector

Classification: additive

• https://app.hollyhr.com/api/mcp is now the canonical connector URL for Anthropic and OpenAI directory clients. The authenticated principal, never a hostname or tool argument, selects the HollyHR workspace.
• The initial provider listing is read-only. Its fixed synthetic reviewer actor has seven read scopes and no write scopes; disabled mode removes write tools, prompts and advertised write scopes.
• WorkOS-backed OAuth discovery advertises only the identity scopes that WorkOS issues. HollyHR data permissions remain enforced by the bound, tenant-scoped backing actor rather than being requested from the identity provider.
• Provider review uses eight durable cases—five positive and three adversarial—with expected tenant, projection and no-mutation outcomes.
• list_api_operations omits the optional required_scope field when an operation has no single REST scope, preventing remote MCP clients from rejecting an otherwise valid catalogue response.
• Tenant-origin MCP URLs remain available for existing server-side integrations.

No customer action is required.

Governed write-capable AI connectors

Classification: behavioural

• HollyHR's hosted MCP server now advertises write tools and write OAuth scopes only while the production write mode is enabled. Disabling the mode removes them from discovery as well as rejecting execution.
• Supported writes remain limited to the positively projected People and Time Off operations in the public API catalogue. A write is first frozen into an exact preview and can commit only after explicit host-mediated approval.
• Read, prepare, and commit tools now carry complete MCP annotations so connected assistants can distinguish non-mutating calls from changes that require confirmation.
• OAuth directory reviewers use a fixed synthetic Sandbox identity with no access to customer records. Workspace identity, actor scopes, field projections, ETag checks, idempotency, audit, revocation, and PII budgets continue to apply.

No customer action is required. Workspace administrators retain control of connector credentials and write scopes.

Newest-first people and time-off polling

Classification: additive

• GET /people and GET /time-off now accept sort=updated_at_desc to return the most recently updated records first.
• The existing default order is unchanged when sort is omitted.
• Descending responses retain cursor pagination and the same tenant, scope, plan, field-projection, and rate-limit boundaries as the existing lists.
• The generated OpenAPI contract and TypeScript SDK expose the new query option.

This option is intended for polling integrations that need to process recent changes first. No customer action is required.

2026-07-29

Dual-era hosted MCP protocol

Classification: additive

• POST /api/mcp now prefers the stateless 2026-07-28 protocol while continuing to accept stateless 2025-11-25 initialize clients.
• Both protocol eras use the same hosted endpoint, bearer authentication, tenant principal, tools, projections, masking, PII budget and request audit.
• Governed writes use modern input_required approval before the existing signed frozen write can commit. Stateless legacy clients can read and prepare but fail closed at commit because they cannot carry host approval.
• The repository pnpm mcp:smoke command verifies both protocol eras.

No customer action is required. New integrations should prefer 2026-07-28; clients that still default to 2025-11-25 remain compatible.

2026-07-23

Stable domain capability metadata

Classification: additive

• Every generated OpenAPI operation now includes x-hollyhr-domain-capabilities.
• GET /metadata and the hosted MCP catalogue expose the same stable domain capability identifiers for discovery and cross-surface tooling.
• Capability metadata does not grant authority: REST scopes, API-key or OAuth principals, MCP projections, masking, and write confirmation remain independently enforced.

No customer action is required.

2026-07-11

Opaque person identifiers

Classification: breaking

• Person-facing API resources, references, webhooks, and exports now use tenant-specific opaque 12-character person_id values.
• Legacy numeric user IDs are no longer accepted as person identifiers.
• The same individual has a different person identifier in each organisation; identifiers remain locators rather than authorisation tokens.

The public API is pre-launch beta. Update any internal fixtures or preview integrations that retained numeric person IDs by resolving people again through GET /people.

2026-07-08

Integration readiness

Classification: additive

• Added GET /integration-readiness for tenant-scoped payroll, accounting, and spend-tool readiness.
• The response reports aggregate readiness, issue severity, and provider playbooks without exposing raw payroll-financial, banking, receipt, or provider-secret values.
• Generated OpenAPI, metadata, and TypeScript SDK contracts include the new operation.

No customer action is required.

2026-07-06

Pay-period payroll changes export

Classification: additive

• Added GET /payroll-changes-export?from=YYYY-MM-DD&to=YYYY-MM-DD for inclusive periods of up to 400 days.
• The export covers starters, leavers, safe employment-history changes, and compensation or banking change flags; it never exports salary amounts, percentages, bank-account fields, or free-text reasons.
• The operation requires payroll_exports:read and is deliberately excluded from the hosted MCP catalogue.

No customer action is required.

2026-07-01

Sandbox API-key environment

Classification: additive

• API keys created in HollyHR's platform-owned synthetic sandbox use the hhr_test_ prefix; ordinary tenant keys continue to use hhr_live_.
• GET /me now reports environment.type and environment.sandbox so integrations can prove which tenant environment owns a key before doing work.
• The OpenAPI Try-It configuration and developer guides expose the real sandbox environment without implying that live customer tenants are cloned.

No customer action is required.

2026-06-23

TypeScript SDK preview

Classification: additive

• Published the beta @hollyhr/api-client package to npm with generated, typed operations from the public OpenAPI contract.
• Added runnable TypeScript examples and package drift checks so the SDK, OpenAPI, and runtime operation catalogue remain aligned.

No customer action is required.

2026-06-21

Metadata discovery

Classification: additive

• Added GET /metadata, a machine-readable catalogue of public API routes, required scopes, path/query parameters, schema fields, field categories, and webhook event scope requirements.
• The catalogue is generated from the same OpenAPI/Zod contract source as the public reference.

No customer action is required.

Contract lock preparation

Classification: additive

• Documented the v1 error envelope as the public API error contract.
• Documented public API rate-limit headers and default request buckets.
• Added planned-changes, support, feedback, and OpenAPI import guidance to the developer docs.

No customer action is required.

Deprecation entry format

Future deprecation or breaking-change entries should include:

• the date the change was published;
• the endpoint, scope, webhook event, or field affected;
• whether the change is behavioural, deprecated, or breaking;
• the effective date for any deprecation or sunset;
• the migration path and final failure mode.
• the response headers, SDK warning, webhook version, or docs pointer clients can use to detect the transition where applicable.