# Conventions

> The rules every /v1 endpoint follows — JSON bodies, canonical encoding, timestamps, ids, nullable members, strict request bodies, unknown parameters, retries and idempotency.

Source: https://docs.getbeekon.com/api/conventions/

These rules hold on every `/v1` server endpoint; each endpoint page lists only what it adds. One request shows most of them: HTTPS to your region’s host, a bearer token, and compact JSON with sorted keys and millisecond UTC timestamps.

```sh
curl -s https://api.in1.getbeekon.com/v1/project -H "Authorization: Bearer $BEEKON_TOKEN"
# {"cell":"in1","created_at":"2026-10-07T06:30:00.000Z","id":"0199b2c4-…","name":"Fleet tracking","status":"active"}
```

## Requests

* **HTTPS only**, against your region’s host, `https://api.<cell>.getbeekon.com`.
* **Authentication**: `Authorization: Bearer <session token>` on every call except `POST /v1/token`. See [Authentication](https://docs.getbeekon.com/api/authentication/).
* **Bodies are JSON.** Send `Content-Type: application/json`. Endpoints that take no body (`GET`, `DELETE`, `ping`) expect none; `ping` refuses a non-empty body.
* **Query parameters.** A parameter an endpoint does not define is ignored, and so are `project`, `project_id`, `id` and `org`, even when repeated. A parameter an endpoint **does** define must be sent at most once and must not be empty (except `limit=` and `cursor=`, which count as absent); otherwise it is a `400` naming that parameter. `GET /v1/events` is the exception: it reads the first of a repeated parameter.
* **Path ids.** Ids in a path are lowercase UUIDs (`/v1/geofences/{fence_id}`, `/v1/trips/{trip_id}`, `/v1/webhooks/{webhook_id}`), except a device’s `install_id` and a user’s `user_id`, which are whatever strings your app set. URL-encode them as one path segment. A malformed UUID id answers `404 not found`, exactly like an unknown one; a malformed `user_id` is `400 invalid_user_id`.

## The project comes from the token

The session token is bound to exactly one project. Every call reads or writes that project only, and nothing in a request can name or widen it: no path segment, query parameter or body member. `/v1/projects/{id}` does not exist. Another project’s id answers `404 not found`, the same as an id that was never created.

## Request bodies are strict

Every endpoint that takes a JSON body decodes it strictly. It never ignores what it does not understand. The one exception is [`POST /v1/ingest`](https://docs.getbeekon.com/api/ingest/#body): the upload envelope ignores members it does not read.

| Rule                         | What it means                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **One JSON object**          | The body must be exactly one JSON object. Malformed JSON, an empty body, `null`, an array, any other non-object, or anything after the object is `400 invalid_body`.                                                                                                                                                                                                                          |
| **Only defined members**     | Every member must be one the endpoint defines, matched case-sensitively. An unknown member, including `project_id`, or a different casing (`Name` for `name`) is refused. For most endpoints that is `400 invalid_body`. The remote-config document instead answers one `400 invalid_config: <paths>` that names every offending member. See [Remote config](https://docs.getbeekon.com/api/remote-config/#validation). |
| **No repeated keys**         | Geofence and webhook bodies refuse a key that appears twice in any object (`400 invalid_body`) rather than guessing which one you meant.                                                                                                                                                                                                                                                      |
| **The right JSON type**      | A member of the wrong JSON type (a string where a boolean belongs) is refused: on geofence and webhook bodies with `400 invalid_body`; on a device command and the config document with the member’s own token (`invalid_type`, `invalid_ttl_seconds`, `invalid_config: <path>`, …).                                                                                                          |
| **Required members present** | A required member must be present and not `null`. The token for a missing one is the endpoint’s own: a geofence body answers `400 invalid_body`, and a webhook create without `endpoint_url` answers `400 invalid_endpoint_url`. Each endpoint’s page lists its tokens.                                                                                                                       |
| **`null` optional members**  | An optional member that is `null` counts as absent, except members documented as nullable (such as a webhook’s `event_types`, where `null` means “every type”).                                                                                                                                                                                                                               |
| **Endpoint rules**           | A value of the right type that breaks a rule of the endpoint (an empty name, an unknown enum value, an out-of-range number) is the endpoint’s own `400 invalid_<thing>` token, checked after the body’s shape.                                                                                                                                                                                |

Body size caps: 1 MiB for a geofence, 16 KiB for a webhook request or a device command, 64 KiB for the remote-config document, and 2 MiB for an upload. An oversized geofence, webhook or command body is `400 invalid_body`; an oversized config document is `413 too_large`, and an oversized upload is the `413` on [Ingest](https://docs.getbeekon.com/api/ingest/#errors). The server stops reading at the cap.

## Responses

* **`Content-Type: application/json`**, and the body is compact JSON: keys sorted, no insignificant whitespace, no HTML escaping. Do not depend on the key order or byte layout; parse the JSON.

* **A single resource is wrapped** in a member named for it: `{"device":{…}}`, `{"geofence":{…}}`, `{"trip":{…}}`, `{"webhook":{…}}`. `GET /v1/project` and the remote-config document are the exceptions: they return the object itself.

* **A list is a page**: `{"<items>":[…],"next_cursor":…}`. See [Pagination](https://docs.getbeekon.com/api/pagination/).

* **Optional members are omitted**, never `null`. The exceptions are the **documented nullables**, which are always present and may be `null`:

  | Member                                                                                                                         | `null` means                                                        |
  | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
  | `next_cursor` on every list except events                                                                                      | the walk is complete                                                |
  | `retention_floor` on a locations page                                                                                          | nothing has been deleted under retention yet                        |
  | a device’s `last_seen`, `reported_at`, `applied_config_revision`, `apply_status`, `health`, `platform`, `sdk_version`, `model` | the device has not reported that yet                                |
  | a device’s `user_id`                                                                                                           | the device has no current user                                      |
  | a webhook’s `event_types`                                                                                                      | the endpoint receives every event type, including types added later |
  | a webhook’s `auto_disabled_at`                                                                                                 | not auto-disabled (or not yet active in the region)                 |
  | a ping’s `status_code`                                                                                                         | the endpoint gave no HTTP response                                  |

* **Ignore what you don’t know.** New members and new enum values can appear in any response within `/v1`. Your client must skip them rather than fail.

* **`DELETE` answers `204 No Content`** with no body.

## Timestamps

Every timestamp the API returns is RFC 3339 in UTC with exactly three fractional digits, **truncated** (never rounded): `2026-10-07T06:30:00.000Z`.

Timestamps you **send** in a query string (`from`, `to`) may use any RFC 3339 offset and any fractional precision: `2026-10-07T15:00:00+05:30` and `2026-10-07T09:30:00Z` are the same instant. A bare date such as `2026-10-07` is refused, never read as midnight. Remember to URL-encode a `+` offset (`curl --data-urlencode` does).

Timestamps inside a command’s `params` must be exactly `YYYY-MM-DDTHH:MM:SS.mmmZ`.

## Ids

Ids are lowercase, hyphenated UUID strings. A device’s `install_id` is the exception: it is the string the SDK generated, so treat it as opaque text and never type it as a UUID. A location’s `id` is minted by the device and may be any UUID version.

## Retries and idempotency

There is no `Idempotency-Key` header. What is safe to retry depends on the method:

| Request                                                   | Safe to retry?                                                                                                                                                   |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Any `GET`                                                 | Yes. Retry with the same cursor.                                                                                                                                 |
| `PUT /v1/geofences/{fence_id}`, `PUT /v1/config/document` | Yes. A replace with the same body leaves the same result. A config document `PUT` that changes nothing does not create a new revision.                           |
| `PATCH /v1/webhooks/{webhook_id}`                         | Yes. Setting the same values again changes nothing except `updated_at` (and, like every webhook write, it lifts an [auto-disable](https://docs.getbeekon.com/api/webhooks/#auto-disable)). |
| `DELETE …`                                                | Yes, but a retry after a delete that succeeded answers `404 not found`. Treat that `404` as success.                                                             |
| `POST /v1/geofences`, `POST /v1/webhooks`                 | **No.** Each call creates a new resource. After a timeout, list the resources before you retry, to see whether the first call landed.                            |
| `POST /v1/devices/{install_id}/commands`                  | **No.** Each call issues a new command. A duplicate `flush` or `upload_logs` is harmless to the device, but counts against the 20 active commands per device.    |
| `POST …/rotate-secret`                                    | **No.** Each call mints a new secret, and only the latest two are kept.                                                                                          |
| `POST …/ping`                                             | Yes, within its [rate limit](https://docs.getbeekon.com/api/rate-limits/).                                                                                                                 |

Retry on `429`, `503` and other `5xx` answers with backoff, except ingest’s `503 unsupported schema_version` and `503 project suspended`, which a retry does not fix. Never retry a `4xx` other than `429` unchanged: it will fail the same way. See [Errors](https://docs.getbeekon.com/api/errors/).

Conditional writes

The remote-config document supports optimistic concurrency with an `ETag` and `If-Match`, so two writers cannot silently overwrite each other. See [Remote config](https://docs.getbeekon.com/api/remote-config/#concurrent-writers-etag-and-if-match).
