Skip to content

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.

Terminal window
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"}
  • 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.
  • 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 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.

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.

RuleWhat it means
One JSON objectThe 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 membersEvery 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 keysGeofence 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 typeA 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 presentA 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 membersAn 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 rulesA 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.

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

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

    Membernull means
    next_cursor on every list except eventsthe walk is complete
    retention_floor on 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.

  • DELETE answers 204 No Content with no body.

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.

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

RequestSafe to retry?
Any GETYes. Retry with the same cursor.
PUT /v1/geofences/{fence_id}, PUT /v1/config/documentYes. 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/webhooksNo. 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}/commandsNo. 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-secretNo. Each call mints a new secret, and only the latest two are kept.
POST …/pingYes, 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.