# Devices

> List your project's devices, read one device's last reported state, and send a device a command (flush its uploads, or upload its logs) — devices:read and devices:write.

Source: https://docs.getbeekon.com/api/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.

## GET `/v1/devices`

**Scope:** `devices:read` · Lists the project’s devices, [paged](https://docs.getbeekon.com/api/pagination/), ordered by `install_id` in byte order.

```sh
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`:

```json
{
  "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}`

**Scope:** `devices:read` · Reads one device.

```sh
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](#the-device-object). A device that has never uploaded a location or reported its state is `404 not found`.

## The device object

```json
{
  "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`](https://docs.getbeekon.com/api/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](https://docs.getbeekon.com/api/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](https://docs.getbeekon.com/api/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](https://docs.getbeekon.com/api/events/#device-presence-events).

## Send a command

### 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.

```sh
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**

| 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`:

```json
{
  "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. |

Delivery and limits

A command may reach the device more than once; the device runs each command `id` at most once, and never after `expires_at`. A device holds at most **20 active commands** (issued, not yet expired, not yet reported done); a 21st is `409 too_many_active_commands` until one completes or expires.

**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

| 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.                          |
