# Changelog

> Changes to the Beekon Cloud /v1 server API — new endpoints, new members and event types, and anything that could affect an existing integration.

Source: https://docs.getbeekon.com/api/changelog/

Every change to the `/v1` server API is listed here, newest first. Within `/v1` changes are additive (see [Versioning](https://docs.getbeekon.com/api/#versioning)); anything that could still affect an existing integration is marked **Check your integration**.

## SDK 0.6.0

All four SDKs move to 0.6.0: Android (`io.github.beekonlabs:beekon`), iOS (`BeekonKit` from `beekon-ios-binary`), Flutter (`beekon_flutter`) and React Native (`@wayq/beekon-rn`). Flutter and React Native wrap the native 0.6.0 SDKs and have no API change. There are no breaking changes and no change to the local store. Install snippets are on [Quickstart](https://docs.getbeekon.com/start/#1-install).

**Presence and geofencing (Cloud mode)**

* **A phone at rest says so.** When the SDK pauses on its own stationary detection, it tells the server the device is resting; moving again ends that. On iOS the SDK pauses only with Always authorisation, so with When In Use it declares nothing. Under `tracking.when_stationary` `pause` (the default) the server reads a 0.6.0 install by what it says: resting until the project’s [rest limit](https://docs.getbeekon.com/api/remote-config/#presence), moving otherwise. See [device presence](https://docs.getbeekon.com/api/events/#device-presence-events).
* **Sampling near a fence.** A moving device near a fence’s boundary records a location every 5 seconds or 10 metres for at most 120 seconds per approach, uploads at once when it crosses a fence or comes close, and records one fresh location to judge an OS crossing (Android: any crossing without a location, also while paused; iOS: a polygon fence’s crossing). See [Near a fence](https://docs.getbeekon.com/guide/geofencing/#near-a-fence-beekon-cloud).

**Device integrity (Cloud mode)**

* The SDK attests in the background, at most once a day: Android with hardware key attestation (no Google setup), iOS with App Attest (add the App Attest capability). Locations from an attested install are stored with `trust_tier: attested`. Register your apps in the console’s **Apps** tab first. See [Device integrity](https://docs.getbeekon.com/guide/integrity/).
* Uploads refused with `403 attestation_required` (when the project [requires attestation](https://docs.getbeekon.com/guide/integrity/#require-attestation)) keep their locations on the device and send them once it verifies.
* The install id moves out of backup and device transfer (Android: the no-backup files directory; iOS: a this-device-only Keychain item). A phone restored from a backup starts as a new install. Android apps need no backup-rules changes.

**Push token handling**

* Android adds `Beekon.setPushToken(token)` and `Beekon.handlePushMessage(data)`. iOS adds `Beekon.shared.startMonitoringLocationPushes(appGroup:)` and the `BeekonLocationPush` package product for a Location Push Service Extension. They let Beekon Cloud check on a silent device with one push before it reports the device unreachable (the [push probe](https://docs.getbeekon.com/api/events/#the-push-probe)).
* The probe is still switched off in Beekon Cloud, so these calls change nothing yet: no token is sent while the probe is off. Wire them now and the app answers once the probe is turned on for your project. Flutter and React Native have no API for this yet: call the native methods from the host app.
* The token is never logged. A token copied by a backup restore, or one the push service no longer accepts, is dropped by the server when the push service reports it gone.

Android, in your `FirebaseMessagingService` (Beekon takes no Firebase dependency):

```kotlin
class AppMessagingService : FirebaseMessagingService() {
  override fun onNewToken(token: String) {
    Beekon.setPushToken(token)
  }


  override fun onMessageReceived(message: RemoteMessage) {
    // Beekon's probe is a data message; it shows nothing to the user.
    if (Beekon.handlePushMessage(message.data)) return
    // Not Beekon's: handle your own message.
  }
}


// Once at launch, after Beekon.configure(...) with BeekonConfig.cloud(...) in Application.onCreate
// (a probe can start the process):
FirebaseMessaging.getInstance().token.addOnSuccessListener { Beekon.setPushToken(it) }
```

`handlePushMessage` returns `true` for Beekon’s message and `false` for any other. It returns at once and never throws; the answer runs as a WorkManager job. A force-stopped app receives no FCM message, so it can’t answer.

iOS needs the `com.apple.developer.location.push` entitlement (Apple grants it on request) on the app and the extension, the same App Group on both, and **Always** location authorisation:

```swift
// In the app, at every launch, after configure with the cloud arm:
await Beekon.shared.startMonitoringLocationPushes(appGroup: "group.com.example.app")


// In the Location Push Service Extension target, which links BeekonLocationPush:
import BeekonLocationPush
import CoreLocation


final class LocationPushService: NSObject, CLLocationPushServiceExtension {
  private let beekon = BeekonLocationPush(appGroup: "group.com.example.app")


  func didReceiveLocationPushPayload(
    _ payload: [String: Any], completion: @escaping () -> Void
  ) {
    if beekon.handle(payload, completion: completion) { return }
    completion() // Not Beekon's: handle your own location push first.
  }


  func serviceExtensionWillTerminate() {
    beekon.serviceExtensionWillTerminate()
  }
}
```

**Licensing (Cloud mode)**

* **The delivered licence key is cached on the device** for 30 days after the last successful config fetch. A delivered key that fails verification never replaces a cached one that verifies, and a revoked licence ages out after the 30 days. See [In Cloud mode](https://docs.getbeekon.com/reference/licensing/#in-cloud-mode).

**Fixes**

* The background-location permission rationale no longer says tracking is foreground-only. Tracking started in the foreground keeps running in the background with a while-in-use grant; the background grant adds restart after the app is killed or the device reboots, geofences and the stationary pause.
* Android: near a fence, a parked device whose locations stay within 10 metres no longer keeps the 5-second request running past the 120-second limit.

**Check your integration**

* **Devices that go silent while moving are reported sooner.** With 0.6.0 a device that is not resting gets the moving deadline: twice its upload interval plus 120 seconds, with the interval counted as at least 900 seconds on Android and 60 seconds on iOS (1920 seconds on Android and 720 seconds on iOS with the default 300-second interval), instead of the 12-hour rest limit. Expect more `device.unreachable` events with `presence.reason` `silent_while_moving`, and sooner, as your users update.
* **Trips of a resting device end on the declaration.** A trip ends with `end_reason` `stop` when a 0.6.0 device declares rest, instead of stalling after 10 minutes without contact.
* **More `trust_tier: attested` locations.** The tier is a label and changes nothing unless you turn on Require attestation.

## The locations feed (2026-11-01)

**New endpoint**

* [`GET /v1/locations/feed`](https://docs.getbeekon.com/api/locations/#get-v1locationsfeed) (`locations:read`): every location of the project once, in the order it arrived, from an `lf1_` cursor that is never `null`. Locations a device uploads late appear after your cursor instead of inside a window you already read. Positions are kept for 7 days.

## Presence, trip closure and geofence evidence (2026-11-01)

**New event types**

* [`trip.stalled`](https://docs.getbeekon.com/api/events/#trip-events): an open trip’s device has had no contact for `trips.silence_timeout_seconds`, or was declared unreachable. See [the trip lifecycle](https://docs.getbeekon.com/api/trips/#the-trip-lifecycle).
* [`device.unreachable` and `device.reachable`](https://docs.getbeekon.com/api/events/#device-presence-events): a device with a fence visit or a trip in progress stopped being reachable, and was heard from again.
* Webhook [`event_types`](https://docs.getbeekon.com/api/webhooks/#event-types) accept all three.

**New members and values**

* Geofence events: `detected_at` and `evidence` (`track`, `interpolated`, `corroborated`, `unreachable`) on every event, `occurred_after` on `unreachable` exits, and `late: true` on visits rebuilt from late locations. See [Geofence events](https://docs.getbeekon.com/api/events/#geofence-events).
* Trip events: `detected_at` on all three types.
* The [trip object](https://docs.getbeekon.com/api/trips/#the-trip-object): `status` `stalled`, and `end_reason` `tracking_stopped` (the app called `stop()`) and `silence` (no contact for `trips.finality_timeout_seconds`).
* The [geofence object](https://docs.getbeekon.com/api/geofences/#fence-policies): `pass_through` (`off`, `on`) and `on_unreachable` (`none`, `exit`), always present on output and optional on `POST` and `PUT`.
* [Remote config](https://docs.getbeekon.com/api/remote-config/#trips): `trips.silence_timeout_seconds` (0, or 60–86400; default the effective `max_gap_seconds`), `trips.finality_timeout_seconds` (3600–604800, default 86400), and a [`presence`](https://docs.getbeekon.com/api/remote-config/#presence) section with `rest_limit_seconds` (3600–604800, default 43200). Like `trips` and `filters`, `presence` is kept when a `PUT` leaves it out.

**Changed behaviour**

* **Geofence crossings confirm sooner.** A moving device confirms an enter on its first location clearly inside, and an exit on its first location clearly outside by twice the usual margin. Otherwise a second location at least 10 seconds after the first confirms it; the 30-second rule is gone. A crossing the SDK reports confirms at once on an admitted location in the same upload that does not contradict it. See [What produces a geofence event](https://docs.getbeekon.com/api/geofences/#what-produces-a-geofence-event).
* **Late locations can produce events.** A complete visit in locations that arrive late (up to 72 hours behind) is sent as an enter and an exit with `late: true`.
* **`stop()` closes the trip.** The SDK’s stop report (SDK 0.5.0 and later) closes the open trip with `tracking_stopped`: within seconds in the `in1` region; in other regions, when the region next handles traffic. Before, the trip stayed open until the device next tracked, then closed with `session_change`.
* **Silent devices’ trips close.** No contact for `finality_timeout_seconds` closes an open or stalled trip with `silence`.
* **Dwell respects presence.** A dwell is not sent for a device that became unreachable before the dwell time was reached, or while its visit is unverified.

**Check your integration**

* **Endpoints with `event_types: null` receive the three new types.** `null` means every type. Skip types you don’t know, or give the endpoint an explicit list of the types it handles.
* **A geofence event’s `location` can be absent.** An exit with `evidence: unreachable` has no `location`; its time is the window from `occurred_after` to `occurred_at`. You only get these from fences you set to `on_unreachable: exit`. Don’t read `location` unconditionally.
* **`trip.ended` can fire without a new location.** A `tracking_stopped` or `silence` close comes from the device’s stop report or from the server’s clock, not from a location, so `ended_at` (the last location’s time) can be hours before `detected_at`.
* **A trip’s `status` can be `stalled`.** Code that reads any `status` other than `open` as closed must check for `closed`. A stalled trip can still return to `open` and grow.
* **Ignore a `trip.stalled` that arrives after its trip’s `trip.ended`**, and between two `trip.stalled` events for one trip, keep the higher `trip.revision`. A trip’s `revision` now also rises on each stall and each return to `open`.
* **`session_change` is rarer.** Trips that used to close with `session_change` at the next `start()` now close with `tracking_stopped` when the app calls `stop()`.
* **More geofence events, earlier.** Events can fire on one location. A fast drive-through of a small fence that used to send nothing now sends an enter and an exit when one moving location lands clearly inside, or, with no location inside, when the fence has `pass_through: on`.
* **A `late` event is history.** Its `occurred_at` can be hours or days old, and it never says where the device is now. Don’t update a device’s current state from it.
* **Treat an `evidence` value you don’t know** as “decided by the server, evidence unknown”.
* **A geofence `PUT` resets the policies you leave out.** A `PUT` built from a geofence read before this release has no `pass_through` or `on_unreachable`, and resets both to `off` and `none`. Read the fence again before you replace it.
* **`features.presence_probe` belongs to the server.** A config `PUT` that carries it is `400 invalid_config: features.presence_probe`. `GET /v1/config/document` never shows it, so a read-modify-write of the document is safe; don’t copy `features` from what devices receive. The flag belongs to the optional [push probe](https://docs.getbeekon.com/api/events/#the-push-probe), which arrives switched off with this release. Turning it on needs the region to enable it, push credentials and an SDK release after 0.5.0. Until then no event carries `presence.probe_unanswered`.
* **Server-key uploads don’t count as contact.** A device whose locations reach Beekon only through server-key uploads to `POST /v1/ingest` never produces presence events, and its trips never stall or close with `silence`. The SDK’s own uploads to the same endpoint are contact.
* **Know the limits.** A dead or force-stopped phone is reported `unreachable`, never located; an iOS app the user force-quits may leave the decision to presence; and a faked location on a rooted or jailbroken device is judged like any other. See [known limits](https://docs.getbeekon.com/api/geofences/#what-produces-a-geofence-event).

## Documentation corrections (2026-11-01)

* The webhook pages now say **endpoint**, the console’s word, for what they called a subscription. The API object is still `webhook`, and deliveries still carry `Beekon-Subscription`.
* [Errors](https://docs.getbeekon.com/api/errors/#exact-bodies) lists `503 credential status unavailable`, which any authenticated endpoint can answer when the server cannot read whether the token’s key is still active. It carries `Retry-After`; retry after it.
* [Authentication](https://docs.getbeekon.com/api/authentication/#rotating-and-revoking-keys) gives the real bound for a revoked key’s tokens: at most 2 seconds after the revocation reaches the region.

## Trip events (2026-10-23)

**New event types**

* [`trip.started`](https://docs.getbeekon.com/api/events/#trip-events) when a trip is first stored, and `trip.ended` when it is first closed. Each carries the [trip object](https://docs.getbeekon.com/api/trips/#the-trip-object) as it was then. Webhook `event_types` accept both. A trip that was already open when trip events were switched on in its region sends a `trip.ended` without a `trip.started`.

**Check your integration**

* **Endpoints with `event_types: null` receive trip events.** `null` means every type. Skip types you don’t know, as always.
* **Billing usage events now appear in `GET /v1/events`.** `billing.usage_threshold` events were meant to be in the feed, and these pages said they were, but the feed did not return them. It does now. Usage events produced before this change appear once, at the point in the feed where this change landed, so expect a few older `occurred_at` values there. Deduplicate on `id` as usual.

## Stricter input checks (2026-10-23)

**Check your integration**

* **Ingest refuses bad locations.** On [`POST /v1/ingest`](https://docs.getbeekon.com/api/ingest/#errors), a location or geofence event without a `timestamp`, a latitude outside −90…90, a longitude outside −180…180, a negative `accuracy`, or a NUL character in `device.install_id` or `session_id` is now `400 invalid batch` for the whole batch. A location with no timestamp used to be dropped under `200`.
* **A NUL character in the locations `install_id` filter** is `400 invalid_install_id`.
* **A whitespace-only geofence name** is `400 invalid_name`.
* **Every `429` and `503` carries `Retry-After`.**
* **Keys take effect at once.** A newly issued or revoked key works, or stops, straight away. Still retry a `401 unknown project key` for up to 60 seconds before you alert. See [Authentication](https://docs.getbeekon.com/api/authentication/#expiry-and-re-minting).

**Documentation**

* Corrections across the API pages and `openapi.yaml`: every operation now declares `429` and `503`, `GET /v1/events` reads the first of a repeated `limit`, and the two ingest `503`s a retry cannot fix are named.

## Security fixes (2026-10-19)

**Check your integration**

* **Revoked keys end their tokens.** A session token minted from a server key stops working at most 2 seconds after the key’s revocation or rotation reaches the region (`401 invalid session token`). The [Authentication](https://docs.getbeekon.com/api/authentication/#rotating-and-revoking-keys) page said such tokens stayed valid until they expired; that was wrong. Move to the new key before you revoke the old one.
* **Device command bodies are capped at 16 KiB.** A larger body to `POST /v1/devices/{install_id}/commands` is `400 invalid_body`. A real command is a few hundred bytes, so no valid request is affected.
* **Geofence vertex limit checked first.** A geometry over your plan’s vertex limit is now `409 quota_vertices` even when it also crosses itself (it was `400 self_intersection`). The cheaper geometry checks still answer `400` first, and a `PUT` to an unknown id is still `404 not found`. See [Limits](https://docs.getbeekon.com/api/geofences/#limits).

**Documentation**

* [Users](https://docs.getbeekon.com/api/users/): `GET /v1/users`, `GET /v1/users/{user_id}`, `GET /v1/users/{user_id}/devices` and `DELETE /v1/users/{user_id}`, the `users:read` and `users:write` [scopes](https://docs.getbeekon.com/api/scopes/), the device object’s `user_id` member and the `GET /v1/devices` `user_id` filter. These shipped with [the full server-key surface](#the-full-server-key-surface) and were missing from these pages (`openapi.yaml` already had them).
* [Ingest](https://docs.getbeekon.com/api/ingest/): `extras` over 4 KiB is `400 invalid batch`; the `413` extras bound is the extras’ size times the batch’s locations, over 256 KiB.

## The full server-key surface

**New endpoints**

* [`GET /v1/project`](https://docs.getbeekon.com/api/project/): the project a key belongs to.
* [Devices](https://docs.getbeekon.com/api/devices/): `GET /v1/devices`, `GET /v1/devices/{install_id}`, and `POST /v1/devices/{install_id}/commands` (`flush`, `upload_logs`).
* [Users](https://docs.getbeekon.com/api/users/): `GET /v1/users`, `GET /v1/users/{user_id}`, `GET /v1/users/{user_id}/devices` and `DELETE /v1/users/{user_id}`, with the `users:read` and `users:write` scopes.
* [Trips](https://docs.getbeekon.com/api/trips/): `GET /v1/trips`, `GET /v1/trips/{trip_id}` and `GET /v1/trips/{trip_id}/points`, from server-side trip detection.
* [Geofences](https://docs.getbeekon.com/api/geofences/): list, create, read, replace and delete.
* [Remote config](https://docs.getbeekon.com/api/remote-config/): `GET` and `PUT /v1/config/document`, including the `trips` and `filters` sections, with `ETag` / `If-Match`.
* [Webhook endpoints](https://docs.getbeekon.com/api/webhooks/): list, create, read, `PATCH`, delete, `rotate-secret` (with `expire_previous`) and `ping`.

**New members and values**

* Locations carry a [`mode`](https://docs.getbeekon.com/api/location-mode/), always present, and `GET /v1/locations` takes a `mode` filter (`400 invalid_mode`).
* A new event type, [`webhook.ping`](https://docs.getbeekon.com/api/events/#ping-events), sent only to an endpoint you ping. Consumers that skip unknown types already handle it.
* New error statuses on the new endpoints: `409`, `412 precondition_failed`, `413 too_large` and `503 unavailable, retry`. See [Errors](https://docs.getbeekon.com/api/errors/).
* A path under `/v1` that no endpoint serves now answers `404` with the JSON body `{"error":"not found"}`, and a method a path does not serve answers `405` with `{"error":"method_not_allowed"}` and an `Allow` header. Both used to be plain text.

**Check your integration**

* **Scopes.** Every server endpoint now requires a [scope](https://docs.getbeekon.com/api/scopes/). Keys issued before scopes keep exactly what they could reach before (`events:read`, `locations:read`, `locations:write`) and reach none of the new endpoints. Issue a new key with the scopes you need. A key without a route’s scope gets `403 insufficient scope`.
* **Webhook secret rotation.** A rotation now keeps the previous secret until the next rotation, and deliveries are signed with both. The old secret can be retired once real-event deliveries verify with the new one; see [Secret rotation](https://docs.getbeekon.com/api/webhooks/#secret-rotation).
* **Disabled webhook endpoints.** Deliveries queued for an endpoint that is disabled (by you, or by [auto-disable](https://docs.getbeekon.com/api/webhooks/#auto-disable)) now wait up to 7 days after the event was produced. Older ones are given up and are not sent automatically when you set it `active` again. Catch up on [`GET /v1/events`](https://docs.getbeekon.com/api/events/).

## Location history

* [`GET /v1/locations`](https://docs.getbeekon.com/api/locations/): stored locations for a window, with device, user and admission filters, `lc1_` cursors and retention.

## Events

* [`GET /v1/events`](https://docs.getbeekon.com/api/events/): the project’s event log as a cursor feed, and signed [webhook delivery](https://docs.getbeekon.com/api/webhooks/#the-delivery-request) of the same events.

## Server keys

* `bkserv_` server keys, exchanged for a session token at [`POST /v1/token`](https://docs.getbeekon.com/api/authentication/), and server-side uploads to `POST /v1/ingest`.
