Skip to content

Server API overview

The Beekon Cloud server API lets your own backend read and manage a project over HTTPS: the project itself, devices and the commands you send them, your app’s users, location history (and uploading locations from your server), trips, geofences, remote configuration, the event log and webhook endpoints. It is a plain JSON-over-HTTP API under /v1, authenticated with a server key. Where a path or field name says “point” (such as /points or point_count), it means a stored location (see Concepts).

The machine-readable description is openapi.yaml (OpenAPI 3.1). It describes the same endpoints, parameters and responses as these pages. It leaves out the device-only endpoints and the webhook delivery request. For the delivery and its headers, see Webhooks.

Every Beekon project lives in one region (a cell). Each region has its own API host, and you call the host of the region your project lives in:

https://api.<cell>.getbeekon.com

You never need to look the cell up: it is the second segment of your key. A server key bkserv_in1_… belongs to cell in1, so its base URL is https://api.in1.getbeekon.com. There is no global host that forwards to the right region. A key presented to another region’s host is refused with 401, exactly like an unknown key.

The host is the only part that changes. If you were given another base URL (a staging host you were told to use), send the same /v1 paths to that host instead, for example http://localhost:8080/v1/token. The examples on these pages use the Cloud host.

Each host also answers GET /healthz and GET /readyz: unauthenticated liveness and readiness checks with minimal bodies. They are not part of /v1.

SDK (project) keyServer key
Prefixbkproj_<cell>_…bkserv_<cell>_…
Lives inyour mobile appyour backend only. Never ship it in an app.
Used forthe SDK’s uploads and config pollingthis API
Permissionsthe device endpoints the SDK needsthe scopes chosen when the key was issued

Both kinds are exchanged for a short-lived session token at the same endpoint. You send the session token, never the key, on every other call. A session minted from an SDK key is refused by every server endpoint (403) except POST /v1/ingest, where the SDK uploads its locations. A session minted from a server key is refused by the device-only endpoints.

Server keys are issued per project by a project owner or admin. The scopes are fixed at issue: to change them, issue a new key with the scopes you want and revoke the old one.

Every example on these pages uses the same placeholder key and region, bkserv_in1_… on api.in1.getbeekon.com. Replace both with your own.

Terminal window
export BEEKON_SERVER_KEY='bkserv_in1_REPLACE_WITH_YOUR_SECRET'
export BEEKON_TOKEN=$(curl -s -X POST https://api.in1.getbeekon.com/v1/token \
-H "Authorization: Bearer $BEEKON_SERVER_KEY" | jq -r .access_token)

The response is {"access_token":"eyJhbGciOiJFUzI1NiIs…","expires_in":3600}. Send Authorization: Bearer $BEEKON_TOKEN on every other /v1 call. Mint a new token when it expires or when a call answers 401. See Authentication.

Method and pathScopePage
POST /v1/tokennone (takes the key)Authentication
GET /v1/projectproject:readProject
GET /v1/devicesdevices:readDevices
GET /v1/devices/{install_id}devices:readDevices
POST /v1/devices/{install_id}/commandsdevices:writeDevices
GET /v1/usersusers:readUsers
GET /v1/users/{user_id}users:readUsers
GET /v1/users/{user_id}/devicesusers:readUsers
DELETE /v1/users/{user_id}users:writeUsers
GET /v1/locationslocations:readLocations
GET /v1/locations/feedlocations:readLocations
POST /v1/ingestlocations:writeIngest
GET /v1/tripstrips:readTrips
GET /v1/trips/{trip_id}trips:readTrips
GET /v1/trips/{trip_id}/pointstrips:readTrips
GET /v1/geofencesgeofences:readGeofences
POST /v1/geofencesgeofences:writeGeofences
GET /v1/geofences/{fence_id}geofences:readGeofences
PUT /v1/geofences/{fence_id}geofences:writeGeofences
DELETE /v1/geofences/{fence_id}geofences:writeGeofences
GET /v1/config/documentconfig:readRemote config
PUT /v1/config/documentconfig:writeRemote config
GET /v1/configconfig:readThe SDK’s own config fetch, not part of this API. From your server, read GET /v1/config/document.
GET /v1/eventsevents:readEvents
GET /v1/webhookswebhooks:readWebhooks
POST /v1/webhookswebhooks:writeWebhooks
GET /v1/webhooks/{webhook_id}webhooks:readWebhooks
PATCH /v1/webhooks/{webhook_id}webhooks:writeWebhooks
DELETE /v1/webhooks/{webhook_id}webhooks:writeWebhooks
POST /v1/webhooks/{webhook_id}/rotate-secretwebhooks:writeWebhooks
POST /v1/webhooks/{webhook_id}/pingwebhooks:writeWebhooks
  • JSON in, JSON out. Timestamps are RFC 3339 UTC with exactly three fractional digits (2026-10-07T06:30:00.000Z).
  • The project comes from the token. No path, query parameter or body names a project. Query parameters an endpoint does not define, including project_id, are ignored.
  • Optional members are omitted, never null, except the members documented as nullable, such as next_cursor.
  • One error shape: {"error":"<text>"}. See Errors.
  • Cursor paging on every list: limit 1–500 and an opaque cursor. See Pagination.

The full set is on Conventions.

The path version /v1 is a promise: within /v1 we only make additive changes: new endpoints, new optional members, new enum values and new event types. Your client must ignore response members and enum values it does not recognise. Removing or renaming a member, changing a member’s type, or changing the meaning of an existing value is a breaking change. It ships under a new version, never silently under /v1.

The locations page and event payloads also carry a schema_version (currently 1). It changes only on a breaking change to that document. If you meet a schema_version you do not understand, fail loudly rather than parsing optimistically.

Beekon is pre-1.0: until 1.0, a breaking change to /v1 remains possible. It is announced in the changelog, never shipped silently.