Every change to the /v1 server API is listed here, newest first. Within /v1 changes are
additive (see Versioning); anything that could still affect an existing
integration is marked Check your integration.
SDK 0.6.0
Section titled “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.
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_stationarypause(the default) the server reads a 0.6.0 install by what it says: resting until the project’s rest limit, moving otherwise. See device presence. - 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.
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. - Uploads refused with
403 attestation_required(when the project requires 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)andBeekon.handlePushMessage(data). iOS addsBeekon.shared.startMonitoringLocationPushes(appGroup:)and theBeekonLocationPushpackage 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). - 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):
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:
// 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 BeekonLocationPushimport 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.
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.unreachableevents withpresence.reasonsilent_while_moving, and sooner, as your users update. - Trips of a resting device end on the declaration. A trip ends with
end_reasonstopwhen a 0.6.0 device declares rest, instead of stalling after 10 minutes without contact. - More
trust_tier: attestedlocations. The tier is a label and changes nothing unless you turn on Require attestation.
The locations feed (2026-11-01)
Section titled “The locations feed (2026-11-01)”New endpoint
GET /v1/locations/feed(locations:read): every location of the project once, in the order it arrived, from anlf1_cursor that is nevernull. 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)
Section titled “Presence, trip closure and geofence evidence (2026-11-01)”New event types
trip.stalled: an open trip’s device has had no contact fortrips.silence_timeout_seconds, or was declared unreachable. See the trip lifecycle.device.unreachableanddevice.reachable: a device with a fence visit or a trip in progress stopped being reachable, and was heard from again.- Webhook
event_typesaccept all three.
New members and values
- Geofence events:
detected_atandevidence(track,interpolated,corroborated,unreachable) on every event,occurred_afteronunreachableexits, andlate: trueon visits rebuilt from late locations. See Geofence events. - Trip events:
detected_aton all three types. - The trip object:
statusstalled, andend_reasontracking_stopped(the app calledstop()) andsilence(no contact fortrips.finality_timeout_seconds). - The geofence object:
pass_through(off,on) andon_unreachable(none,exit), always present on output and optional onPOSTandPUT. - Remote config:
trips.silence_timeout_seconds(0, or 60–86400; default the effectivemax_gap_seconds),trips.finality_timeout_seconds(3600–604800, default 86400), and apresencesection withrest_limit_seconds(3600–604800, default 43200). Liketripsandfilters,presenceis kept when aPUTleaves 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.
- 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 withtracking_stopped: within seconds in thein1region; in other regions, when the region next handles traffic. Before, the trip stayed open until the device next tracked, then closed withsession_change.- Silent devices’ trips close. No contact for
finality_timeout_secondscloses an open or stalled trip withsilence. - 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: nullreceive the three new types.nullmeans every type. Skip types you don’t know, or give the endpoint an explicit list of the types it handles. - A geofence event’s
locationcan be absent. An exit withevidence: unreachablehas nolocation; its time is the window fromoccurred_aftertooccurred_at. You only get these from fences you set toon_unreachable: exit. Don’t readlocationunconditionally. trip.endedcan fire without a new location. Atracking_stoppedorsilenceclose comes from the device’s stop report or from the server’s clock, not from a location, soended_at(the last location’s time) can be hours beforedetected_at.- A trip’s
statuscan bestalled. Code that reads anystatusother thanopenas closed must check forclosed. A stalled trip can still return toopenand grow. - Ignore a
trip.stalledthat arrives after its trip’strip.ended, and between twotrip.stalledevents for one trip, keep the highertrip.revision. A trip’srevisionnow also rises on each stall and each return toopen. session_changeis rarer. Trips that used to close withsession_changeat the nextstart()now close withtracking_stoppedwhen the app callsstop().- 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
lateevent is history. Itsoccurred_atcan 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
evidencevalue you don’t know as “decided by the server, evidence unknown”. - A geofence
PUTresets the policies you leave out. APUTbuilt from a geofence read before this release has nopass_throughoron_unreachable, and resets both tooffandnone. Read the fence again before you replace it. features.presence_probebelongs to the server. A configPUTthat carries it is400 invalid_config: features.presence_probe.GET /v1/config/documentnever shows it, so a read-modify-write of the document is safe; don’t copyfeaturesfrom what devices receive. The flag belongs to the optional 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 carriespresence.probe_unanswered.- Server-key uploads don’t count as contact. A device whose locations reach Beekon only
through server-key uploads to
POST /v1/ingestnever produces presence events, and its trips never stall or close withsilence. 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.
Documentation corrections (2026-11-01)
Section titled “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 carryBeekon-Subscription. - Errors 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 carriesRetry-After; retry after it. - Authentication 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)
Section titled “Trip events (2026-10-23)”New event types
trip.startedwhen a trip is first stored, andtrip.endedwhen it is first closed. Each carries the trip object as it was then. Webhookevent_typesaccept both. A trip that was already open when trip events were switched on in its region sends atrip.endedwithout atrip.started.
Check your integration
- Endpoints with
event_types: nullreceive trip events.nullmeans every type. Skip types you don’t know, as always. - Billing usage events now appear in
GET /v1/events.billing.usage_thresholdevents 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 olderoccurred_atvalues there. Deduplicate onidas usual.
Stricter input checks (2026-10-23)
Section titled “Stricter input checks (2026-10-23)”Check your integration
- Ingest refuses bad locations. On
POST /v1/ingest, a location or geofence event without atimestamp, a latitude outside −90…90, a longitude outside −180…180, a negativeaccuracy, or a NUL character indevice.install_idorsession_idis now400 invalid batchfor the whole batch. A location with no timestamp used to be dropped under200. - A NUL character in the locations
install_idfilter is400 invalid_install_id. - A whitespace-only geofence name is
400 invalid_name. - Every
429and503carriesRetry-After. - Keys take effect at once. A newly issued or revoked key works, or stops, straight away.
Still retry a
401 unknown project keyfor up to 60 seconds before you alert. See Authentication.
Documentation
- Corrections across the API pages and
openapi.yaml: every operation now declares429and503,GET /v1/eventsreads the first of a repeatedlimit, and the two ingest503s a retry cannot fix are named.
Security fixes (2026-10-19)
Section titled “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 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}/commandsis400 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_verticeseven when it also crosses itself (it was400 self_intersection). The cheaper geometry checks still answer400first, and aPUTto an unknown id is still404 not found. See Limits.
Documentation
- Users:
GET /v1/users,GET /v1/users/{user_id},GET /v1/users/{user_id}/devicesandDELETE /v1/users/{user_id}, theusers:readandusers:writescopes, the device object’suser_idmember and theGET /v1/devicesuser_idfilter. These shipped with the full server-key surface and were missing from these pages (openapi.yamlalready had them). - Ingest:
extrasover 4 KiB is400 invalid batch; the413extras bound is the extras’ size times the batch’s locations, over 256 KiB.
The full server-key surface
Section titled “The full server-key surface”New endpoints
GET /v1/project: the project a key belongs to.- Devices:
GET /v1/devices,GET /v1/devices/{install_id}, andPOST /v1/devices/{install_id}/commands(flush,upload_logs). - Users:
GET /v1/users,GET /v1/users/{user_id},GET /v1/users/{user_id}/devicesandDELETE /v1/users/{user_id}, with theusers:readandusers:writescopes. - Trips:
GET /v1/trips,GET /v1/trips/{trip_id}andGET /v1/trips/{trip_id}/points, from server-side trip detection. - Geofences: list, create, read, replace and delete.
- Remote config:
GETandPUT /v1/config/document, including thetripsandfilterssections, withETag/If-Match. - Webhook endpoints: list, create, read,
PATCH, delete,rotate-secret(withexpire_previous) andping.
New members and values
- Locations carry a
mode, always present, andGET /v1/locationstakes amodefilter (400 invalid_mode). - A new event type,
webhook.ping, 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_largeand503 unavailable, retry. See Errors. - A path under
/v1that no endpoint serves now answers404with the JSON body{"error":"not found"}, and a method a path does not serve answers405with{"error":"method_not_allowed"}and anAllowheader. Both used to be plain text.
Check your integration
- Scopes. Every server endpoint now requires a scope. 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 gets403 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.
- Disabled webhook endpoints. Deliveries queued for an endpoint that is disabled (by
you, or by 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
activeagain. Catch up onGET /v1/events.
Location history
Section titled “Location history”GET /v1/locations: stored locations for a window, with device, user and admission filters,lc1_cursors and retention.
Events
Section titled “Events”GET /v1/events: the project’s event log as a cursor feed, and signed webhook delivery of the same events.
Server keys
Section titled “Server keys”bkserv_server keys, exchanged for a session token atPOST /v1/token, and server-side uploads toPOST /v1/ingest.