# Versioning

> How the TimeTracking API is versioned (/v1 path, spec version 1.1.0), what counts as a breaking change, and how to detect the version you are talking to.

URL: https://timetracking.tech/developers/api/versioning
Last updated: 2026-10-24

- 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 `message`s.
- New error `code`s 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](https://timetracking.tech/developers/api/pagination)).

## Detecting the version

```sh
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:

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

> **Planned:** official TypeScript and Python SDKs.

See the [changelog](https://timetracking.tech/developers/api/changelog) for what changed per version.