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.
GET /v1/config/document
Section titled “GET /v1/config/document”Scope: config:read
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.
PUT /v1/config/document
Section titled “PUT /v1/config/document”Scope: config:write · Replaces the document.
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
Section titled “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).
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
Section titled “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
Section titled “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:
{ "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
Section titled “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.
The document
Section titled “The document”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.
tracking
Section titled “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 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. |
| 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. 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”| 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
Section titled “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 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.
| 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. 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 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.
presence
Section titled “presence”When the server declares a resting device unreachable. See 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:
{"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
Section titled “filters”The server’s admission checks on uploaded locations. A location that fails one is stored but gated 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.