Skip to content

Ingest

POST /v1/ingest stores locations that your backend sends, instead of a phone running the SDK. Use it to bring locations from another system, or to test an integration end to end before you have an app: locations you upload are read back on GET /v1/locations, are cut into trips and are evaluated against your geofences, producing events and webhook deliveries, like locations from the SDK.

The body is the SDK’s own upload format, the same envelope a self-managed backend receives. The SDK posts to this same endpoint in cloud mode. This page covers a server key’s upload.

Scope: locations:write

Terminal window
cat > batch.json <<'EOF'
{
"schema_version": 1,
"batch_id": "0199b2c4-0000-7000-8000-000000000001",
"session_id": "server-import-2026-10-07",
"sent_at": "2026-10-07T09:05:00.000Z",
"device": {"install_id": "vehicle-42", "platform": "android"},
"segments": [
{
"user_id": "driver-7",
"locations": [
{"id": "0199b2c4-0000-7000-8000-000000000101",
"timestamp": "2026-10-07T09:00:00.000Z",
"trigger": "interval", "motion": "moving", "is_mock": false,
"latitude": 12.9716, "longitude": 77.5946, "accuracy": 8},
{"id": "0199b2c4-0000-7000-8000-000000000102",
"timestamp": "2026-10-07T09:00:30.000Z",
"trigger": "interval", "motion": "moving", "is_mock": false,
"latitude": 12.9731, "longitude": 77.5969, "accuracy": 8}
]
}
]
}
EOF
curl -s -o /dev/null -w '%{http_code}\n' \
-X POST https://api.in1.getbeekon.com/v1/ingest \
-H "Authorization: Bearer $BEEKON_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @batch.json

To send it compressed, gzip the file and add Content-Encoding: gzip:

Terminal window
gzip -c batch.json > batch.json.gz
curl -s -o /dev/null -w '%{http_code}\n' \
-X POST https://api.in1.getbeekon.com/v1/ingest \
-H "Authorization: Bearer $BEEKON_TOKEN" \
-H "Content-Type: application/json" \
-H "Content-Encoding: gzip" \
--data-binary @batch.json.gz
  • Plain JSON or gzip. The server decompresses the body only when the request says Content-Encoding: gzip. Without that header the body is read as plain JSON. A body labelled gzip that is not gzip is 400 malformed gzip request body. (The SDK always gzips; a server caller may do either.)
  • At most 2 MiB, compressed and decompressed, and at most 1000 locations across all segments. Over either limit is 413. Split the batch and send the parts.
  • Send timestamps as YYYY-MM-DDTHH:MM:SS.mmmZ, as the SDK does. Any RFC 3339 timestamp is accepted, with any offset and any fractional precision, and is stored in UTC.

The members below are the ones the server reads. The full field reference, including every optional location field (speed, bearing, altitude, activity, battery_percent and so on), is The upload payload.

