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.
GET /v1/devices
Section titled “GET /v1/devices”Scope: devices:read · Lists the project’s devices, paged, ordered by
install_id in byte order.
curl -s -G https://api.in1.getbeekon.com/v1/devices \ -H "Authorization: Bearer $BEEKON_TOKEN" \ --data-urlencode "limit=100"| Parameter | Required | Meaning |
|---|---|---|
limit | no | 1–500, default 100. |
cursor | no | The previous page’s next_cursor (prefix dc1_). |
user_id | no | Only 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}GET /v1/devices/{install_id}
Section titled “GET /v1/devices/{install_id}”Scope: devices:read · Reads one device.
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.
The device object
Section titled “The device object”{ "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.
| Member | Type | Meaning |
|---|---|---|
install_id | string | The device’s identifier, as the SDK generated it. |
last_seen | string | null | When 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_at | string | null | When the device last reported its state (applied config and health). |
applied_config_revision | integer | null | The remote config revision the device last applied. |
apply_status | string | null | How 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). |
health | object | null | The 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. |
platform | string | null | The platform the SDK reported, such as android or ios. |
sdk_version | string | null | The SDK version the device runs. |
model | string | null | The device model. |
user_id | string | null | The 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.
Send a command
Section titled “Send a command”POST /v1/devices/{install_id}/commands
Section titled “POST /v1/devices/{install_id}/commands”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.
INSTALL_ID=2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50curl -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
| Member | Type | Required | Meaning |
|---|---|---|---|
type | string | yes | flush or upload_logs. |
params | object | no | The command’s parameters, below. Absent means {}. |
ttl_seconds | integer | no | How long the command waits for the device, in seconds: 60 (1 minute) to 604800 (7 days). Default 3600. |
type | params | What the device does |
|---|---|---|
flush | none: {} or absent | Uploads its queued locations now. |
upload_logs | optional 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"} }}| Member | Meaning |
|---|---|
id | The command id. |
install_id | The target device. |
type, params | As sent. params is {} when you sent none. |
expires_at | When 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:
| Status | error | When |
|---|---|---|
| 400 | invalid_body | Not one JSON object, trailing data, a member other than type, params and ttl_seconds (matched case-sensitively), or a body over 16 KiB. |
| 400 | invalid_type | type missing, not a string, or not flush / upload_logs. |
| 400 | invalid_params | params 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. |
| 400 | invalid_ttl_seconds | Not a JSON integer (a string, a fraction or null included), or outside 60–604800. |
| 404 | not found | No such device in your project. The body is checked first, so a bad body is a 400 even for an unknown device. |
| 409 | too_many_active_commands | The device already has 20 active commands. |
Errors on every device endpoint
Section titled “Errors on every device endpoint”| Status | error | When |
|---|---|---|
| 400 | limit must be an integer in [1, 500] · invalid_cursor · cursor_query_mismatch | Bad paging on the list. |
| 400 | invalid_user_id | A bad user_id filter. |
| 401 | missing bearer token · invalid session token | No valid session. |
| 403 | server credentials required | The token was minted from an SDK key. |
| 403 | insufficient scope | The key lacks devices:read (reads) or devices:write (commands). |
| 404 | not found | Unknown device. |
| 500 | internal error | A failure on our side. Retry with backoff. |