# Remote config

> Read and replace your project's remote-config document: tracking, sync, privacy, features, diagnostics, trips, presence and the server's filters, with ETag / If-Match concurrency.

Source: https://docs.getbeekon.com/api/remote-config/

These two endpoints read and replace your project’s **remote config**: the settings your cloud-mode devices fetch, cache and apply. Every real change produces a new revision, which devices pick up on the next sync, or within about two config polls while idle (`poll_interval_seconds`, 300 s by default).

The document also carries sections devices never see: `trips` (how the server cuts and closes [trips](https://docs.getbeekon.com/api/trips/)) and `filters` (how the server judges uploaded locations before [admitting](https://docs.getbeekon.com/api/locations/#admitted-and-gated-locations) them). A third, `presence`, sets when the server declares a device [unreachable](https://docs.getbeekon.com/api/events/#device-presence-events).

## GET `/v1/config/document`

**Scope:** `config:read`

```sh
curl -s -i https://api.in1.getbeekon.com/v1/config/document \
  -H "Authorization: Bearer $BEEKON_TOKEN"
```

**Response** `200` with `ETag: W/"<revision>"` and [the document](#the-document). This endpoint does not answer `If-None-Match`: it always returns `200` and the full document.

## PUT `/v1/config/document`

**Scope:** `config:write` · Replaces the document.

```sh
curl -s -i -X PUT https://api.in1.getbeekon.com/v1/config/document \
  -H "Authorization: Bearer $BEEKON_TOKEN" \
  -H "Content-Type: application/json" \
  -H 'If-Match: W/"1"' \
  -d '{
    "tracking": {"accuracy_mode": "high", "detect_activity": true},
    "sync": {"interval_seconds": 120}
  }'
```

**Response** `200` with the stored document and its new `ETag`, the same as a following `GET`.

### What a `PUT` changes

A `PUT` is a **replace**, with one exception for the server-side sections:

| In your body | `tracking`, `sync`, `privacy`, `features`, `diagnostics`, `poll_interval_seconds` | `trips`, `presence`, `filters`                    |
| ------------ | --------------------------------------------------------------------------------- | ------------------------------------------------- |
| present      | replaced; knobs you leave out take their **defaults**                             | replaced; knobs you leave out take their defaults |
| `null`       | reset to defaults                                                                 | reset to defaults                                 |
| **left out** | reset to defaults                                                                 | **kept as they are**                              |

So the example above sets `accuracy_mode` and `detect_activity`, resets every other `tracking` and `sync` knob to its default, clears `privacy`, `features`, `diagnostics` and `poll_interval_seconds`, and leaves `trips`, `presence` and `filters` untouched. To change one knob, read the document, change the knob, and `PUT` the whole document back (without `revision`).

Read, modify, write

Do not `PUT` a partial document unless you mean to reset everything you left out. The safe pattern is `GET`, edit, then `PUT` with `If-Match` set to the `ETag` you read.

A `PUT` that changes nothing, in any spelling, keeps the current revision. A real change to any section, `filters` included, moves `revision` up.

### Concurrent writers: ETag and If-Match

Send `If-Match` to make the write conditional:

| `If-Match`                                       | Effect                                                                                                                                   |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| absent                                           | The write is unconditional.                                                                                                              |
| `W/"<revision>"`, exactly as the `ETag` you read | The write happens only if `<revision>` is still current; otherwise `412 precondition_failed`, even when your write would change nothing. |
| `*`                                              | The write happens whatever the current revision.                                                                                         |
| anything else                                    | `400 invalid_if_match`.                                                                                                                  |

Only the weak form `W/"7"` is accepted. The strong form `"7"`, a list of tags, an empty value, a leading zero (`W/"07"`) or two `If-Match` headers are all `400 invalid_if_match`. This is stricter than HTTP’s general rules, deliberately: it is the only form the API ever sends.

On a `412`, `GET` the document again, re-apply your change, and retry with the new `ETag`. A `412` carries no `ETag`.

### Validation

The body must be one JSON object of at most 65536 bytes. Every value is checked; nothing is clamped or adjusted.

The server reports **every** offending member in one answer, as dotted paths in ASCII order:

```json
{
  "error": "invalid_config: revision, sync.batch_size, tracking.speed"
}
```

A member offends when it is unknown (at any level, `project_id` included), server-owned (`revision`, `schema_version`, `service_state`, `license_jws`, even as `null`, and `features.presence_probe` with any value), of the wrong type (a boolean is never a number), out of range, not an integer where one is required (`250.0` and `2.5e2` count as the integer 250), or an unknown enum value. A section that is not an object is reported by its own name (`trips`). A bad feature-flag key, or more than 64 keys, is reported as `features`; a non-boolean flag as `features.<key>`. A `null` knob takes its default, and a `null` feature flag is dropped.

Prefix-match `invalid_config:` and split the rest on `", "`.

### Errors

The checks run in this order:

| Status | `error`                                          | When                                                                                                    |
| ------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| 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 `config:read` (`GET`) or `config:write` (`PUT`).                                          |
| 413    | `too_large`                                      | The body is over 65536 bytes.                                                                           |
| 400    | `invalid_if_match`                               | A malformed `If-Match` (see above).                                                                     |
| 400    | `invalid_body`                                   | Not one JSON object: malformed, empty, trailing data, a non-object, or a number too large for a double. |
| 400    | `invalid_config: <paths>`                        | One or more offending members.                                                                          |
| 412    | `precondition_failed`                            | `If-Match` names a revision that is not current.                                                        |
| 500    | `internal error`                                 | A failure on our side. Retry; a failed read never falls back to defaults.                               |

The device-facing `GET /v1/config` (also `config:read`) is unchanged by these endpoints. For what each setting does on the device, see [Configuration](https://docs.getbeekon.com/start/configuration/).

## The document

`GET` returns every section **fully filled in**, with the default for anything never set. This is a project nobody has changed:

```json
{
  "diagnostics": {},
  "features": {},
  "filters": {
    "accuracy_enabled": true,
    "max_accuracy_meters": 200,
    "max_speed_mps": 350,
    "mock_enabled": true,
    "teleport_enabled": true
  },
  "privacy": {},
  "revision": 1,
  "sync": {
    "batch_size": 100,
    "charging_only": false,
    "interval_seconds": 300,
    "sync_threshold": 0,
    "unmetered_only": false
  },
  "tracking": {
    "accuracy_mode": "balanced",
    "detect_activity": false,
    "heartbeat_interval_seconds": 0,
    "max_queue_size": 100000,
    "min_distance_between_locations_meters": 100,
    "min_time_between_locations_seconds": 30,
    "stationary_radius_meters": 5,
    "when_stationary": "pause"
  },
  "trips": {
    "max_accuracy_meters": 100,
    "max_gap_seconds": 600,
    "min_distance_meters": 250,
    "min_duration_seconds": 120,
    "stop_duration_seconds": 300,
    "stop_radius_meters": 100
  }
}
```

(Pretty-printed here; the API sends compact JSON.) `revision` is set by the server and is response-only. The response carries the same revision as an `ETag` header, `W/"1"`.

Three knobs are the exception to “fully filled in”. `trips.silence_timeout_seconds` appears once you set it to any value; `trips.finality_timeout_seconds` and the `presence` section appear only when they differ from their defaults. See [`trips`](#trips) and [`presence`](#presence).

### `tracking`

| Knob                                    | Values                      | Default    | Meaning                                                                                                      |
| --------------------------------------- | --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| `min_time_between_locations_seconds`    | integer, 1–86400            | 30         | Minimum interval between recorded fixes.                                                                     |
| `min_distance_between_locations_meters` | integer, 0–10000            | 100        | Minimum movement between recorded fixes.                                                                     |
| `accuracy_mode`                         | `high`, `balanced` or `low` | `balanced` | Location accuracy versus battery.                                                                            |
| `when_stationary`                       | `pause`, `reduce` or `keep` | `pause`    | What the device does when it stops moving: pause tracking, pause with periodic check-ins, or keep tracking.  |
| `stationary_radius_meters`              | integer, 5–10000            | 5          | Radius for deciding the device is stationary.                                                                |
| `detect_activity`                       | boolean                     | `false`    | OS activity recognition. Needed for a location’s [`mode`](https://docs.getbeekon.com/api/location-mode/) to be anything but `unknown`. |
| `heartbeat_interval_seconds`            | integer, 0, or 60–86400     | 0 (off)    | Proof-of-life fix cadence while stationary.                                                                  |
| `max_queue_size`                        | integer, 1000–500000        | 100000     | Most locations queued on the device; the oldest are dropped first.                                           |

### `sync`

| Knob               | Values            | Default | Meaning                                                 |
| ------------------ | ----------------- | ------- | ------------------------------------------------------- |
| `interval_seconds` | integer, 30–86400 | 300     | Upload cadence. OS scheduler floors may make it longer. |
| `batch_size`       | integer, 1–1000   | 100     | Locations per upload.                                   |
| `sync_threshold`   | integer, 0–10000  | 0 (off) | Upload early once this many locations are queued.       |
| `unmetered_only`   | boolean           | `false` | Upload only on unmetered networks.                      |
| `charging_only`    | boolean           | `false` | Upload only while charging.                             |

`interval_seconds` is the SDK’s `intervalSeconds`, with the same platform floors: see [Upload interval](https://docs.getbeekon.com/guide/sync/#upload-interval). To get locations sooner, set `sync_threshold`. A new interval takes effect on the device as soon as it fetches the new config.

### `privacy`, `diagnostics`, `features` and `poll_interval_seconds`

| Knob                                  | Values                                                           | Default                            | Meaning                                                                                                             |
| ------------------------------------- | ---------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `privacy.precision_truncate_decimals` | integer, 1–6                                                     | absent (off)                       | Truncate recorded coordinates to this many decimal places on the device. Irreversible.                              |
| `diagnostics.log_level`               | `off`, `error`, `warn`, `info` or `debug`                        | absent (the SDK’s own default)     | The SDK’s diagnostic log level.                                                                                     |
| `features`                            | object: up to 64 keys matching `[a-z0-9_]{1,64}`, boolean values | `{}`                               | Feature flags for your app and the SDK. Unknown flags are ignored by devices. `presence_probe` is reserved (below). |
| `poll_interval_seconds`               | integer, 60–86400                                                | absent (the SDK polls every 300 s) | How often an idle device re-checks its config.                                                                      |

A knob that is absent from `GET` (such as `privacy.precision_truncate_decimals` above) is unset, and the device uses its own default.

#### The reserved `presence_probe` flag

`features.presence_probe` belongs to the server. It is `true` in the config devices receive while the optional [push probe](https://docs.getbeekon.com/api/events/#the-push-probe) is on for your project, and absent otherwise. The probe is switched off: it needs its region to enable it and SDK 0.6.0 or later on the device, so for now the flag is always absent. It is never stored in your document, so `GET` does not show it, and a `PUT` that carries it, with any value, is refused with `400 invalid_config: features.presence_probe`.

### `trips`

| Knob                       | Values                  | Default                         | Meaning                                                                                                                                                                                                                  |
| -------------------------- | ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `stop_radius_meters`       | integer, 25–1000        | 100                             | How far a device may wander and still count as stopped.                                                                                                                                                                  |
| `stop_duration_seconds`    | integer, 60–7200        | 300                             | How long a stop must last to end a trip.                                                                                                                                                                                 |
| `min_distance_meters`      | integer, 50–100000      | 250                             | The shortest trip, by distance.                                                                                                                                                                                          |
| `min_duration_seconds`     | integer, 0–86400        | 120                             | The shortest trip, by time. 0 turns the check off.                                                                                                                                                                       |
| `max_gap_seconds`          | integer, 60–86400       | 600                             | The longest silence a trip bridges before it is ended with `end_reason: gap`.                                                                                                                                            |
| `max_accuracy_meters`      | integer, 10–10000       | 100                             | Locations less accurate than this are left out of trips.                                                                                                                                                                 |
| `silence_timeout_seconds`  | integer, 0, or 60–86400 | the effective `max_gap_seconds` | No contact from the device for this long marks its open trip `stalled` and sends [`trip.stalled`](https://docs.getbeekon.com/api/events/#trip-events). 0 turns the silence stall off; a trip still stalls when its device is declared unreachable. |
| `finality_timeout_seconds` | integer, 3600–604800    | 86400                           | No contact from the device for this long closes its open or stalled trip with `end_reason: silence`.                                                                                                                     |

The first six knobs cut trips. A change to them applies to trips that start after it. Each trip records the revision it was cut with in `settings_revision`. Existing trips are not re-cut automatically; a [rebuild](https://docs.getbeekon.com/api/trips/#rebuilds) can re-cut them.

The two timeouts close trips rather than cut them, and are read live: a change applies from the device’s next upload or the server’s next check, and never re-stalls or reopens a trip. See [the trip lifecycle](https://docs.getbeekon.com/api/trips/#the-trip-lifecycle). `GET` shows `silence_timeout_seconds` once you set it to any value (setting it pins it, so a later `max_gap_seconds` change no longer moves it), and `finality_timeout_seconds` only when it differs from 86400. Leave `silence_timeout_seconds` out, or send `null`, to follow `max_gap_seconds` again.

### `presence`

When the server declares a resting device unreachable. See [Device presence events](https://docs.getbeekon.com/api/events/#device-presence-events).

| Knob                 | Values               | Default          | Meaning                                                                                                               |
| -------------------- | -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| `rest_limit_seconds` | integer, 3600–604800 | 43200 (12 hours) | How long a resting device may send nothing before it is unreachable (`device.unreachable` with `reason: rest_limit`). |

For example, an 8-hour rest limit, in a document that sets only this section:

```json
{"presence": {"rest_limit_seconds": 28800}}
```

`GET` shows the `presence` section only when `rest_limit_seconds` differs from the default. A change applies from each device’s next upload or the server’s next check; a deadline already set moves at the device’s next upload.

### `filters`

The server’s admission checks on uploaded locations. A location that fails one is stored but [gated](https://docs.getbeekon.com/api/locations/#admitted-and-gated-locations) with that reason.

| Knob                  | Values           | Default | Meaning                                                                                         |
| --------------------- | ---------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `accuracy_enabled`    | boolean          | `true`  | Gate locations less accurate than `max_accuracy_meters` (`low_accuracy`).                       |
| `max_accuracy_meters` | number, 25–10000 | 200     | The accuracy limit.                                                                             |
| `mock_enabled`        | boolean          | `true`  | Gate locations the OS flagged as mock locations (`mock`).                                       |
| `teleport_enabled`    | boolean          | `true`  | Gate locations that imply an impossible speed from the previous location (`implausible_speed`). |
| `max_speed_mps`       | number, 30–1000  | 350     | The speed limit, in metres per second.                                                          |

Filter changes apply to locations uploaded after the change; stored locations keep their verdict.
