> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telemax.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Version history, deprecation notices, and the Telemax API deprecation policy.

## Deprecation policy

When an endpoint or field is deprecated:

1. A deprecation notice is added to this changelog and to the relevant endpoint reference page.
2. The live API begins returning a `Sunset` HTTP response header (RFC 8594) on every call to the deprecated route, with the removal date as an HTTP-date value:
   ```
   Sunset: Sat, 14 Oct 2026 23:59:59 GMT
   ```
3. The endpoint **continues to work** for a minimum of **6 months** from the deprecation notice date.
4. After the Sunset date the route may return `410 Gone` or be removed entirely.

<Note>
  If you receive a `Sunset` header in an API response, plan your migration before the date shown. Contact [Telemax support](https://telemax.com.au/contact/) if you need an extension.
</Note>

## API versioning

All V2 responses include an `X-API-Version` response header containing the major API version number:

```
X-API-Version: 2
```

V1 responses do not include this header. Use its presence to detect which version you are talking to.

URL paths encode the version directly (`/v2/api/...` vs `/api/...`). The `X-API-Version` header provides a redundant signal for integration monitoring.

***

## Version history

### 2026-04-28 — API V2 release

#### Added

**Infrastructure (V2 only)**

* Rate limiting middleware — 60 requests per 60-second sliding window per token; returns `429` with `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers
* Exception middleware — all V2 errors return a standardised `ApiError` JSON body (`type`, `code`, `description`, `requestId`, `docUrl`)
* `X-API-Version: 2` response header on all V2 responses

**Authentication**

* `POST /v2/api/authentication/token/user` — V2 user login
* `POST /v2/api/authentication/token/api-key` — V2 API key login

**Companies & fleet**

* `GET /v2/api/companies` — paginated list of accessible companies
* `GET /v2/api/companies/{id}/vehicles/last-position` — paginated fleet-wide last positions
* `GET /v2/api/companies/{id}/vehicles/nearest` — nearest vehicles to a coordinate (paginated)
* `GET /v2/api/companies/{id}/vehicles/last-time-online` — paginated fleet last-seen timestamps
* `GET /v2/api/companies/{id}/alert-records` — paginated alert records
* `GET /v2/api/companies/{id}/alerts` — **new** — paginated alert configurations with string `AlertType` and linked vehicle/tag lists
* `PUT /v2/api/companies/{id}/set-all-alerts-read` — mark all company alert records as read

**Vehicles**

* `POST /v2/api/vehicles/list` — paginated vehicle list
* `GET /v2/api/vehicles/{id}/last-position` — last known position for a vehicle
* `GET /v2/api/vehicles/{id}/positions` — paginated position history
* `GET /v2/api/vehicles/info` — **new** — look up vehicle metadata by IMEI, vehicle ID, or VIN
* `GET /v2/api/vehicles/{id}/last-online` — last-seen timestamp for a vehicle
* `GET /v2/api/vehicles/{imei}/device-ids` — IMEI → vehicle ID lookup
* `GET /v2/api/vehicles/{id}/engine-codes` — **enriched** — paginated engine codes with AI analysis, severity, and detection location

**Vehicle commands**

* `PUT /v2/api/vehicles/{id}/odometer` — update odometer
* `PUT /v2/api/vehicles/{id}/name` — rename vehicle
* `POST /v2/api/vehicles/{id}/ignition` — send ignition command
* `PUT /v2/api/vehicles/{id}/door-lock` — send door lock/unlock command

**Alerts**

* `PUT /v2/api/alerts/{id}/{date}/update-read-status` — **new** — mark a single alert record as read or unread

**Telemetry & replay**

* `GET /v2/api/replay/{id}` — paginated trip replay

**Insights & diagnostics**

* `GET /v2/api/safety-score/{id}` — trip safety score
* `GET /v2/api/battery-health` — paginated battery health predictions

**Webhooks (all new)**

* `POST /v2/api/webhooks` — create a webhook; response includes the plaintext HMAC secret (returned once only)
* `GET /v2/api/webhooks/{id}` — get a webhook by ID
* `GET /v2/api/webhooks` — paginated list of company webhooks
* `PUT /v2/api/webhooks/{id}` — update webhook URL, active state, or linked alerts
* `DELETE /v2/api/webhooks/{id}` — soft-delete a webhook
* `POST /v2/api/webhooks/{id}/link-alert` — link an alert configuration to a webhook

Webhook deliveries are signed with HMAC-SHA256; each request carries `X-Telemax-Signature: sha256=<hex>` and `X-Telemax-Delivery: <uuid>`.

***

### 2026-04-28 — GetSafetyScore parameter updates

#### Changed

**Insights & diagnostics**

* `POST /api/GetSafetyScore` — `vehicleId` parameter renamed from `id` (breaking for clients using the old name)
* `POST /api/GetSafetyScore` — `start` and `finish` are now optional; omit both and supply `intervalType` to use a preset time window
* `POST /api/GetSafetyScore` — new `intervalType` parameter: `1` = instant range, `2` = relative to end of local day, `3` = three-day window, `4` = week window. Validate preset windows in staging before relying on them (see endpoint reference for the known date-arithmetic quirk)

***

### 2026-04-14 — v1 (Initial public documentation)

#### Added

**Authentication**

* `POST /api/Authentication/token/user` — JWT via username + password
* `POST /api/Authentication/token/api-key` — JWT via API key

**Companies & fleet**

* `POST /api/GetCompanies` — list accessible companies
* `POST /api/GetAllLastPositionData/{companyId}` — fleet-wide last positions
* `POST /api/GetNearestVehicles` — nearest vehicles to a coordinate
* `POST /api/devices` — vehicle list for a company
* `POST /api/GetAllLastTimeOnline` — last-seen timestamps for all vehicles

**Telemetry**

* `POST /api/GetLastPositionData` — latest position for one vehicle
* `POST /api/GetPositionData` — historical positions for one vehicle
* `POST /api/GetReplay` — trip replay (UTC time context)
* `POST /api/GetReplayUserTime` — trip replay (user timezone context)
* `GET /api/GetDeviceId` — IMEI → vehicle ID lookup

**Alerts**

* `POST /api/GetAlerts` — list alerts for a company
* `POST /api/SetAlertAsRead` — mark one alert as read
* `POST /api/SetAllAlertAsRead` — mark all company alerts as read

**Insights & diagnostics**

* `POST /api/GetCompanyVehiclesBatteryHealth` — paged battery predictions
* `POST /api/GetSafetyScore` — trip safety score for a vehicle
* `GET /api/devices/{id}/dtc-codes` — latest DTC codes from vehicle handler state

**Vehicle commands**

* `POST /api/ChangeOdometer` — update odometer value
* `POST /api/SetVehicleName` — rename a vehicle
* `POST /api/UpdateLocation` — trigger device location update
* `POST /api/SendIgnition` — send ignition enable/disable command
* `POST /api/LastTimeOnline` — last-seen timestamp for one vehicle
* `POST /api/SendDoorLock` — send door lock command (ATrack SMS path)

**Operations**

* `POST /api/Test` — anonymous connectivity health check

#### Deprecated

* `POST /api/rebuild-vehicle-movement-cache` — removed from public API reference (internal dev/ops only; not for integration partners).

***

*This changelog follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.*
*Future entries will appear at the top of the Version history section, newest first.*