# Ingest

> POST /v1/ingest — upload locations from your own server in the SDK's upload format, with a server key (locations:write). Plain or gzipped JSON, an empty 200, locations stored as source "server".

Source: https://docs.getbeekon.com/api/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`](https://docs.getbeekon.com/api/locations/), are cut into [trips](https://docs.getbeekon.com/api/trips/) and are evaluated against your [geofences](https://docs.getbeekon.com/api/geofences/), producing [events](https://docs.getbeekon.com/api/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](https://docs.getbeekon.com/guide/payload/#the-upload-payload). The SDK posts to this same endpoint in cloud mode. This page covers a server key’s upload.

## POST `/v1/ingest`

**Scope:** `locations:write`

```sh
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`:

```sh
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
```

### 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 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.

### Body

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](https://docs.getbeekon.com/guide/payload/#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`](https://docs.getbeekon.com/api/devices/).                                                                                                                                                                                                                             |
| `device.platform`, `device.sdk_version`, `device.model` | no       | Stored on the device and shown on [`GET /v1/devices/{install_id}`](https://docs.getbeekon.com/api/devices/).                                                                                                                                                                                                                                                                                                                                                    |
| `session_id`                                            | no       | Up to 128 bytes, with no NUL character. One tracking run: a change of `session_id` ends a [trip](https://docs.getbeekon.com/api/trips/#when-a-trip-ends). 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](#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](https://docs.getbeekon.com/guide/payload/#segmentsgeofence_events). 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](https://docs.getbeekon.com/api/events/#device-presence-events). A device whose locations reach Beekon only through server-key uploads never produces `device.unreachable` or `device.reachable`, and its [trips](https://docs.getbeekon.com/api/trips/#the-trip-lifecycle) never stall or close with `silence`: they end on what the locations show.

### 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"` and `trust_tier: "unverified"` (an SDK upload stores `source: "sdk"`). Read them back on [`GET /v1/locations`](https://docs.getbeekon.com/api/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](https://docs.getbeekon.com/api/locations/#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](https://docs.getbeekon.com/cloud/usage/#usage-and-the-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`.

A device that only ever arrives through ingest

Its `reported_at`, `applied_config_revision`, `apply_status` and `health` on [`GET /v1/devices/{install_id}`](https://docs.getbeekon.com/api/devices/) stay `null`. Those come only from an SDK’s own report. `last_seen`, `platform`, `sdk_version` and `model` are filled from what you upload.

### 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](https://docs.getbeekon.com/api/rate-limits/#other-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 `id`s.
