Skip to content

Devices

A device is one install of your app running the Beekon SDK, identified by its install_id. These endpoints show which devices your project has, when each last sent a location, what config and health it last reported, and let your backend ask a device to act.

A device appears once it has either uploaded a location or reported its state. Treat install_id as opaque text: it is whatever the SDK generated, not necessarily a UUID. URL-encode it in a path.

Scope: devices:read · Lists the project’s devices, paged, ordered by install_id in byte order.

Terminal window
curl -s -G https://api.in1.getbeekon.com/v1/devices \
-H "Authorization: Bearer $BEEKON_TOKEN" \
--data-urlencode "limit=100"
ParameterRequiredMeaning
limitno1–500, default 100.
cursornoThe previous page’s next_cursor (prefix dc1_).
user_idnoOnly the devices whose current user_id is exactly this value. 1–256 bytes, valid UTF-8, no control characters; form-encode it (a literal + is %2B). An empty, repeated or invalid value is 400 invalid_user_id. A cursor belongs to its filter: one minted with another user_id, or with none, is 400 cursor_query_mismatch.

Response 200:

{
"devices": [
{
"applied_config_revision": null,
"apply_status": null,
"health": null,
"install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50",
"last_seen": "2026-10-07T06:29:41.120Z",
"model": null,
"platform": null,
"reported_at": null,
"sdk_version": null,
"user_id": null
}
],
"next_cursor": null
}

Scope: devices:read · Reads one device.

Terminal window
curl -s \
https://api.in1.getbeekon.com/v1/devices/2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50 \
-H "Authorization: Bearer $BEEKON_TOKEN"

Response 200: {"device":{…}}, the device object. A device that has never uploaded a location or reported its state is 404 not found.

{
"applied_config_revision": 7,
"apply_status": "success",
"health": {
"battery_percent": 81,
"is_charging": false,
"location_enabled": true,
"pending_fixes": 0,
"permission": "always",
"sync_errors": 0
},
"install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50",
"last_seen": "2026-10-07T06:29:41.120Z",
"model": "Pixel 8",
"platform": "android",
"reported_at": "2026-10-07T06:25:03.000Z",
"sdk_version": "0.6.0",
"user_id": "acct_9931"
}

All ten members are always present. Every member except install_id is null until the device has reported it. A device whose locations only ever arrive through POST /v1/ingest keeps reported_at, applied_config_revision, apply_status and health at null: only the SDK reports them.

MemberTypeMeaning
install_idstringThe device’s identifier, as the SDK generated it.
last_seenstring | nullWhen the device last uploaded a location. null if it never has (for example, a device that reported its state but has no location permission).
reported_atstring | nullWhen the device last reported its state (applied config and health).
applied_config_revisioninteger | nullThe remote config revision the device last applied.
apply_statusstring | nullHow that apply went: success, partial (applied, but a device constraint degraded an effect, such as the geofence cap or a missing permission) or failed (the document was unusable and the device kept its previous config).
healthobject | nullThe device’s last health snapshot, passed through as the device sent it. Each member is optional: permission (always, when_in_use, denied, restricted, not_determined), location_enabled, pending_fixes, sync_errors, log_rows, last_error, battery_percent, is_charging, power_save_mode.
platformstring | nullThe platform the SDK reported, such as android or ios.
sdk_versionstring | nullThe SDK version the device runs.
modelstring | nullThe device model.
user_idstring | nullThe user on the device’s newest admitted location: the id your app set with setUserId, exactly as sent. null when that location carried no user id, or the device has no admitted location still stored. It changes only when your app sets another user. See Users.

Ignore members you don’t know, inside health too: newer SDKs may report more.

The device object does not say whether the server can still reach the device: presence is not part of /v1/devices. Presence reaches you as device.unreachable and device.reachable events.

Scope: devices:write · Queues a command for one device. The device receives it on its next upload or config poll, runs it, and reports it done. A device never acts on a command after its expires_at. Commands are fire-and-forget: no endpoint reads a command’s status or tells you when the device ran it. The only response is this one, which says the command was queued.

Terminal window
INSTALL_ID=2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50
curl -s -X POST \
"https://api.in1.getbeekon.com/v1/devices/$INSTALL_ID/commands" \
-H "Authorization: Bearer $BEEKON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "upload_logs",
"params": {"since": "2026-10-07T00:00:00.000Z"},
"ttl_seconds": 86400
}'

Body

MemberTypeRequiredMeaning
typestringyesflush or upload_logs.
paramsobjectnoThe command’s parameters, below. Absent means {}.
ttl_secondsintegernoHow long the command waits for the device, in seconds: 60 (1 minute) to 604800 (7 days). Default 3600.
typeparamsWhat the device does
flushnone: {} or absentUploads its queued locations now.
upload_logsoptional since and until, each a timestamp in exactly YYYY-MM-DDTHH:MM:SS.mmmZ form, with since not after until (both inclusive)Uploads the diagnostic log entries in that range from its local log buffer to Beekon, for support and troubleshooting. No /v1 endpoint reads uploaded logs today.

Response 201:

{
"command": {
"id": "0199b2d0-6c1e-7a40-8f00-3c2b1a090807",
"type": "upload_logs",
"expires_at": "2026-10-08T06:30:00.000Z",
"install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50",
"params": {"since": "2026-10-07T00:00:00.000Z"}
}
}
MemberMeaning
idThe command id.
install_idThe target device.
type, paramsAs sent. params is {} when you sent none.
expires_atWhen the command is dropped if the device has not picked it up.

Errors

The body is checked in this order, and the first problem wins:

StatuserrorWhen
400invalid_bodyNot one JSON object, trailing data, a member other than type, params and ttl_seconds (matched case-sensitively), or a body over 16 KiB.
400invalid_typetype missing, not a string, or not flush / upload_logs.
400invalid_paramsparams not an object; any member on flush; a member other than since / until on upload_logs; a timestamp in any other form; or since after until.
400invalid_ttl_secondsNot a JSON integer (a string, a fraction or null included), or outside 60–604800.
404not foundNo such device in your project. The body is checked first, so a bad body is a 400 even for an unknown device.
409too_many_active_commandsThe device already has 20 active commands.
StatuserrorWhen
400limit must be an integer in [1, 500] · invalid_cursor · cursor_query_mismatchBad paging on the list.
400invalid_user_idA bad user_id filter.
401missing bearer token · invalid session tokenNo valid session.
403server credentials requiredThe token was minted from an SDK key.
403insufficient scopeThe key lacks devices:read (reads) or devices:write (commands).
404not foundUnknown device.
500internal errorA failure on our side. Retry with backoff.