> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API changelog

> Track public API and schema changes, client impact, deprecations, and migration requirements.

The JobHandy Public API remains version `1.0.0` on the `/v1` base path.

## 2026-09-02 - 1.0.0

### Incidents

* `POST /incidents` now returns `422 EMPLOYEE_NOT_ACTIVATED` when the referenced employee exists in the authorized scope but has not completed activation.
* The error message is `The referenced employee is not activated.`
* No incident is created when this validation fails.

### Client impact

Do not retry the same create request until employee activation has completed. After activation, submit a new request with a new `X-Request-ID`.

## 2026-08-28 - 1.0.0

### Orders

* Removed `tenant` and `divisionId` from the `Order` response schema.
* Replaced `hrReviewDecision` and `OrderHrReviewDecision` with `hrHistory` and `OrderHrHistory`.
* `hrHistory.decisionBy` now contains a nullable 24-character user ID. It is `null` for automated and API-key decisions.
* Replaced the `OrderProduct` model returned in `products[]` by `GET /orders`, `GET /orders/{id}`, and `POST /orders/{id}/decision`.
* Added `model`, `vatRate`, `manufacturerName`, `articleGroupName`, `grossAmount`, `netAmount`, `service`, `grossService`, and `netService` to `OrderProduct`.
* Removed `description`, `rateInCents`, and `serviceRateInCents` from `OrderProduct`.
* `model`, `manufacturerName`, `articleGroupName`, `service`, `grossService`, and `netService` are nullable.
* `vatRate` and `grossAmount` are decimal strings with two decimal places; `netAmount` uses four decimal places. `grossService` and `netService` are nullable decimal strings with two decimal places.

### Order queries

* Removed `tenant` and `divisionId` from the supported filter and sort fields of `GET /orders`.
* Use `X-Tenant-ID` to restrict an order query to one authorized tenant where required.

### Divisions

* Changed `Division.order`, `DivisionCreate.order`, and `DivisionPatch.order` from OpenAPI type `integer` to `number`.
* Removed the previous integer-only `multipleOf: 1` constraint.

### Client impact

The API version remains `1.0.0` and the production base URL remains `https://api.jobhandy.io/v1`. Clients that deserialize order responses must update their models, DTOs, mappings, decimal handling, mocks, and contract tests. Do not infer tenant or division from fields that are no longer present in the `Order` response.

## Initial public scope

### Available resources

* Employees: list, create, get, update
* Orders: list, get, HR decision, attachment download
* Incidents: list, create, get, update, attachment upload
* Divisions: list, create, get, update
* Payroll export documents: list, get, download
* Health: public availability check

### Cross-cutting behavior

* `X-API-Key` authentication
* optional `X-Tenant-ID` tenant selection where documented
* UUID v4/v7 `X-Request-ID` correlation
* page-based collection pagination
* one-field sorting
* filter expression language
* dry-run validation on supported writes
* common structured error envelope
* rate-limit response headers

<Note>
  The OpenAPI document does not encode a publication date for this baseline. Future entries should include an explicit release date and migration impact.
</Note>

## Future entry format

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
## YYYY-MM-DD - Contract version

### Added
### Changed
### Fixed
### Deprecated
### Removed
### Security
### Migration
```

## Client responsibility

Before adopting a new OpenAPI file:

1. Compare it with the version currently used by the client.
2. Identify request, response, schema, enum, endpoint, and error changes.
3. Regenerate or update client types.
4. Run contract and acceptance tests.
5. Record the adopted version and checksum.

<Card title="Versioning policy" icon="git-branch" horizontal href="/concepts/versioning">
  Review which changes are additive and which require migration.
</Card>