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.
POST /v1/ingest
Section titled “POST /v1/ingest”Scope: locations:write
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.jsonTo send it compressed, gzip the file and add Content-Encoding: gzip:
gzip -c batch.json > batch.json.gzcurl -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.gzEncoding
Section titled “Encoding”- 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 is400 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.
| Member | Required | Meaning |
|---|---|---|
schema_version | yes | 1. Missing is 400. Another number is 503 unsupported schema_version. |
device.install_id | yes | The 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.model | no | Stored on the device and shown on GET /v1/devices/{install_id}. |
session_id | no | Up 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_at | no | When you assembled the batch. More than 24 hours ahead of the server’s clock is 400. |
batch_id | no | Tracing only. The server never deduplicates on it. |
extras | no | Your 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[] | no | One entry per user id, in time order. Each is {user_id?, locations[], geofence_events[]?}. A batch with no segments stores no locations. |
segments[].user_id | no | The user the locations belong to: up to 256 bytes of UTF-8, no control characters. Omit it for anonymous locations. |
segments[].locations[] | no | The locations. Each needs id, timestamp, latitude and longitude, and should carry trigger, motion and is_mock as the SDK does. |
segments[].locations[].id | yes | A 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[].timestamp | yes | When the location was recorded. RFC 3339 (see Encoding). |
segments[].locations[].latitude, longitude | yes | WGS 84 degrees. Latitude −90…90, longitude −180…180. |
segments[].locations[].accuracy | no | The accuracy radius in metres, 0 or more. |
segments[].geofence_events[] | no | Geofence 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[].id | yes | A UUID, of any version. Not a UUID is 400 invalid batch. |
segments[].geofence_events[].timestamp | yes | When 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, type | no | Your 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.
Response
Section titled “Response”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"andtrust_tier: "unverified"(an SDK upload storessource: "sdk"). Read them back onGET /v1/locations, filtered byinstall_idoruser_idif 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
idis 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.
Errors
Section titled “Errors”| Status | error | When |
|---|---|---|
| 400 | invalid batch | Not 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. |
| 400 | malformed gzip request body · unreadable request body | Labelled Content-Encoding: gzip but not gzip, or a body that could not be read. |
| 401 | missing bearer token · invalid session token | No valid session. |
| 403 | insufficient scope | The key lacks locations:write. |
| 413 | request 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 bound | Too large. Split the batch. The extras bound is extras’ encoded size times the batch’s locations, over 256 KiB. |
| 429 | rate limit exceeded for this credential, retry | Uploads are limited per key. Wait Retry-After seconds. See Rate limits. |
| 500 | internal error | A failure on our side. Retry the same batch: the location ids make it safe. |
| 503 | cell is at capacity, retry · unsupported producer class, retry | Brief. Retry after Retry-After. |
| 503 | unsupported schema_version · project suspended | Not 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.