Versioning

• The major version is in the path: https://app.timetracking.tech/api/v1.
• The spec version is in info.version of GET /api/v1/openapi.json. It is currently 1.1.0.
• /v1 is stable. Breaking changes get a new major path (/v2), and the old version keeps running for at least 12 months (as stated in the spec description).

Non-breaking changes (can happen within v1)

• New endpoints, new optional request fields, new query parameters.
• New fields in responses. Clients must ignore unknown fields. For example, v1.1 added external_source/external_ref to people, clients and placements.
• New webhook event types (you only receive the events you subscribe to) and new fields in event data.
• New enum values in fields that are documented as open: hourType, source, error messages.
• New error codes for new situations.

Breaking changes (only in a new major version)

• Removing or renaming endpoints, fields or event types.
• Changing a field's type or unit (minutes stay minutes, cents stay cents).
• Making an optional request field required.
• Changing the default shape of an existing response. v1.1 therefore returns {items, next_cursor} on /people, /clients and /placements only when you send a paging parameter (see pagination).

Detecting the version

curl -s https://app.timetracking.tech/api/v1/openapi.json | jq -r .info.version
# 1.1.0

Each operation in the spec has a stable operationId (e.g. getOrgWeek, listDays, upsertPersonByExternal). Use these for client generation.

Client generation

The spec is OpenAPI 3.1 with response schemas, so generators such as openapi-typescript or openapi-python-client work:

npx openapi-typescript https://app.timetracking.tech/api/v1/openapi.json -o timetracking.d.ts

Planned: official TypeScript and Python SDKs.

See the changelog for what changed per version.