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

# Changelog

> Every change to the API, newest first, with its date.

Every change to the API is recorded here, newest first, with its date.

## How the API changes

* **Additive changes are made without notice.** A new field, a new endpoint, a new query parameter or a
  new event type can appear at any time, and is recorded here. Clients must **ignore fields, event
  types and enum values they do not know**.
* **A breaking change is a new version.** Removing or renaming a field, changing a type or a meaning, or
  removing an endpoint ships as `/v2`. `/v1` is never changed in a breaking way.
* **`/v1` lives at least 12 more months** after `/v2` is announced. From the announcement, `/v1` answers
  with a `Deprecation` header (RFC 9745) and, once the shutdown date is set, a `Sunset` header
  (RFC 8594).
* A field the key may not read is left out, not sent as null. Which field group opens which field is part
  of the contract: a new field joins the group that fits it.

## v1 preview, 8 Nov 2026

The first version. The go-live date is to be confirmed; until then the API is in preview and the shape
below may still be refined before it is announced as generally available.

* **Read endpoints:** `GET /v1/employees`, `GET /v1/employees/{id}`, `GET /v1/companies`,
  `GET /v1/org-units`, `GET /v1/positions`, `GET /v1/locations`, `GET /v1/lookups/{type}` (departments,
  cost centres, grades, job titles), `GET /v1/time-off` and `GET /v1/events`. The OpenAPI document is at
  `GET /v1/openapi.json`.
* **Authentication:** a bearer key, `Authorization: Bearer atk_live_…`, created in Settings,
  Integrations, API keys. A key holds companies and field groups, and may carry an IP range and an expiry
  date. A rolled secret works for 24 hours more.
* **Field groups:** Directory, Organisation, Positions, Time off, Personal contact, Personal details and
  Special categories. Special categories need the Information Officer's approval.
* **Rate limits:** 300 requests a minute per key (a burst of 50 in 10 seconds) and 1,200 a minute per
  tenant, with `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and, on a 429, `Retry-After`.
* **Pagination:** `limit` (1 to 500) and an opaque `cursor`; `next_cursor` is null on the last page.
  `updated_since` for incremental reads.
* **Errors:** RFC 9457 `application/problem+json`, each with a stable type URL under
  `https://docs.andteam.com/api/problems/`.
* **Webhooks:** the seven employee events, signed with Standard Webhooks, thin by default with an Include
  details switch per endpoint, retried over about 27 and a half hours.
* **Time off** is returned as dates, shown as Away. The leave type is never exposed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.