Skip to content

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) and filters (how the server judges uploaded locations before admitting them). A third, presence, sets when the server declares a device unreachable.

Scope: config:read

Terminal window
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. This endpoint does not answer If-None-Match: it always returns 200 and the full document.

Scope: config:write · Replaces the document.

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

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

In your bodytracking, sync, privacy, features, diagnostics, poll_interval_secondstrips, presence, filters
presentreplaced; knobs you leave out take their defaultsreplaced; knobs you leave out take their defaults
nullreset to defaultsreset to defaults
left outreset to defaultskept 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).

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

Send If-Match to make the write conditional:

If-MatchEffect
absentThe write is unconditional.
W/"<revision>", exactly as the ETag you readThe 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 else400 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.

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:

{
"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 ", ".

The checks run in this order:

StatuserrorWhen
401missing bearer token · invalid session tokenNo valid session.
403server credentials requiredThe token was minted from an SDK key.
403insufficient scopeThe key lacks config:read (GET) or config:write (PUT).
413too_largeThe body is over 65536 bytes.
400invalid_if_matchA malformed If-Match (see above).
400invalid_bodyNot one JSON object: malformed, empty, trailing data, a non-object, or a number too large for a double.
400invalid_config: <paths>One or more offending members.
412precondition_failedIf-Match names a revision that is not current.
500internal errorA 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.

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

{
"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 and presence.

KnobValuesDefaultMeaning
min_time_between_locations_secondsinteger, 1–8640030Minimum interval between recorded fixes.
min_distance_between_locations_metersinteger, 0–10000100Minimum movement between recorded fixes.
accuracy_modehigh, balanced or lowbalancedLocation accuracy versus battery.
when_stationarypause, reduce or keeppauseWhat the device does when it stops moving: pause tracking, pause with periodic check-ins, or keep tracking.
stationary_radius_metersinteger, 5–100005Radius for deciding the device is stationary.
detect_activitybooleanfalseOS activity recognition. Needed for a location’s mode to be anything but unknown.
heartbeat_interval_secondsinteger, 0, or 60–864000 (off)Proof-of-life fix cadence while stationary.
max_queue_sizeinteger, 1000–500000100000Most locations queued on the device; the oldest are dropped first.
KnobValuesDefaultMeaning
interval_secondsinteger, 30–86400300Upload cadence. OS scheduler floors may make it longer.
batch_sizeinteger, 1–1000100Locations per upload.
sync_thresholdinteger, 0–100000 (off)Upload early once this many locations are queued.
unmetered_onlybooleanfalseUpload only on unmetered networks.
charging_onlybooleanfalseUpload only while charging.

interval_seconds is the SDK’s intervalSeconds, with the same platform floors: see 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

Section titled “privacy, diagnostics, features and poll_interval_seconds”
KnobValuesDefaultMeaning
privacy.precision_truncate_decimalsinteger, 1–6absent (off)Truncate recorded coordinates to this many decimal places on the device. Irreversible.
diagnostics.log_leveloff, error, warn, info or debugabsent (the SDK’s own default)The SDK’s diagnostic log level.
featuresobject: 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_secondsinteger, 60–86400absent (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.

features.presence_probe belongs to the server. It is true in the config devices receive while the optional 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.

KnobValuesDefaultMeaning
stop_radius_metersinteger, 25–1000100How far a device may wander and still count as stopped.
stop_duration_secondsinteger, 60–7200300How long a stop must last to end a trip.
min_distance_metersinteger, 50–100000250The shortest trip, by distance.
min_duration_secondsinteger, 0–86400120The shortest trip, by time. 0 turns the check off.
max_gap_secondsinteger, 60–86400600The longest silence a trip bridges before it is ended with end_reason: gap.
max_accuracy_metersinteger, 10–10000100Locations less accurate than this are left out of trips.
silence_timeout_secondsinteger, 0, or 60–86400the effective max_gap_secondsNo contact from the device for this long marks its open trip stalled and sends trip.stalled. 0 turns the silence stall off; a trip still stalls when its device is declared unreachable.
finality_timeout_secondsinteger, 3600–60480086400No 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 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. 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.

When the server declares a resting device unreachable. See Device presence events.

KnobValuesDefaultMeaning
rest_limit_secondsinteger, 3600–60480043200 (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:

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

The server’s admission checks on uploaded locations. A location that fails one is stored but gated with that reason.

KnobValuesDefaultMeaning
accuracy_enabledbooleantrueGate locations less accurate than max_accuracy_meters (low_accuracy).
max_accuracy_metersnumber, 25–10000200The accuracy limit.
mock_enabledbooleantrueGate locations the OS flagged as mock locations (mock).
teleport_enabledbooleantrueGate locations that imply an impossible speed from the previous location (implausible_speed).
max_speed_mpsnumber, 30–1000350The speed limit, in metres per second.

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