MemberRequiredMeaning
schema_versionyes1. Missing is 400. Another number is 503 unsupported schema_version.
device.install_idyesThe device the locations belong to: any opaque text up to 128 bytes, not blank, with no NUL character. Each install_id you upload locations for becomes a device in GET /v1/devices.
device.platform, device.sdk_version, device.modelnoStored on the device and shown on GET /v1/devices/{install_id}.
session_idnoUp to 128 bytes, with no NUL character. One tracking run: a change of session_id ends a trip. Keep it constant for one continuous journey.
sent_atnoWhen you assembled the batch. More than 24 hours ahead of the server’s clock is 400.
batch_idnoTracing only. The server never deduplicates on it.
extrasnoYour own string → string map, copied onto every location of the batch. At most 4 KiB encoded (over it is 400 invalid batch), and its encoded size times the batch’s number of locations at most 256 KiB (over it is 413 batch exceeds the extras size bound: send fewer locations per batch, or smaller extras).
segments[]noOne entry per user id, in time order. Each is {user_id?, locations[], geofence_events[]?}. A batch with no segments stores no locations.
segments[].user_idnoThe user the locations belong to: up to 256 bytes of UTF-8, no control characters. Omit it for anonymous locations.
segments[].locations[]noThe locations. Each needs id, timestamp, latitude and longitude, and should carry trigger, motion and is_mock as the SDK does.
segments[].locations[].idyesA UUID you generate, one per location, of any version. The deduplication key: a location whose id is already stored is skipped, so re-sending a batch is safe.
segments[].locations[].timestampyesWhen the location was recorded. RFC 3339 (see Encoding).
segments[].locations[].latitude, longitudeyesWGS 84 degrees. Latitude −90…90, longitude −180…180.
segments[].locations[].accuracynoThe accuracy radius in metres, 0 or more.
segments[].geofence_events[]noGeofence crossings the device recorded, each {id, geofence_id, type, timestamp} as in the upload payload. Stored for provenance only, deduplicated on id: they are never readable through the API and never become events or webhooks, because geofence.* events come only from the server’s own evaluation of the stored locations. They don’t count towards the 1000-location cap.
segments[].geofence_events[].idyesA UUID, of any version. Not a UUID is 400 invalid batch.
segments[].geofence_events[].timestampyesWhen the crossing occurred. RFC 3339; missing is 400 invalid batch. An event outside the accepted window is dropped, and the batch still answers 200.
segments[].geofence_events[].geofence_id, typenoYour geofence id and enter or exit. An event with another type, or a geofence_id over 256 bytes or containing a NUL character, is skipped, and the batch still answers 200.

Members the server does not read are ignored, not refused. A reported_state member is dropped when a server key uploads: device state comes only from the SDK.

A server-key upload is not contact for device presence. A device whose locations reach Beekon only through server-key uploads never produces device.unreachable or device.reachable, and its trips never stall or close with silence: they end on what the locations show.

200 with an empty body. The locations are stored. A server key’s upload never gets the response members the SDK receives (pending config revision, nearby geofences, device commands).

What happens to the locations:

  • Each is stored with source: "server" and trust_tier: "unverified" (an SDK upload stores source: "sdk"). Read them back on GET /v1/locations, filtered by install_id or user_id if you like.
  • The server checks every location as it does the SDK’s: a mock, inaccurate or impossible location is stored as gated and is readable only with include_gated=true. See Admitted and gated locations.
  • A location whose id is already stored is skipped, without an error.
  • A location whose timestamp falls outside the window the deployment accepts (far in the past, or ahead of the server’s clock) is set aside: it is not stored as a location, and not readable. The batch still answers 200.
  • On Beekon Cloud, if the project has a monthly active user (MAU) cap, locations from a user not already counted among this month’s MAU are discarded once the cap is reached, and the batch still answers 200.
StatuserrorWhen
400invalid batchNot JSON; a missing schema_version or device.install_id; a NUL character in device.install_id or session_id; a location id that is not a UUID; a location or geofence event without a timestamp, or a location without latitude or longitude (absent or null); a timestamp that is not RFC 3339; a latitude outside −90…90 or a longitude outside −180…180; a negative accuracy; a bound above exceeded (extras over 4 KiB included); or sent_at too far ahead. One bad location refuses the whole batch, and nothing in it is stored.
400malformed gzip request body · unreadable request bodyLabelled Content-Encoding: gzip but not gzip, or a body that could not be read.
401missing bearer token · invalid session tokenNo valid session.
403insufficient scopeThe key lacks locations:write.
413request body exceeds the 2 MiB cap · decompressed request body exceeds the 2 MiB cap · batch exceeds the 1000-row cap · batch exceeds the extras size boundToo large. Split the batch. The extras bound is extras’ encoded size times the batch’s locations, over 256 KiB.
429rate limit exceeded for this credential, retryUploads are limited per key. Wait Retry-After seconds. See Rate limits.
500internal errorA failure on our side. Retry the same batch: the location ids make it safe.
503cell is at capacity, retry · unsupported producer class, retryBrief. Retry after Retry-After.
503unsupported schema_version · project suspendedNot brief: a retry will not fix them. Do not retry blindly. Send schema_version: 1, or wait until the project is reinstated.

Every 503 carries Retry-After. Retrying is always safe: send the same locations with the same ids.