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.
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
Section titled “Requests”- HTTPS only, against your region’s host,
https://api.<cell>.getbeekon.com. - Authentication:
Authorization: Bearer <session token>on every call exceptPOST /v1/token. See Authentication. - Bodies are JSON. Send
Content-Type: application/json. Endpoints that take no body (GET,DELETE,ping) expect none;pingrefuses a non-empty body. - Query parameters. A parameter an endpoint does not define is ignored, and so are
project,project_id,idandorg, even when repeated. A parameter an endpoint does define must be sent at most once and must not be empty (exceptlimit=andcursor=, which count as absent); otherwise it is a400naming that parameter.GET /v1/eventsis 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’sinstall_idand a user’suser_id, which are whatever strings your app set. URL-encode them as one path segment. A malformed UUID id answers404 not found, exactly like an unknown one; a malformeduser_idis400 invalid_user_id.
The project comes from the token
Section titled “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
Section titled “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: 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. |
| 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. The server stops reading at the cap.
Responses
Section titled “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/projectand the remote-config document are the exceptions: they return the object itself. -
A list is a page:
{"<items>":[…],"next_cursor":…}. See Pagination. -
Optional members are omitted, never
null. The exceptions are the documented nullables, which are always present and may benull:Member nullmeansnext_cursoron every list except eventsthe walk is complete retention_flooron a locations pagenothing has been deleted under retention yet a device’s last_seen,reported_at,applied_config_revision,apply_status,health,platform,sdk_version,modelthe device has not reported that yet a device’s user_idthe device has no current user a webhook’s event_typesthe endpoint receives every event type, including types added later a webhook’s auto_disabled_atnot auto-disabled (or not yet active in the region) a ping’s status_codethe 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. -
DELETEanswers204 No Contentwith no body.
Timestamps
Section titled “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 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
Section titled “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). |
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. |
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.