Changelog

Change history of the Kinmu Public API. Incompatible changes are never applied within a major version: they are introduced in a new version and announced here.

Versioning policy

• The version goes in the URL: https://api.kinmu.app/v1.
• Frozen contract within v1. We do not introduce incompatible changes in v1.

What we consider a compatible change (non-breaking)

These changes can happen in v1 without prior notice; your integration must tolerate them:

• Adding new endpoints or resources.
• Adding new fields to a response.
• Adding new values to an enum documented as extensible (e.g. custom absence types).
• Adding optional query or body parameters.
• Changing the text of error messages (title, detail) — that’s why your logic must be based on the stable code field.

What we consider an incompatible change (breaking)

Requires a new major version (v2):

• Removing or renaming an endpoint, field or enum value.
• Changing the type of a field or making it required.
• Changing the meaning of a field or the code of an error.

Deprecation policy (12 months)

When we deprecate an endpoint, field or version:

1. It is announced in this changelog and in the developer mailing list.
2. It is marked as deprecated in the OpenAPI spec and, where applicable, with the Deprecation + Sunset response headers.
3. It remains operational for at least 12 months from the announcement before being retired.

Subscribe to notices on the support page.

History

2026-08-27 — OpenAPI spec and updated_since

• The spec now declares the 402 and 409 codes and the X-RateLimit-* headers, which the API already emitted.
• The 409 is also declared on POST /v1/reports and on the idempotent webhook operations, where it was missing.
• updated_since implemented on GET /v1/webhook-endpoints.
• updated_since marked deprecated on GET /v1/vacation-balances and GET /v1/work-summaries: it has never filtered on those resources. It is still accepted with no effect — so regenerated SDKs don’t break — and will be removed on 2027-08-27, under the 12-month deprecation policy. For these aggregates, re-query the range (year, from/to). See conventions.

2026-08-20 — employee email unique per company

• Email uniqueness when creating an employee is now per company (it used to be global). Creations that previously failed with 422 because of a collision with another company’s email are now accepted.

2026-08-10 — sandbox and keys are deprovisioned

• Disabling the Public API addon now revokes all API keys (reason addon_disabled), deletes the generated reports and removes the sandbox company along with its data. Re-enabling the addon provisions an empty sandbox and does not restore the keys. See sandbox.

2026-07-31 — subscription gate and revocation

• The subscription gate is tightened: an exhausted trial, a canceled and lapsed subscription, an expired subscription and an archived company now return 403 subscription_inactive on /v1.
• Revoking API keys and webhooks (DELETE) no longer requires an active subscription: cutting off a credential is a security control and must always be available.

2026-07-30 — company settings applied when issuing keys

• API key issuance honors the per-company addon settings: default_expiration_days (expiration applied when you don’t ask for an explicit one) and max_active_keys (cap on active keys, 10 by default).

v1 · 1.0.0

Launch resources (MVP):

• Organization — GET /v1/organization (introspection).
• Employees — list, get, create, update and terminate.
• Check-ins — list, get and record check-ins.
• Work summaries — workday aggregates for payroll.
• Absences — list, get, create, approve and reject.
• Vacation balances — vacation balances.
• Locations / Units — organizational structure (read-only).
• Reports — asynchronous reports (legal time registry and exports), with file download via GET /v1/reports/{id}/download.

Webhooks:

• Signed outgoing events (Standard Webhooks): endpoint management, ping sending, delivery listing and manual re-queue of a delivery via POST /v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry.