openapi: 3.1.0
info:
  title: Beekon Cloud server API
  version: "1"
  summary: The /v1 server-key surface of Beekon Cloud.
  description: |
    The Beekon Cloud server API, for a customer's own backend. Authenticate by exchanging a
    `bkserv_` server key for a short-lived session token at `POST /v1/token`, then send the token
    as a bearer token. Every other operation requires exactly one scope, listed in its `security`
    requirement and in `x-beekon-scope`.

    This document describes every server endpoint documented at https://docs.getbeekon.com/api/,
    with the same parameters and responses. It leaves out the device-only endpoints and the
    webhook delivery request and its headers; the pages describe those.

    Conventions: errors are `{"error":"<text>"}` with `Content-Type: application/json`; optional
    members are omitted, never null, except the documented nullables; query parameters an
    operation does not define are ignored; the project always comes from the session token;
    request bodies are strict (unknown members are refused, never ignored), except
    `POST /v1/ingest`, whose upload envelope ignores members it does not read. Response objects
    grow additively: a later revision may add members to any response object, so ignore
    members you do not know. Removing or retyping a member is a breaking change; adding one
    is not.

    Release: members, values and event types whose description says "Added in the next backend
    release" are not in production yet. A region without that release omits them from
    responses, never sends those values or events, and refuses them in requests. They are
    optional here so that a client generated from this document accepts today's responses.

    Routing: these errors also apply to requests that match no operation here. A path under
    `/v1` that no operation serves answers `404` with `{"error":"not found"}` (the same body as an
    unknown id), and a method a documented path does not serve answers `405` with
    `{"error":"method_not_allowed"}` and an `Allow` header listing the path's methods (sorted,
    `", "`-joined, `HEAD` wherever `GET` is served). Both are decided before authentication.
  contact:
    name: Beekon
    url: https://docs.getbeekon.com/api/
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.{cell}.getbeekon.com
    description: The API host of your project's region. The cell is the second segment of your key (bkserv_<cell>_...).
    variables:
      cell:
        default: in1
        description: Your project's cell, for example in1.
security:
  - session: []
tags:
  - name: Authentication
    description: Exchange a key for a session token.
  - name: Project
    description: The project the key belongs to.
  - name: Devices
    description: The project's devices and the commands sent to them.
  - name: Users
    description: The user ids your app set on its devices, their devices, and their erasure.
  - name: Locations
    description: Stored location points, and uploading points from your server.
  - name: Trips
    description: Trips detected on the server from each device's points.
  - name: Geofences
    description: The project's geofences.
  - name: Remote config
    description: The project's remote configuration document.
  - name: Events
    description: The project's event log.
  - name: Webhooks
    description: Webhook endpoints for the project's events (the API object is `webhook`).
paths:
  /v1/token:
    post:
      tags: [Authentication]
      operationId: createToken
      summary: Exchange a key for a session token
      description: |
        Send the server key (or an SDK key) as `Authorization: Bearer <key>` with no body. The
        response's `access_token` is the session token for every other call. A key presented to
        another region's host is refused like an unknown key.
      security:
        - serverKey: []
      x-beekon-scope: null
      responses:
        "200":
          description: A session token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Token"
              example:
                access_token: eyJhbGciOiJFUzI1NiIs...
                expires_in: 3600
        "400":
          description: "`malformed project key`: the value is not shaped like a Beekon key."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: malformed project key
        "401":
          description: "`missing bearer token`, or `unknown project key` (unknown, revoked, or another region's key). A new or revoked key takes effect at once; still retry `unknown project key` with backoff for up to 60 seconds before alerting."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: unknown project key
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/project:
    get:
      tags: [Project]
      operationId: getProject
      summary: Read the session's project
      description: |
        Returns the project the key belongs to. Takes no parameters; query parameters such as
        `project_id` are ignored. A suspended project answers 200 with `"status":"suspended"`.
      security:
        - session: ["project:read"]
      x-beekon-scope: project:read
      responses:
        "200":
          description: The project.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
              example:
                cell: in1
                created_at: "2026-10-07T06:30:00.000Z"
                id: 0199b2c4-1f3a-7c11-9d2e-5a6b7c8d9e0f
                name: Fleet tracking
                status: active
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: "`not found`: the token's project is not hosted on this region."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not found
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/devices:
    get:
      tags: [Devices]
      operationId: listDevices
      summary: List devices
      description: |
        The project's devices, ordered by `install_id` in byte order, paged with a `dc1_` cursor.
        A device appears once it has uploaded a point or reported its state.

        `user_id` narrows the list to the devices whose current `user_id` member is exactly that
        id, in the same order and shape. An id with no current device is an empty page. The
        filter's cursor binds it: a cursor minted with another `user_id`, or with none, is
        `cursor_query_mismatch`. `GET /v1/users/{user_id}/devices` returns the same bytes. The
        parameters are read in the order `limit`, `user_id`, `cursor`.
      security:
        - session: ["devices:read"]
      x-beekon-scope: devices:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/UserIdFilter"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of devices.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DevicesPage"
              example:
                devices:
                  - applied_config_revision: null
                    apply_status: null
                    health: null
                    install_id: 2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50
                    last_seen: "2026-10-07T06:29:41.120Z"
                    model: null
                    platform: null
                    reported_at: null
                    sdk_version: null
                    user_id: customer-42
                next_cursor: null
        "400":
          $ref: "#/components/responses/BadDevicesQuery"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/devices/{install_id}:
    get:
      tags: [Devices]
      operationId: getDevice
      summary: Read one device
      security:
        - session: ["devices:read"]
      x-beekon-scope: devices:read
      parameters:
        - $ref: "#/components/parameters/InstallIdPath"
      responses:
        "200":
          description: The device.
          content:
            application/json:
              schema:
                type: object
                required: [device]
                properties:
                  device:
                    $ref: "#/components/schemas/Device"
              example:
                device:
                  applied_config_revision: 7
                  apply_status: success
                  health:
                    battery_percent: 81
                    is_charging: false
                    location_enabled: true
                    pending_fixes: 0
                    permission: always
                    sync_errors: 0
                  install_id: 2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50
                  last_seen: "2026-10-07T06:29:41.120Z"
                  model: Pixel 8
                  platform: android
                  reported_at: "2026-10-07T06:25:03.000Z"
                  sdk_version: 0.4.0
                  user_id: customer-42
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/devices/{install_id}/commands:
    post:
      tags: [Devices]
      operationId: createDeviceCommand
      summary: Send a device a command
      description: |
        Queues `flush` or `upload_logs` for one device. The body is validated before the device is
        looked up, so a bad body is a 400 even for an unknown device. Not idempotent: each call
        issues a new command. At most 20 active commands per device.
      security:
        - session: ["devices:write"]
      x-beekon-scope: devices:write
      parameters:
        - $ref: "#/components/parameters/InstallIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommandRequest"
            example:
              type: upload_logs
              params:
                since: "2026-10-07T00:00:00.000Z"
              ttl_seconds: 86400
      responses:
        "201":
          description: The command was issued.
          content:
            application/json:
              schema:
                type: object
                required: [command]
                properties:
                  command:
                    $ref: "#/components/schemas/Command"
              example:
                command:
                  expires_at: "2026-10-08T06:30:00.000Z"
                  id: 0199b2d0-6c1e-7a40-8f00-3c2b1a090807
                  install_id: 2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50
                  params:
                    since: "2026-10-07T00:00:00.000Z"
                  type: upload_logs
        "400":
          description: "In this order: `invalid_body` (not one JSON object, trailing data, an unknown member, or a body over 16 KiB), `invalid_type`, `invalid_params`, `invalid_ttl_seconds`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_params
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`too_many_active_commands`: the device already has 20 unexpired, unfulfilled commands."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: too_many_active_commands
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/users:
    get:
      tags: [Users]
      operationId: listUsers
      summary: List users
      description: |
        The project's users, ordered by `user_id` in byte order, paged with a `us1_` cursor. A
        user is a `user_id` value at least one stored location point in the project carries,
        gated or not; an anonymous point makes no user. There is no create call: your app's
        `setUserId` is the only way a user appears, and the id is returned exactly as the SDK sent
        it. A user whose every stored point has aged out under retention, or been erased, is no
        longer listed. There are no filters.
      security:
        - session: ["users:read"]
      x-beekon-scope: users:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/UsersCursor"
      responses:
        "200":
          description: A page of users.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsersPage"
              example:
                next_cursor: null
                users:
                  - last_seen: "2026-10-15T09:30:00.123Z"
                    user_id: customer-42
        "400":
          $ref: "#/components/responses/BadPaging"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/users/{user_id}:
    get:
      tags: [Users]
      operationId: getUser
      summary: Read one user
      description: |
        The user, or `404` for a well-formed id that is not a user of this project (never seen,
        aged out, erased, or another project's). A malformed id is `400 invalid_user_id`, before
        any read.
      security:
        - session: ["users:read"]
      x-beekon-scope: users:read
      parameters:
        - $ref: "#/components/parameters/UserIdPath"
      responses:
        "200":
          description: The user.
          content:
            application/json:
              schema:
                type: object
                required: [user]
                properties:
                  user:
                    $ref: "#/components/schemas/User"
              example:
                user:
                  last_seen: "2026-10-15T09:30:00.123Z"
                  user_id: customer-42
        "400":
          $ref: "#/components/responses/BadUserId"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
    delete:
      tags: [Users]
      operationId: eraseUser
      summary: Erase a user's data in this project
      description: |
        Erases everything this project holds under the `user_id`: its stored points (gated or
        not), quarantined uploads, events and their pending webhook deliveries, device geofence
        events, trips, queued work that embeds the id, and its (user, device) pairs; a device's
        current `user_id` and the geofence state's last user are set to null. The same id in
        another project or organisation is untouched. Device-keyed state stays: the user's former
        devices are still listed, and their `user_id` follows their next point.

        Erasure runs in bounded calls with two passes around a 185-second settle window. Repeat
        the same `DELETE` until it answers `204`:

        - `202` `{"status":"erasing"}` while work is left or the settle window runs.
          `Retry-After` is 1 while rows remain, the settle window (185) once the first pass has
          verified nothing is left, and the rest of the window, in whole seconds, while it runs.
        - `204` when the second pass, after the window, verifies nothing in this project matches
          the id.
        - `500` when a part of the erasure failed. Retry.

        Every well-formed id converges to `204`, including one with no data and one already
        erased, so the answers do not reveal whether the user existed (the time a pass takes may,
        to a key that can erase the id anyway). A `204` is not a tombstone: points still queued on
        a device, or recorded later, re-create the user. Stop the id at its source first (your
        app calls `setUserId(null)`, or the device is stopped and its queue drains), then erase. A
        new `DELETE` after a `204` starts a new cycle.

        At most one erasure call per project runs at a time (`503` with `Retry-After: 1`
        otherwise), and each key may make 30 calls a minute (`429` with `Retry-After`). A refused
        call erases and records nothing. Every call that did work is recorded in the
        organisation's audit trail with a keyed hash of the id, never the id.
      security:
        - session: ["users:write"]
      x-beekon-scope: users:write
      parameters:
        - $ref: "#/components/parameters/UserIdPath"
      responses:
        "202":
          description: Erasing. Call again after Retry-After seconds.
          headers:
            Retry-After:
              description: Seconds to wait before the next call, 1 to 185.
              schema:
                type: integer
                minimum: 1
                maximum: 185
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Erasing"
              example:
                status: erasing
        "204":
          description: Erased. Nothing in this project matches the id. No body.
        "400":
          $ref: "#/components/responses/BadUserId"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/users/{user_id}/devices:
    get:
      tags: [Users]
      operationId: listUserDevices
      summary: List a user's devices
      description: |
        The devices whose current `user_id` is this user, exactly as
        `GET /v1/devices?user_id=<user_id>` returns them, cursors included (a cursor from one
        resumes on the other). A device's current user is the user on its newest admitted point,
        so a device moves between users only when your app calls `setUserId`. A well-formed id
        that is not a user of this project is a `404`; a user with no current device is an empty
        page.
      security:
        - session: ["users:read"]
      x-beekon-scope: users:read
      parameters:
        - $ref: "#/components/parameters/UserIdPath"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of devices.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DevicesPage"
        "400":
          $ref: "#/components/responses/BadDevicesQuery"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/locations:
    get:
      tags: [Locations]
      operationId: listLocations
      summary: Read stored location points for a window
      description: |
        Points in `[from, to)` on the device's recorded time, ordered by `(recorded_at, id)`
        ascending, or descending (newest first) with `order=desc`. Admitted points only by default; `include_gated=true` adds gated points (each
        with `gate`), and `gate_reason` selects only points gated for that reason. When
        `install_id`, `user_id`, `gate_reason` or `mode` is present the window must be at most 24
        hours.
        A defined parameter sent twice is a 400 with that parameter's token; an empty value is a
        400 except for `limit` and `cursor`. Every parameter except `limit` and `cursor` must be
        repeated unchanged on every page of a walk.
      security:
        - session: ["locations:read"]
      x-beekon-scope: locations:read
      parameters:
        - name: from
          in: query
          required: true
          description: Inclusive lower bound on recorded_at. RFC 3339 with any offset; a bare date is refused.
          schema:
            type: string
            format: date-time
          example: "2026-10-06T00:00:00Z"
        - name: to
          in: query
          required: true
          description: Exclusive upper bound on recorded_at. Must be after `from`.
          schema:
            type: string
            format: date-time
          example: "2026-10-07T00:00:00Z"
        - name: install_id
          in: query
          required: false
          description: Only this device. Non-blank, at most 128 bytes, no NUL character. Capped to a 24-hour window.
          schema:
            type: string
            minLength: 1
        - name: user_id
          in: query
          required: false
          description: Only points recorded under this user id. Non-empty, at most 256 bytes, valid UTF-8, no control characters. Capped to a 24-hour window.
          schema:
            type: string
            minLength: 1
        - name: include_gated
          in: query
          required: false
          description: "`true` adds gated points to admitted ones. Exactly `true` or `false`. Cannot be combined with `gate_reason`."
          schema:
            type: string
            enum: ["true", "false"]
            default: "false"
        - name: gate_reason
          in: query
          required: false
          description: Only points gated for this reason. Cannot be combined with `include_gated`. Capped to a 24-hour window.
          schema:
            $ref: "#/components/schemas/GateReason"
        - name: mode
          in: query
          required: false
          description: Only points with this movement mode. One value. Capped to a 24-hour window.
          schema:
            $ref: "#/components/schemas/Mode"
        - name: order
          in: query
          required: false
          description: |
            `asc` (the default) reads oldest first; `desc` reads the same window newest first, each
            `next_cursor` continuing toward `from`. A cursor must be presented with the order that
            issued it (`asc` and an absent `order` are the same request).
          schema:
            type: string
            enum: [asc, desc]
            default: asc
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of points.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LocationsPage"
              example:
                locations:
                  - accuracy_m: 12.5
                    device:
                      install_id: 2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50
                      user_id: acct_9931
                    id: 01900100-0000-7000-8000-000000000001
                    is_mock: false
                    latitude: 12.9716
                    longitude: 77.5946
                    mode: unknown
                    motion: stationary
                    received_at: "2026-08-06T07:06:45.000Z"
                    recorded_at: "2026-08-06T07:06:41.000Z"
                    source: sdk
                    trigger: check_in
                    trust_tier: unverified
                next_cursor: null
                retention_floor: null
                schema_version: 1
        "400":
          description: |
            One of: `invalid_window`, `window_too_large`, `invalid_install_id`, `invalid_user_id`,
            `invalid_gate_reason`, `invalid_mode`, `invalid_order`, `invalid_include_gated`, `conflicting_filters`,
            `invalid_cursor`, `cursor_query_mismatch`, `limit must be an integer in [1, 500]`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_window
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`the location log is readable by server integrator credentials only` (an SDK session) or `insufficient scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                kind:
                  value:
                    error: the location log is readable by server integrator credentials only
                scope:
                  value:
                    error: insufficient scope
        "410":
          $ref: "#/components/responses/ExpiredCursor"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/locations/feed:
    get:
      tags: [Locations]
      operationId: tailLocations
      summary: Read every stored point once, in the order it arrived
      description: |
        Every point of the project once, in the order the server finished judging it (each
        upload's admission), and within one upload by `(recorded_at, id)`. A device that was
        offline delivers points recorded long ago; they appear after the cursor you already hold,
        never below it. Keep `next_cursor` and present it on the next call: it is always a token,
        and an empty page means nothing new yet, so poll again later.
        Admitted points only by default; `include_gated=true` adds gated points (each with
        `gate`). A point is served only once its verdict is final, so `gate` never changes after
        you read it. Points recorded below `retention_floor` are never served. Positions are kept
        for 7 days: a cursor older than that is `410 expired_cursor`; restart without a cursor and
        fill the gap with `GET /v1/locations` windows. Points stored before this operation existed
        are not in the feed; read them with `GET /v1/locations`.
        There is no window and no filter: `from`, `to`, `install_id`, `user_id`, `gate_reason`,
        `mode` and `order` are ignored here. A point can be served twice after an operator
        re-admission, so deduplicate on `(id, recorded_at)`.
      security:
        - session: ["locations:read"]
      x-beekon-scope: locations:read
      parameters:
        - name: include_gated
          in: query
          required: false
          description: "`true` adds gated points to admitted ones. Exactly `true` or `false`."
          schema:
            type: string
            enum: ["true", "false"]
            default: "false"
        - $ref: "#/components/parameters/Limit"
        - name: cursor
          in: query
          required: false
          description: The previous page's `next_cursor`, verbatim (prefix `lf1_`). Opaque; bound to the project. Absent or empty starts at the oldest retained position; repeated is `invalid_cursor`.
          schema:
            type: string
            maxLength: 256
      responses:
        "200":
          description: A page of points, oldest arrival first.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LocationFeedPage"
              example:
                locations:
                  - accuracy_m: 12.5
                    device:
                      install_id: 2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50
                      user_id: acct_9931
                    id: 01900100-0000-7000-8000-000000000001
                    is_mock: false
                    latitude: 12.9716
                    longitude: 77.5946
                    mode: unknown
                    motion: stationary
                    received_at: "2026-08-06T07:06:45.000Z"
                    recorded_at: "2026-08-06T07:06:41.000Z"
                    source: sdk
                    trigger: check_in
                    trust_tier: unverified
                next_cursor: lf1_AAAAAABq0DsAAAAAAAAAKgAAAAAAAAABEF8P2km-dsM
                retention_floor: null
                schema_version: 1
        "400":
          description: |
            One of: `invalid_include_gated`, `invalid_cursor`, `cursor_query_mismatch` (a cursor
            from another project), `limit must be an integer in [1, 500]`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_cursor
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "410":
          $ref: "#/components/responses/ExpiredCursor"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/ingest:
    post:
      tags: [Locations]
      operationId: ingestLocations
      summary: Upload location points from your server
      description: |
        Stores the points of one upload in the SDK's upload format (the envelope documented at
        https://docs.getbeekon.com/guide/payload/#the-upload-payload). The body is plain JSON, or
        gzip when the request carries `Content-Encoding: gzip`; at most 2 MiB compressed and
        decompressed, and at most 1000 locations across all segments. Members the server does not
        read are ignored. Each location `id` is a UUID and the deduplication key: a point whose id
        is already stored is skipped, so re-sending a batch is safe.

        Points uploaded with a server key are stored with `source: "server"` and evaluated for
        trips and geofence events like the SDK's. A server key's `reported_state` is dropped, and
        its `200` is always an empty body. A device that only arrives through this endpoint keeps
        `reported_at`, `applied_config_revision`, `apply_status` and `health` null. SDK sessions
        also use this endpoint; they pass the scope check, and their `200` may carry a JSON body
        for the device.
      security:
        - session: ["locations:write"]
      x-beekon-scope: locations:write
      parameters:
        - name: Content-Encoding
          in: header
          required: false
          description: "`gzip` when the body is gzipped. Absent: the body is plain JSON."
          schema:
            type: string
            enum: [gzip]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IngestBatch"
            example:
              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
      responses:
        "200":
          description: The points are stored. A server key's upload gets an empty body.
        "400":
          description: "`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 to 90 or a longitude outside -180 to 180; a negative `accuracy`; `extras` over 4 KiB encoded, or another bound exceeded; or `sent_at` more than 24 hours ahead). One bad point refuses the whole batch. Also `malformed gzip request body` or `unreadable request body`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid batch
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`insufficient scope`: the key lacks `locations:write`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: insufficient scope
        "413":
          description: "`request body exceeds the 2 MiB cap`, `decompressed request body exceeds the 2 MiB cap`, `batch exceeds the 1000-row cap`, or `batch exceeds the extras size bound` (the encoded `extras` times the batch's number of points is over 256 KiB). Split the batch."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: batch exceeds the 1000-row cap
        "429":
          description: "`rate limit exceeded for this credential, retry`: uploads are limited per key."
          headers:
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: rate limit exceeded for this credential, retry
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          description: "`cell is at capacity, retry` or `unsupported producer class, retry` (the session token names a client this server does not recognise): brief, retry after Retry-After. `unsupported schema_version` or `project suspended`: not brief, a retry will not fix them, so do not retry blindly. Every 503 carries Retry-After."
          headers:
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: cell is at capacity, retry
  /v1/events:
    get:
      tags: [Events]
      operationId: listEvents
      summary: Read the project's event log
      description: |
        The event log in commit order, as a never-ending, never-skipping feed. `next_cursor` is
        always present and never null; an empty page echoes the request cursor. Unfiltered and
        project-wide. Events stay readable for at least 7 days. Geofence, trip, device presence
        (`device.unreachable` and `device.reachable`, from the next backend release) and
        billing.usage_threshold events all appear here, in one log order. `webhook.ping` never
        appears here.
      security:
        - session: ["events:read"]
      x-beekon-scope: events:read
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size, 1 to 500. Never clamped; out of range or unparseable is a 400. An empty value counts as absent. Repeated, the first is read (this endpoint predates the repeated-parameter rule).
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: cursor
          in: query
          required: false
          description: The previous page's `next_cursor`. Absent or empty starts from the oldest retained event.
          schema:
            type: string
            maxLength: 256
      responses:
        "200":
          description: A page of events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventsPage"
        "400":
          description: "`invalid_cursor` or `limit must be an integer in [1, 500]`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_cursor
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`the event log is readable by server integrator credentials only` (an SDK session) or `insufficient scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                kind:
                  value:
                    error: the event log is readable by server integrator credentials only
                scope:
                  value:
                    error: insufficient scope
        "410":
          $ref: "#/components/responses/ExpiredCursor"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/trips:
    get:
      tags: [Trips]
      operationId: listTrips
      summary: List trips
      description: |
        Trips (open and closed) ordered by `started_at`, then `id`, paged with a `tr1_` cursor
        bound to `install_id`, `from` and `to`. A trip is listed when it overlaps the window:
        `last_point_at >= from` and `started_at < to`. Either bound may be omitted. No maximum
        window. A defined parameter sent twice, or empty, is a 400.
      security:
        - session: ["trips:read"]
      x-beekon-scope: trips:read
      parameters:
        - name: install_id
          in: query
          required: false
          description: Only this device's trips. Non-blank, at most 128 bytes.
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: from
          in: query
          required: false
          description: Only trips with `last_point_at` at or after this instant. RFC 3339, any offset.
          schema:
            type: string
            format: date-time
          example: "2026-10-07T00:00:00Z"
        - name: to
          in: query
          required: false
          description: Only trips with `started_at` before this instant. RFC 3339, any offset. Must be after `from`.
          schema:
            type: string
            format: date-time
          example: "2026-10-08T00:00:00Z"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of trips.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TripsPage"
              example:
                next_cursor: null
                trips:
                  - distance_m: 5234.81
                    duration_seconds: 1122
                    end:
                      latitude: 12.9352
                      longitude: 77.6245
                    end_reason: stop
                    ended_at: "2026-10-07T09:18:42.000Z"
                    id: 5b0d3c6e-2f1a-8c4d-9e7f-0a1b2c3d4e5f
                    install_id: 2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50
                    last_point_at: "2026-10-07T09:18:42.000Z"
                    mode: driving
                    mode_counts:
                      driving: 41
                      still: 3
                      walking: 2
                    point_count: 46
                    revision: 2
                    settings_revision: 7
                    start:
                      latitude: 12.9716
                      longitude: 77.5946
                    started_at: "2026-10-07T09:00:00.000Z"
                    status: closed
                    user_id: acct_9931
        "400":
          description: |
            One of: `invalid_install_id`, `invalid_window`, `invalid_cursor`,
            `cursor_query_mismatch`, `limit must be an integer in [1, 500]`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_window
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/trips/{trip_id}:
    get:
      tags: [Trips]
      operationId: getTrip
      summary: Read one trip
      security:
        - session: ["trips:read"]
      x-beekon-scope: trips:read
      parameters:
        - $ref: "#/components/parameters/TripId"
      responses:
        "200":
          description: The trip.
          content:
            application/json:
              schema:
                type: object
                required: [trip]
                properties:
                  trip:
                    $ref: "#/components/schemas/Trip"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/trips/{trip_id}/points:
    get:
      tags: [Trips]
      operationId: listTripPoints
      summary: List a trip's points
      description: |
        The location points counted in the trip, ordered by `(recorded_at, id)`, as the same point
        objects `GET /v1/locations` returns. Paged with a `tr1_` cursor bound to the trip. An open
        trip's newest, not yet counted points are not listed.
      security:
        - session: ["trips:read"]
      x-beekon-scope: trips:read
      parameters:
        - $ref: "#/components/parameters/TripId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of the trip's points.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TripPointsPage"
        "400":
          description: "`invalid_cursor`, `cursor_query_mismatch` or `limit must be an integer in [1, 500]`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_cursor
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/geofences:
    get:
      tags: [Geofences]
      operationId: listGeofences
      summary: List geofences
      description: The project's geofences, ordered by `id`, paged with a `gf1_` cursor. No filters.
      security:
        - session: ["geofences:read"]
      x-beekon-scope: geofences:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of geofences.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeofencesPage"
        "400":
          $ref: "#/components/responses/BadPaging"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
    post:
      tags: [Geofences]
      operationId: createGeofence
      summary: Create a geofence
      description: Not idempotent. The 201 body is identical to a following GET.
      security:
        - session: ["geofences:write"]
      x-beekon-scope: geofences:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeofenceInput"
            example:
              name: HQ
              geometry:
                type: circle
                center:
                  latitude: 12.9716
                  longitude: 77.5946
                radius_meters: 150
              notify_on_entry: true
              notify_on_exit: false
      responses:
        "201":
          description: The created geofence.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeofenceEnvelope"
              example:
                geofence:
                  created_at: "2026-10-07T06:30:00.000Z"
                  geometry:
                    center:
                      latitude: 12.9716
                      longitude: 77.5946
                    radius_meters: 150
                    type: circle
                  id: 0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d
                  name: HQ
                  notify_on_entry: true
                  notify_on_exit: false
                  on_unreachable: "none"
                  pass_through: "off"
                  updated_at: "2026-10-07T06:30:00.000Z"
        "400":
          $ref: "#/components/responses/BadGeofence"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: "A plan limit: `quota_fences`, `quota_vertices` or `quota_area`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: quota_fences
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/geofences/{fence_id}:
    get:
      tags: [Geofences]
      operationId: getGeofence
      summary: Read one geofence
      security:
        - session: ["geofences:read"]
      x-beekon-scope: geofences:read
      parameters:
        - $ref: "#/components/parameters/FenceId"
      responses:
        "200":
          description: The geofence.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeofenceEnvelope"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
    put:
      tags: [Geofences]
      operationId: replaceGeofence
      summary: Replace a geofence
      description: |
        A full replace with the same body as create: an omitted `notification` clears it. The body
        is validated before the id is looked up. Checked against the vertex and area limits, never
        the count.
      security:
        - session: ["geofences:write"]
      x-beekon-scope: geofences:write
      parameters:
        - $ref: "#/components/parameters/FenceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeofenceInput"
      responses:
        "200":
          description: The replaced geofence.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeofenceEnvelope"
        "400":
          $ref: "#/components/responses/BadGeofence"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "A plan limit: `quota_vertices` or `quota_area`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: quota_vertices
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
    delete:
      tags: [Geofences]
      operationId: deleteGeofence
      summary: Delete a geofence
      description: A second delete of the same id is a 404.
      security:
        - session: ["geofences:write"]
      x-beekon-scope: geofences:write
      parameters:
        - $ref: "#/components/parameters/FenceId"
      responses:
        "204":
          description: Deleted. No body.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/config/document:
    get:
      tags: [Remote config]
      operationId: getConfigDocument
      summary: Read the remote-config document
      description: |
        Every section fully materialized, with defaults for anything never set. Always 200 with the
        full document; `If-None-Match` is not answered.
      security:
        - session: ["config:read"]
      x-beekon-scope: config:read
      responses:
        "200":
          description: The document.
          headers:
            ETag:
              $ref: "#/components/headers/ConfigETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigDocument"
              example:
                diagnostics: {}
                features: {}
                filters:
                  accuracy_enabled: true
                  max_accuracy_meters: 200
                  max_speed_mps: 350
                  mock_enabled: true
                  teleport_enabled: true
                privacy: {}
                revision: 1
                sync:
                  batch_size: 100
                  charging_only: false
                  interval_seconds: 300
                  sync_threshold: 0
                  unmetered_only: false
                tracking:
                  accuracy_mode: balanced
                  detect_activity: false
                  heartbeat_interval_seconds: 0
                  max_queue_size: 100000
                  min_distance_between_locations_meters: 100
                  min_time_between_locations_seconds: 30
                  stationary_radius_meters: 5
                  when_stationary: pause
                trips:
                  max_accuracy_meters: 100
                  max_gap_seconds: 600
                  min_distance_meters: 250
                  min_duration_seconds: 120
                  stop_duration_seconds: 300
                  stop_radius_meters: 100
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
    put:
      tags: [Remote config]
      operationId: replaceConfigDocument
      summary: Replace the remote-config document
      description: |
        A replace. `tracking`, `sync`, `privacy`, `features`, `diagnostics` and
        `poll_interval_seconds` are reset to their defaults when left out or null; `trips`,
        `presence` and `filters` are kept as stored when left out and reset when null. Absent knobs inside a
        present section take their defaults. Values are rejected, never clamped. A write that
        changes nothing keeps the revision. Checks run in this order: 413, `invalid_if_match`,
        `invalid_body`, `invalid_config: <paths>`, 412.
      security:
        - session: ["config:write"]
      x-beekon-scope: config:write
      parameters:
        - name: If-Match
          in: header
          required: false
          description: |
            `W/"<revision>"` exactly as served in `ETag` (the write happens only if that revision
            is current, else 412), or `*` (any revision). Absent makes the write unconditional.
            Anything else, including the strong form `"<revision>"`, a list or a repeated header,
            is `400 invalid_if_match`.
          schema:
            type: string
            pattern: '^(\*|W/"(0|[1-9][0-9]*)")$'
          example: W/"1"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfigDocumentInput"
            example:
              tracking:
                accuracy_mode: high
                detect_activity: true
              sync:
                interval_seconds: 120
      responses:
        "200":
          description: The stored document, as a following GET returns it.
          headers:
            ETag:
              $ref: "#/components/headers/ConfigETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigDocument"
        "400":
          description: |
            `invalid_if_match`, `invalid_body` (not one JSON object), or
            `invalid_config: <paths>` naming every offending member as dotted paths in ASCII
            order, `", "`-joined. Prefix-match `invalid_config:`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "invalid_config: sync.batch_size, tracking.accuracy_mode"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "412":
          description: "`precondition_failed`: `If-Match` names a revision that is not current. No ETag; re-read."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: precondition_failed
        "413":
          description: "`too_large`: the body is over 65536 bytes."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: too_large
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/webhooks:
    get:
      tags: [Webhooks]
      operationId: listWebhooks
      summary: List webhook endpoints
      description: The project's webhook endpoints, oldest first (`created_at`, then `id`), paged with a `wh1_` cursor.
      security:
        - session: ["webhooks:read"]
      x-beekon-scope: webhooks:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of webhook endpoints.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhooksPage"
        "400":
          $ref: "#/components/responses/BadPaging"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
    post:
      tags: [Webhooks]
      operationId: createWebhook
      summary: Create a webhook endpoint
      description: |
        Creates an `active` webhook endpoint and returns its signing secret, once. At most 10
        endpoints per project (disabled ones count). Not idempotent.
      security:
        - session: ["webhooks:write"]
      x-beekon-scope: webhooks:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookCreate"
            example:
              endpoint_url: https://hooks.example.com/beekon
              event_types: [geofence.enter, geofence.exit]
      responses:
        "201":
          description: The webhook endpoint and its secret. A key without `webhooks:read` gets the reduced object.
          headers:
            Cache-Control:
              $ref: "#/components/headers/NoStore"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookWithSecret"
              example:
                secret: whsec_REDACTED_EXAMPLE
                webhook:
                  auto_disabled_at: null
                  created_at: "2026-10-07T06:30:00.000Z"
                  endpoint_url: https://hooks.example.com/beekon
                  event_types: [geofence.enter, geofence.exit]
                  id: 0199b2d1-3c4d-7e5f-8a9b-0c1d2e3f4a5b
                  project_id: 019000b0-0000-7000-8000-0000000000b1
                  status: active
                  updated_at: "2026-10-07T06:30:00.000Z"
        "400":
          $ref: "#/components/responses/BadWebhook"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: "`webhook_limit_reached`: the project already has 10 webhook endpoints."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: webhook_limit_reached
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/webhooks/{webhook_id}:
    get:
      tags: [Webhooks]
      operationId: getWebhook
      summary: Read one webhook endpoint
      security:
        - session: ["webhooks:read"]
      x-beekon-scope: webhooks:read
      parameters:
        - $ref: "#/components/parameters/WebhookId"
      responses:
        "200":
          description: The webhook endpoint.
          content:
            application/json:
              schema:
                type: object
                required: [webhook]
                properties:
                  webhook:
                    $ref: "#/components/schemas/Webhook"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
    patch:
      tags: [Webhooks]
      operationId: updateWebhook
      summary: Change a webhook endpoint
      description: |
        Changes any non-empty subset of `endpoint_url`, `event_types` and `status` in one step.
        Any successful write lifts an auto-disable.
      security:
        - session: ["webhooks:write"]
      x-beekon-scope: webhooks:write
      parameters:
        - $ref: "#/components/parameters/WebhookId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookPatch"
            example:
              status: disabled
      responses:
        "200":
          description: The webhook endpoint. A key without `webhooks:read` gets the reduced object.
          content:
            application/json:
              schema:
                type: object
                required: [webhook]
                properties:
                  webhook:
                    $ref: "#/components/schemas/WebhookForWriter"
        "400":
          $ref: "#/components/responses/BadWebhook"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
    delete:
      tags: [Webhooks]
      operationId: deleteWebhook
      summary: Delete a webhook endpoint
      description: Deletes it and discards its pending deliveries. A second delete is a 404.
      security:
        - session: ["webhooks:write"]
      x-beekon-scope: webhooks:write
      parameters:
        - $ref: "#/components/parameters/WebhookId"
      responses:
        "204":
          description: Deleted. No body.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/webhooks/{webhook_id}/rotate-secret:
    post:
      tags: [Webhooks]
      operationId: rotateWebhookSecret
      summary: Rotate a webhook endpoint's signing secret
      description: |
        Mints a new secret and returns it, once. By default the previous secret stays valid (and
        deliveries are signed with both) until the next rotation; `expire_previous: true` drops it
        at once. The body is optional.
      security:
        - session: ["webhooks:write"]
      x-beekon-scope: webhooks:write
      parameters:
        - $ref: "#/components/parameters/WebhookId"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RotateSecretRequest"
            example:
              expire_previous: true
      responses:
        "200":
          description: The new secret and the webhook endpoint. A key without `webhooks:read` gets the reduced object.
          headers:
            Cache-Control:
              $ref: "#/components/headers/NoStore"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookWithSecret"
        "400":
          description: "`invalid_body`: a body that is not empty and not `{\"expire_previous\": <boolean>}`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/webhooks/{webhook_id}/ping:
    post:
      tags: [Webhooks]
      operationId: pingWebhook
      summary: Send a signed test delivery
      description: |
        Sends one signed `webhook.ping` delivery to the endpoint's URL, whatever the endpoint's
        status and event types, and reports the outcome. Takes no body. Answers 200 whatever the
        endpoint did. When the endpoint gives no HTTP response, the answer comes exactly 10
        seconds after the ping started, with `status_code: null`. Limited to 1 a minute per
        endpoint (burst 3) and 20 an hour per project.
      security:
        - session: ["webhooks:write"]
      x-beekon-scope: webhooks:write
      parameters:
        - $ref: "#/components/parameters/WebhookId"
      responses:
        "200":
          description: The ping's outcome.
          content:
            application/json:
              schema:
                type: object
                required: [ping]
                properties:
                  ping:
                    $ref: "#/components/schemas/PingResult"
              example:
                ping:
                  delivered: true
                  delivery_id: 0199b2d4-1b2c-7d3e-8f40-516273849506
                  status_code: 200
        "400":
          description: "`invalid_body`: the request carried a body."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/Unavailable"
components:
  securitySchemes:
    serverKey:
      type: http
      scheme: bearer
      description: A `bkserv_<cell>_<secret>` server key (or a `bkproj_` SDK key). Accepted only by `POST /v1/token`.
    session:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        A session token from `POST /v1/token`. Treat it as opaque. The scopes in each operation's
        security requirement are the server key's scopes the operation needs (exact match, no
        wildcards, write does not imply read). The 15 scopes: project:read, locations:read,
        locations:write, events:read, devices:read, devices:write, geofences:read,
        geofences:write, config:read, config:write, trips:read, users:read, users:write,
        webhooks:read, webhooks:write. Keys issued before scopes hold events:read,
        locations:read and locations:write; no existing key gains users:read or users:write.
        devices:read discloses each device's current user id (the device's `user_id` member),
        as locations:read and events:read disclose the ids on points and events.
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Page size, 1 to 500. Never clamped; out of range, unparseable or repeated is a 400 (`GET /v1/events` defines its own `limit`, which reads the first of a repeated value). An empty value counts as absent.
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
    Cursor:
      name: cursor
      in: query
      required: false
      description: The previous page's `next_cursor`, verbatim. Opaque; bound to the query that produced it. Absent or empty starts the walk; repeated is `invalid_cursor`.
      schema:
        type: string
        maxLength: 256
    UsersCursor:
      name: cursor
      in: query
      required: false
      description: The previous page's `next_cursor`, verbatim. Opaque; bound to the query that produced it. Absent or empty starts the walk; repeated is `invalid_cursor`. A users cursor can be up to 356 bytes long.
      schema:
        type: string
        maxLength: 356
    UserIdPath:
      name: user_id
      in: path
      required: true
      description: |
        The user id your app set, exactly (compared as bytes: never trimmed, case-folded or
        normalised). Percent-encode it as one path segment: `a%2Fb` is the user `a/b`, `%25` a
        literal `%`. 1 to 256 bytes of UTF-8 with no control character, else `invalid_user_id`.
        An id that is exactly `.` or `..` cannot be addressed by path.
        Stored as sent: send an opaque stable identifier (a database key), never an email or
        phone number.
      schema:
        type: string
        minLength: 1
        maxLength: 256
      example: customer-42
    UserIdFilter:
      name: user_id
      in: query
      required: false
      description: |
        Only the devices whose current `user_id` is exactly this id. Form-encoded like every query
        value: `+` is a space, so send a literal `+` as `%2B`. Empty, repeated, over 256 bytes,
        not UTF-8 or carrying a control character is `invalid_user_id`.
      schema:
        type: string
        minLength: 1
        maxLength: 256
    InstallIdPath:
      name: install_id
      in: path
      required: true
      description: The device's install id, as the SDK generated it. Opaque text, not necessarily a UUID; URL-encode it.
      schema:
        type: string
      example: 2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50
    TripId:
      name: trip_id
      in: path
      required: true
      description: The trip id. A malformed id is a 404, like an unknown one.
      schema:
        type: string
        format: uuid
      example: 5b0d3c6e-2f1a-8c4d-9e7f-0a1b2c3d4e5f
    FenceId:
      name: fence_id
      in: path
      required: true
      description: The geofence id. A malformed id is a 404, like an unknown one.
      schema:
        type: string
        format: uuid
      example: 0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d
    WebhookId:
      name: webhook_id
      in: path
      required: true
      description: The webhook endpoint's id. A malformed id is a 404, like an unknown one.
      schema:
        type: string
        format: uuid
      example: 0199b2d1-3c4d-7e5f-8a9b-0c1d2e3f4a5b
  headers:
    RetryAfter:
      description: Seconds to wait before retrying, 1 to 3600.
      schema:
        type: integer
        minimum: 1
        maximum: 3600
    ConfigETag:
      description: The document's revision as a weak tag, `W/"<revision>"`. Send it back in `If-Match`.
      schema:
        type: string
        pattern: '^W/"(0|[1-9][0-9]*)"$'
      example: W/"1"
    NoStore:
      description: "`no-store`: the body carries a secret."
      schema:
        type: string
        const: no-store
  responses:
    Unauthorized:
      description: "`missing bearer token` or `invalid session token`. Mint a new token and retry once."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: invalid session token
    Forbidden:
      description: "`server credentials required` (a session minted from an SDK key) or `insufficient scope` (the key lacks this operation's scope)."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            kind:
              value:
                error: server credentials required
            scope:
              value:
                error: insufficient scope
    NotFound:
      description: "`not found`: an unknown id, another project's id, or a malformed UUID id (geofence, trip, webhook). A malformed `user_id` is `400 invalid_user_id` instead. A path no operation serves gets the same body."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: not found
    BadPaging:
      description: "`limit must be an integer in [1, 500]`, `invalid_cursor`, or, on `GET /v1/users`, `cursor_query_mismatch` (a cursor from another project)."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            limit:
              value:
                error: limit must be an integer in [1, 500]
            cursor:
              value:
                error: invalid_cursor
            mismatch:
              value:
                error: cursor_query_mismatch
    BadUserId:
      description: "`invalid_user_id`: the id is empty, over 256 bytes, not UTF-8, or carries a control character, so no stored user can have it."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: invalid_user_id
    BadDevicesQuery:
      description: "In this order: `limit must be an integer in [1, 500]`, `invalid_user_id` (the user id, in the path or the `user_id` filter), `invalid_cursor`, `cursor_query_mismatch` (a cursor minted for another user id, or for none)."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            limit:
              value:
                error: limit must be an integer in [1, 500]
            user:
              value:
                error: invalid_user_id
            cursor:
              value:
                error: cursor_query_mismatch
    BadGeofence:
      description: |
        `invalid_body` (not one object, a required member missing or null, a wrong type, an
        unknown member, a repeated key, or over 1 MiB), `invalid_name`, `invalid_geometry`,
        `invalid_notification`, or a geometry reason: `shape_unknown`, `coordinate_out_of_range`,
        `radius_not_positive`, `ring_too_few_vertices`, `self_intersection`,
        `hole_outside_shell`, `antimeridian_span`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: self_intersection
    BadWebhook:
      description: |
        `invalid_body` (not one object, over 16 KiB, an unknown member, a repeated key, a wrong
        type, or a PATCH with no member), `invalid_endpoint_url`, `invalid_event_types`, or
        `invalid_status` (PATCH).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: invalid_endpoint_url
    ExpiredCursor:
      description: "`expired_cursor`: the cursor's position was deleted under retention. Restart the walk."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: expired_cursor
    RateLimited:
      description: "Rate limited: `rate limited` (ingest says `rate limit exceeded for this credential, retry`). Any operation may answer it while the platform protects itself. Always carries Retry-After: wait at least that long, then retry the same request."
      headers:
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: rate limited
    Unavailable:
      description: "`unavailable, retry`: the service is briefly busy or unreachable. Any operation may answer it while the platform protects itself. Always carries Retry-After (usually 1 second): retry after it. Any authenticated operation may also answer `credential status unavailable`, when the server cannot read whether the token's key is still valid; retry it the same way."
      headers:
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: unavailable, retry
    InternalError:
      description: "`internal error`: a failure on Beekon's side. Retry with backoff, keeping your cursor."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: internal error
  schemas:
    Error:
      type: object
      description: The one error envelope. Match `error` verbatim.
      required: [error]
      properties:
        error:
          type: string
    Token:
      type: object
      required: [access_token, expires_in]
      properties:
        access_token:
          type: string
          description: The session token. Opaque.
        expires_in:
          type: integer
          description: Seconds until expiry. Read it; do not hard-code it.
          minimum: 1
    Project:
      type: object
      required: [cell, created_at, id, name, status]
      properties:
        cell:
          type: string
          description: The project's region, as in the key and the API host.
          examples: [in1]
        created_at:
          $ref: "#/components/schemas/Timestamp"
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
          enum: [active, suspended]
    Timestamp:
      type: string
      format: date-time
      description: RFC 3339 UTC with exactly three fractional digits.
      examples: ["2026-10-07T06:30:00.000Z"]
    GateReason:
      type: string
      enum: [low_accuracy, implausible_speed, mock]
    User:
      type: object
      description: A user of the project. Exactly these two members, both always present and never null. The user's devices are `GET /v1/users/{user_id}/devices`.
      required: [last_seen, user_id]
      properties:
        last_seen:
          description: When the newest stored point carrying this user id was recorded, on any device (including one that has since moved to another user). It may be newer than any device's last_seen.
          allOf:
            - $ref: "#/components/schemas/Timestamp"
        user_id:
          type: string
          description: The id exactly as your app set it. Stored as sent; send an opaque stable identifier (a database key), never an email or phone number.
          minLength: 1
          maxLength: 256
    UsersPage:
      type: object
      required: [next_cursor, users]
      properties:
        next_cursor:
          type: [string, "null"]
          description: The next page's cursor (prefix `us1_`), or null when the walk is complete. Up to 356 bytes long.
          maxLength: 356
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
    Erasing:
      type: object
      required: [status]
      properties:
        status:
          type: string
          const: erasing
    LocationsPage:
      type: object
      required: [locations, next_cursor, retention_floor, schema_version]
      properties:
        locations:
          type: array
          items:
            $ref: "#/components/schemas/LocationPoint"
        next_cursor:
          type: [string, "null"]
          description: The next page's cursor (prefix `lc1_`), or null when the window is exhausted.
          maxLength: 256
        retention_floor:
          description: The project's retention floor, or null if nothing has been deleted under retention.
          oneOf:
            - $ref: "#/components/schemas/Timestamp"
            - type: "null"
        schema_version:
          type: integer
          const: 1
    LocationFeedPage:
      type: object
      required: [locations, next_cursor, retention_floor, schema_version]
      properties:
        locations:
          type: array
          items:
            $ref: "#/components/schemas/LocationPoint"
        next_cursor:
          type: string
          description: The cursor to present next (prefix `lf1_`). Always present and never null; on an empty page it is the cursor you sent.
          maxLength: 256
        retention_floor:
          description: The project's retention floor, or null if nothing has been deleted under retention. Points recorded below it are not served.
          oneOf:
            - $ref: "#/components/schemas/Timestamp"
            - type: "null"
        schema_version:
          type: integer
          const: 1
    LocationPoint:
      type: object
      description: One stored point. Optional members are omitted when absent. Ignore unknown members and unknown activity, trigger, motion and source values; treat an unknown gate.reason as gated.
      required: [device, id, is_mock, latitude, longitude, mode, motion, received_at, recorded_at, source, trigger, trust_tier]
      properties:
        accuracy_m:
          type: number
        activity:
          type: string
          description: The raw reading - stationary, walking, running, cycling, automotive or unknown. Absent when activity detection is off.
          examples: [walking]
        altitude_m:
          type: number
        battery_percent:
          type: integer
          minimum: 0
          maximum: 100
        bearing_deg:
          type: number
        device:
          $ref: "#/components/schemas/PointDevice"
        extras:
          type: object
          description: The customer's own string map, as uploaded. Untrusted.
          additionalProperties:
            type: string
        gate:
          type: object
          description: Present only on gated points. Absent means admitted. Never present on a trip's points.
          required: [reason]
          properties:
            reason:
              $ref: "#/components/schemas/GateReason"
        id:
          type: string
          format: uuid
          description: Device-minted id, any UUID version. Unique only together with recorded_at.
        is_charging:
          type: boolean
        is_mock:
          type: boolean
        latitude:
          type: number
        longitude:
          type: number
        mode:
          $ref: "#/components/schemas/Mode"
        motion:
          type: string
          description: moving, stationary or unknown.
          examples: [moving]
        power_save_mode:
          type: boolean
        quality:
          type: string
          description: The device's own self-report (low_accuracy or implausible_speed), not the server's verdict.
          examples: [low_accuracy]
        received_at:
          $ref: "#/components/schemas/Timestamp"
        recorded_at:
          $ref: "#/components/schemas/Timestamp"
        source:
          type: string
          description: sdk or server.
          examples: [sdk]
        speed_mps:
          type: number
        trigger:
          type: string
          description: interval, motion, check_in, geofence or manual.
          examples: [interval]
        trust_tier:
          type: string
          description: unverified, attested or verified.
          examples: [unverified]
    PointDevice:
      type: object
      required: [install_id]
      properties:
        install_id:
          type: string
          description: Opaque SDK-generated identifier. Do not type it as a UUID.
        session_id:
          type: string
        user_id:
          type: string
          description: The customer-defined user id set in the SDK at record time.
    EventsPage:
      type: object
      required: [events, next_cursor, schema_version]
      properties:
        events:
          type: array
          description: In log (commit) order. Skip objects whose type you do not know.
          items:
            $ref: "#/components/schemas/Event"
        next_cursor:
          type: string
          description: Always present, never null. An empty page echoes the request cursor (the empty string when none was sent).
          maxLength: 256
        schema_version:
          type: integer
          const: 1
    Event:
      description: An event. New types may appear; consumers skip types they do not know. `webhook.ping` reaches webhooks only, never the cursor page.
      oneOf:
        - $ref: "#/components/schemas/GeofenceEvent"
        - $ref: "#/components/schemas/TripEvent"
        - $ref: "#/components/schemas/DevicePresenceEvent"
        - $ref: "#/components/schemas/UsageThresholdEvent"
        - $ref: "#/components/schemas/PingEvent"
      discriminator:
        propertyName: type
        mapping:
          geofence.enter: "#/components/schemas/GeofenceEvent"
          geofence.exit: "#/components/schemas/GeofenceEvent"
          geofence.dwell: "#/components/schemas/GeofenceEvent"
          trip.started: "#/components/schemas/TripEvent"
          trip.stalled: "#/components/schemas/TripEvent"
          trip.ended: "#/components/schemas/TripEvent"
          device.unreachable: "#/components/schemas/DevicePresenceEvent"
          device.reachable: "#/components/schemas/DevicePresenceEvent"
          billing.usage_threshold: "#/components/schemas/UsageThresholdEvent"
          webhook.ping: "#/components/schemas/PingEvent"
    GeofenceEvent:
      type: object
      description: >-
        A server-decided geofence transition. location is present on every event except one
        with evidence unreachable, where it is absent (never null). A consumer that only uses
        fences with the default policies (pass_through off, on_unreachable none) never sees
        interpolated or unreachable, so location is always present for it. detected_at,
        evidence, late and occurred_after are added in the next backend release; until then
        location is always present.
      required: [device, geofence, id, occurred_at, project_id, type]
      properties:
        detected_at:
          $ref: "#/components/schemas/Timestamp"
          description: When the server produced the event (server clock). At or after occurred_at, except where the device's clock ran ahead of the server's. Present on every event once the region has the next backend release. Added in the next backend release.
        device:
          type: object
          required: [install_id]
          properties:
            install_id:
              type: string
            session_id:
              type: string
            user_id:
              type: string
        dwell_seconds:
          type: number
          description: geofence.dwell only. The threshold crossed, not the total stay. One fixed threshold, 300 today.
        evidence:
          type: string
          description: >-
            What the server's decision rests on. track: admitted points alone confirmed it.
            interpolated: a pass-through, two consecutive outside points whose segment crosses
            the fence (only for a fence with pass_through on). corroborated: a device-reported
            crossing plus a non-contradicting admitted point confirmed it at once. unreachable:
            the device was confirmed inside and then declared unreachable (geofence.exit only,
            only for a fence with on_unreachable exit). New values may appear; read an unknown
            value as "server-decided, evidence unknown". Present on every event once the region
            has the next backend release. Added in the next backend release.
          enum: [track, interpolated, corroborated, unreachable]
        geofence:
          type: object
          required: [id]
          properties:
            external_id:
              type: string
              description: Reserved. Present only for a fence authored with one, which no endpoint offers yet.
            id:
              type: string
              format: uuid
        id:
          type: string
          format: uuid
          description: UUIDv7. The deduplication key.
        late:
          type: boolean
          const: true
          description: Present only as true. The event belongs to a backfilled complete visit; it never describes the device's current state. Added in the next backend release.
        location:
          type: object
          description: >-
            The triggering point. Absent exactly when evidence is unreachable. For interpolated,
            the first observed point after the crossing (so its recorded_at is after occurred_at);
            for geofence.dwell, the most recent point inside the fence at threshold time.
          required: [latitude, longitude, recorded_at]
          properties:
            accuracy_m:
              type: number
              description: Present when the triggering point had an accuracy.
            latitude:
              type: number
            longitude:
              type: number
            recorded_at:
              $ref: "#/components/schemas/Timestamp"
        occurred_after:
          $ref: "#/components/schemas/Timestamp"
          description: >-
            geofence.exit only, when the exit time is a window: the recorded_at of the last inside
            point, and occurred_at is the window's upper bound. Always present with evidence
            unreachable. Added in the next backend release.
        occurred_at:
          $ref: "#/components/schemas/Timestamp"
          description: >-
            When the transition happened, not when it was evaluated or delivered: the confirming
            point's recorded_at (track, corroborated), the instant interpolated between two
            observed points (interpolated), the presence deadline that passed (unreachable, server
            clock), or the instant the dwell threshold was crossed (geofence.dwell).
        project_id:
          type: string
          format: uuid
        type:
          type: string
          enum: [geofence.enter, geofence.exit, geofence.dwell]
      example:
        detected_at: "2026-06-07T00:00:02.000Z"
        device:
          install_id: install-e1
        evidence: track
        geofence:
          id: 019000f0-0000-7000-8000-0000000000f1
        id: 019e9f61-1400-7000-8000-0000000000e1
        location:
          accuracy_m: 12.5
          latitude: 12.9716
          longitude: 77.5946
          recorded_at: "2026-06-07T00:00:00.000Z"
        occurred_at: "2026-06-07T00:00:00.000Z"
        project_id: 019000b0-0000-7000-8000-0000000000b1
        type: geofence.enter
    TripEvent:
      type: object
      description: >-
        trip.started fires once, when a trip is first stored (at its third point).
        trip.stalled (next backend release) fires once per stall, when an open trip goes quiet for
        silence_timeout_seconds (default: the effective max_gap_seconds) or presence declares the device unreachable;
        a trip may stall more than once, and the higher trip.revision wins. A return from
        stalled to open sends nothing. trip.ended fires exactly once, when a stored trip
        first becomes closed, and is final: a stop() closes it within seconds
        (end_reason tracking_stopped), and a trip whose install has no contact for
        finality_timeout_seconds (default 86400) closes with end_reason silence. Ignore a
        trip.stalled that arrives after the trip's trip.ended. A trip uploaded whole
        produces trip.started and trip.ended. A trip.ended can come without a
        trip.started. A rebuild, retention, erasure or a late point that changes a closed
        trip sends none. trip.stalled, detected_at, and the tracking_stopped and silence closes
        are added in the next backend release.
      required: [device, id, occurred_at, project_id, trip, type]
      properties:
        detected_at:
          $ref: "#/components/schemas/Timestamp"
          description: The production instant (server clock). For trip.stalled, at least silence_timeout_seconds after the install's last contact. Added in the next backend release.
        device:
          type: object
          required: [install_id]
          properties:
            install_id:
              type: string
            user_id:
              type: string
              description: Present when the trip has a user_id.
        id:
          type: string
          format: uuid
          description: UUIDv7. The deduplication key.
        occurred_at:
          $ref: "#/components/schemas/Timestamp"
          description: The trip's started_at (trip.started), last_point_at (trip.stalled) or ended_at (trip.ended), on the device's recorded timeline. Never the production or delivery instant.
        project_id:
          type: string
          format: uuid
        trip:
          $ref: "#/components/schemas/Trip"
          description: The trip exactly as GET /v1/trips/{trip_id} rendered it when the event was produced (status stalled on trip.stalled, closed on trip.ended). Never updated afterwards; trip.revision says which revision it was.
        type:
          type: string
          enum: [trip.started, trip.stalled, trip.ended]
      example:
        detected_at: "2026-10-07T09:18:44.000Z"
        device:
          install_id: 2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50
          user_id: acct_9931
        id: 01a115a8-6d50-7b4d-8e32-7c6f5a4b3d21
        occurred_at: "2026-10-07T09:18:42.000Z"
        project_id: 019000b0-0000-7000-8000-0000000000b1
        trip:
          distance_m: 5234.81
          duration_seconds: 1122
          end:
            latitude: 12.9352
            longitude: 77.6245
          end_reason: stop
          ended_at: "2026-10-07T09:18:42.000Z"
          id: 5b0d3c6e-2f1a-8c4d-9e7f-0a1b2c3d4e5f
          install_id: 2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50
          last_point_at: "2026-10-07T09:18:42.000Z"
          mode: driving
          mode_counts:
            driving: 41
            still: 3
            walking: 2
          point_count: 46
          revision: 2
          settings_revision: 7
          start:
            latitude: 12.9716
            longitude: 77.5946
          started_at: "2026-10-07T09:00:00.000Z"
          status: closed
          user_id: acct_9931
        type: trip.ended
    DevicePresenceEvent:
      type: object
      description: >-
        device.unreachable fires once per episode when an install with context (a fence it is
        confirmed inside, or an open or stalled trip) stops being reachable; device.reachable
        fires once when contact returns, only for an episode that produced a
        device.unreachable. Installs without context change state silently. Delivery is
        unordered, so a device.reachable may arrive first: correlate by
        presence.unreachable_event_id. A device.unreachable says nothing about where the
        device is; fence exits and trip stalls are separate events. Both types are added in
        the next backend release.
      required: [detected_at, device, id, occurred_at, presence, project_id, type]
      properties:
        detected_at:
          $ref: "#/components/schemas/Timestamp"
          description: The production instant (server clock), at or after occurred_at.
        device:
          type: object
          required: [install_id]
          properties:
            install_id:
              type: string
            user_id:
              type: string
              description: Present when the install's newest admitted fix carried a user_id.
        id:
          type: string
          format: uuid
          description: UUIDv7. The deduplication key.
        occurred_at:
          $ref: "#/components/schemas/Timestamp"
          description: >-
            Server clock. device.unreachable: the deadline that passed (silent_while_moving,
            rest_limit) or the receipt time of the contact that reported it (tracking_stopped,
            permission_lost). device.reachable: the receipt time of the contact that ended the
            episode.
        presence:
          type: object
          required: [context, last_contact_at]
          properties:
            context:
              type: object
              description: What the install was doing when the event was produced.
              required: [geofences]
              properties:
                geofences:
                  type: array
                  description: Every fence the install is confirmed inside, in ascending id order. May be empty.
                  items:
                    type: object
                    required: [id]
                    properties:
                      external_id:
                        type: string
                        description: Reserved. Present only for a fence authored with one, which no endpoint offers yet.
                      id:
                        type: string
                        format: uuid
                trip_id:
                  type: string
                  format: uuid
                  description: Present when the install has an open or stalled trip.
            last_contact_at:
              $ref: "#/components/schemas/Timestamp"
              description: The receipt time of the install's last accepted envelope before the episode.
            last_fix:
              type: object
              description: The install's newest admitted fix. Absent when the install never sent one.
              required: [latitude, longitude, recorded_at]
              properties:
                accuracy_m:
                  type: number
                  description: Present when the fix had an accuracy.
                latitude:
                  type: number
                longitude:
                  type: number
                recorded_at:
                  $ref: "#/components/schemas/Timestamp"
            probe_unanswered:
              type: boolean
              const: true
              description: device.unreachable only, present only as true. The server probed the device in this silence and no answer arrived. The push probe arrives switched off with the next backend release; until the region enables it and an SDK release after 0.5.0 registers a push token, no event carries this member.
            reason:
              type: string
              description: >-
                device.unreachable only. silent_while_moving: a moving device went silent past
                its contact deadline. rest_limit: a resting device stayed silent past the
                project's rest limit. tracking_stopped: the app stopped tracking.
                permission_lost: the device reported it lost location permission. New values may
                appear; read an unknown one as "unreachable, reason unknown".
              enum: [silent_while_moving, rest_limit, tracking_stopped, permission_lost]
            unreachable_event_id:
              type: string
              format: uuid
              description: device.reachable only. The id of the device.unreachable that opened the episode.
        project_id:
          type: string
          format: uuid
        type:
          type: string
          enum: [device.unreachable, device.reachable]
      example:
        detected_at: "2026-06-07T02:02:41.000Z"
        device:
          install_id: 9f1b6c2e-8d4a-4b7f-9c3d-2e1f0a9b8c7d
          user_id: customer-42
        id: 019000ee-0000-7000-8000-0000000000a1
        occurred_at: "2026-06-07T02:00:00.000Z"
        presence:
          context:
            geofences:
              - id: 019000f0-0000-7000-8000-0000000000f1
          last_contact_at: "2026-06-06T14:00:00.000Z"
          last_fix:
            accuracy_m: 9.5
            latitude: 12.9716
            longitude: 77.5946
            recorded_at: "2026-06-06T13:59:58.000Z"
          reason: rest_limit
        project_id: 019000b0-0000-7000-8000-0000000000b1
        type: device.unreachable
    UsageThresholdEvent:
      type: object
      required: [id, occurred_at, project_id, type, usage]
      properties:
        id:
          type: string
          format: uuid
        occurred_at:
          $ref: "#/components/schemas/Timestamp"
        project_id:
          type: string
          format: uuid
        type:
          type: string
          const: billing.usage_threshold
        usage:
          type: object
          required: [cap_mtu, month, mtu, threshold, year]
          properties:
            cap_mtu:
              type: integer
              minimum: 0
            month:
              type: integer
              minimum: 1
              maximum: 12
            mtu:
              type: integer
              minimum: 0
            threshold:
              type: integer
              enum: [50, 80, 100]
            year:
              type: integer
              minimum: 0
      example:
        id: 019ecb27-2200-7000-8000-0000000000b8
        occurred_at: "2026-06-15T12:00:00.000Z"
        project_id: 019000b0-0000-7000-8000-0000000000b1
        type: billing.usage_threshold
        usage:
          cap_mtu: 100
          month: 6
          mtu: 85
          threshold: 80
          year: 2026
    Mode:
      type: string
      description: The normalized movement mode, derived from `activity` (automotive → driving, stationary → still; anything unrecognised or absent → unknown). Treat an unknown value as `unknown`.
      enum: [still, walking, running, cycling, driving, unknown]
    PingEvent:
      type: object
      description: A test delivery, sent only to the pinged endpoint. Never stored, never retried, never in the cursor page.
      required: [id, occurred_at, project_id, type]
      properties:
        id:
          type: string
          format: uuid
        occurred_at:
          $ref: "#/components/schemas/Timestamp"
        project_id:
          type: string
          format: uuid
        type:
          type: string
          const: webhook.ping
      example:
        id: 01a1150d-fa40-7c2d-8e3f-405162738495
        occurred_at: "2026-10-07T06:30:00.000Z"
        project_id: 019000b0-0000-7000-8000-0000000000b1
        type: webhook.ping
    Device:
      type: object
      description: All ten members are always present; every member except install_id may be null — the reported members until the device has reported them, user_id while the device has no current user.
      required: [applied_config_revision, apply_status, health, install_id, last_seen, model, platform, reported_at, sdk_version, user_id]
      properties:
        applied_config_revision:
          type: [integer, "null"]
          description: The remote-config revision the device last applied.
        apply_status:
          type: [string, "null"]
          description: success, partial or failed. Ignore unknown values.
          examples: [success]
        health:
          type: [object, "null"]
          description: The device's last health snapshot, as sent. Every member optional; ignore unknown members.
          properties:
            permission:
              type: string
              description: always, when_in_use, denied, restricted or not_determined.
            location_enabled:
              type: boolean
            pending_fixes:
              type: integer
              minimum: 0
            sync_errors:
              type: integer
              minimum: 0
            log_rows:
              type: integer
              minimum: 0
            last_error:
              type: string
              maxLength: 256
            battery_percent:
              type: integer
              minimum: 0
              maximum: 100
            is_charging:
              type: boolean
            power_save_mode:
              type: boolean
        install_id:
          type: string
          description: Opaque SDK-generated identifier. Do not type it as a UUID.
        last_seen:
          description: When the device last uploaded a location point.
          oneOf:
            - $ref: "#/components/schemas/Timestamp"
            - type: "null"
        model:
          type: [string, "null"]
        platform:
          type: [string, "null"]
          examples: [android]
        reported_at:
          description: When the device last reported its state.
          oneOf:
            - $ref: "#/components/schemas/Timestamp"
            - type: "null"
        sdk_version:
          type: [string, "null"]
        user_id:
          type: [string, "null"]
          description: |
            The user id on the device's newest admitted point, exactly as your app set it; null
            when that point is anonymous, when the device has no admitted point, or when that point
            is no longer stored (aged out or erased) — it does not fall back to an older point. A
            newer point the admission filters rejected (mock, low accuracy, implausible speed) does
            not change it, and a later-arriving point that is older than the one in force never
            does. Among points at the same instant, the byte-smallest id wins, and an id wins over
            none. Any key with devices:read sees it.
          examples: [customer-42]
    DevicesPage:
      type: object
      required: [devices, next_cursor]
      properties:
        devices:
          type: array
          items:
            $ref: "#/components/schemas/Device"
        next_cursor:
          type: [string, "null"]
          description: The next page's cursor (prefix `dc1_`), or null when the walk is complete.
          maxLength: 256
    CommandWindowTimestamp:
      type: string
      description: Exactly YYYY-MM-DDTHH:MM:SS.mmmZ.
      pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$'
    CommandRequest:
      type: object
      description: At most 16 KiB; a larger body is a 400 `invalid_body`.
      additionalProperties: false
      required: [type]
      properties:
        type:
          type: string
          enum: [flush, upload_logs]
        params:
          type: object
          additionalProperties: false
          description: flush takes none ({} or absent). upload_logs takes optional since and until (inclusive), since not after until.
          properties:
            since:
              $ref: "#/components/schemas/CommandWindowTimestamp"
            until:
              $ref: "#/components/schemas/CommandWindowTimestamp"
        ttl_seconds:
          type: integer
          minimum: 60
          maximum: 604800
          default: 3600
          description: How long the command waits for the device.
    Command:
      type: object
      required: [expires_at, id, install_id, params, type]
      properties:
        expires_at:
          $ref: "#/components/schemas/Timestamp"
        id:
          type: string
          format: uuid
        install_id:
          type: string
        params:
          type: object
          description: As sent; {} when none was sent.
        type:
          type: string
          enum: [flush, upload_logs]
    LatLon:
      type: object
      required: [latitude, longitude]
      properties:
        latitude:
          type: number
        longitude:
          type: number
    Trip:
      type: object
      description: Ignore unknown members and unknown end_reason and mode values. No project_id.
      required: [distance_m, duration_seconds, id, install_id, last_point_at, mode, mode_counts, point_count, revision, settings_revision, start, started_at, status]
      properties:
        distance_m:
          type: number
          description: Path length over the trip's points, metres. Not rounded.
        duration_seconds:
          type: integer
          minimum: 0
        end:
          $ref: "#/components/schemas/LatLon"
        end_reason:
          type: string
          description: >-
            Closed trips only. session_change means the app stopped and restarted
            tracking. tracking_stopped means the device reported that tracking stopped
            (the app called stop()), which closes the trip at once. silence means the
            install had no contact for finality_timeout_seconds and the server closed the
            trip. Ignore values you don't know. tracking_stopped and silence are added in the
            next backend release.
          enum: [stop, gap, project_change, identity_change, session_change, tracking_stopped, silence]
        ended_at:
          $ref: "#/components/schemas/Timestamp"
        id:
          type: string
          format: uuid
          description: Deterministic (UUID version 8).
        install_id:
          type: string
        last_point_at:
          $ref: "#/components/schemas/Timestamp"
        mode:
          type: string
          description: The moving mode with the most points; ties go to the faster mode. Never still.
          enum: [driving, cycling, running, walking, unknown]
        mode_counts:
          type: object
          description: Points per mode; zero counts are omitted; the counts sum to point_count.
          additionalProperties:
            type: integer
            minimum: 1
        point_count:
          type: integer
          minimum: 3
        revision:
          type: integer
          minimum: 1
          description: 1 when the trip first appears, +1 on every change of its points, end, status or end_reason.
        settings_revision:
          type: integer
          description: The remote-config revision whose trip settings cut this trip.
        start:
          $ref: "#/components/schemas/LatLon"
        started_at:
          $ref: "#/components/schemas/Timestamp"
        status:
          type: string
          description: >-
            open while the trip may still grow; stalled when the install has gone quiet
            (no contact for silence_timeout_seconds, or presence declared it unreachable),
            and back to open when new evidence arrives; closed once, for good. stalled is added
            in the next backend release.
          enum: [open, stalled, closed]
        user_id:
          type: string
          description: Present when the trip's points carried a user id.
      example:
        distance_m: 5234.81
        duration_seconds: 1122
        end:
          latitude: 12.9352
          longitude: 77.6245
        end_reason: stop
        ended_at: "2026-10-07T09:18:42.000Z"
        id: 5b0d3c6e-2f1a-8c4d-9e7f-0a1b2c3d4e5f
        install_id: 2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50
        last_point_at: "2026-10-07T09:18:42.000Z"
        mode: driving
        mode_counts:
          driving: 41
          still: 3
          walking: 2
        point_count: 46
        revision: 2
        settings_revision: 7
        start:
          latitude: 12.9716
          longitude: 77.5946
        started_at: "2026-10-07T09:00:00.000Z"
        status: closed
    TripsPage:
      type: object
      required: [next_cursor, trips]
      properties:
        next_cursor:
          type: [string, "null"]
          description: The next page's cursor (prefix `tr1_`), or null when the walk is complete.
          maxLength: 256
        trips:
          type: array
          items:
            $ref: "#/components/schemas/Trip"
    TripPointsPage:
      type: object
      required: [next_cursor, points]
      properties:
        next_cursor:
          type: [string, "null"]
          description: The next page's cursor (prefix `tr1_`, bound to the trip), or null when the walk is complete.
          maxLength: 256
        points:
          type: array
          items:
            $ref: "#/components/schemas/LocationPoint"
    Circle:
      type: object
      required: [type, center, radius_meters]
      properties:
        type:
          type: string
          const: circle
        center:
          type: object
          required: [latitude, longitude]
          properties:
            latitude:
              type: number
              minimum: -90
              maximum: 90
            longitude:
              type: number
              minimum: -180
              maximum: 180
        radius_meters:
          type: number
          exclusiveMinimum: 0
    Polygon:
      type: object
      description: GeoJSON Polygon coordinates, [longitude, latitude]; outer ring first, then holes. Stored as a one-part multipolygon.
      required: [type, coordinates]
      properties:
        type:
          type: string
          const: polygon
        coordinates:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Ring"
    MultiPolygon:
      type: object
      description: GeoJSON MultiPolygon coordinates, [longitude, latitude]. Parts must not overlap.
      required: [type, coordinates]
      properties:
        type:
          type: string
          const: multipolygon
        coordinates:
          type: array
          minItems: 1
          items:
            type: array
            minItems: 1
            items:
              $ref: "#/components/schemas/Ring"
    Ring:
      type: array
      description: A linear ring of [longitude, latitude] positions, at least 3 distinct. Closed by the server if open.
      minItems: 3
      items:
        type: array
        minItems: 2
        maxItems: 2
        items:
          type: number
    GeometryInput:
      description: An authoring shape. Invalid geometry is refused, never repaired.
      oneOf:
        - $ref: "#/components/schemas/Circle"
        - $ref: "#/components/schemas/Polygon"
        - $ref: "#/components/schemas/MultiPolygon"
      discriminator:
        propertyName: type
        mapping:
          circle: "#/components/schemas/Circle"
          polygon: "#/components/schemas/Polygon"
          multipolygon: "#/components/schemas/MultiPolygon"
    Geometry:
      description: The stored, normalized geometry - a circle as sent, or a multipolygon (rings closed, duplicates collapsed, outer rings counter-clockwise, holes clockwise).
      oneOf:
        - $ref: "#/components/schemas/Circle"
        - $ref: "#/components/schemas/MultiPolygon"
      discriminator:
        propertyName: type
        mapping:
          circle: "#/components/schemas/Circle"
          multipolygon: "#/components/schemas/MultiPolygon"
    NotificationContent:
      type: object
      required: [title, body]
      properties:
        title:
          type: string
          maxLength: 100
        body:
          type: string
          maxLength: 500
        importance:
          type: string
          enum: [high, default]
        deep_link:
          type: string
          maxLength: 2048
        data:
          type: object
          description: At most 10 entries and 2048 bytes of keys and values.
          maxProperties: 10
          additionalProperties:
            type: string
    Notification:
      type: object
      description: At least one of on_enter (needs notify_on_entry) and on_exit (needs notify_on_exit).
      required: [delivery]
      properties:
        delivery:
          type: string
          enum: [local, cloud]
        on_enter:
          $ref: "#/components/schemas/NotificationContent"
        on_exit:
          $ref: "#/components/schemas/NotificationContent"
    Geofence:
      type: object
      required: [created_at, geometry, id, name, notify_on_entry, notify_on_exit, updated_at]
      properties:
        created_at:
          $ref: "#/components/schemas/Timestamp"
        geometry:
          $ref: "#/components/schemas/Geometry"
        id:
          type: string
          format: uuid
        name:
          type: string
        notification:
          $ref: "#/components/schemas/Notification"
        notify_on_entry:
          type: boolean
        notify_on_exit:
          type: boolean
        on_unreachable:
          type: string
          enum: ["none", "exit"]
          description: What the server does when presence declares a device confirmed inside this fence unreachable (geofence-transitions-v1). none marks the device's visit unverified and sends nothing; exit sends geofence.exit with evidence unreachable and no location. Always present once the region has the next backend release. Added in the next backend release.
        pass_through:
          type: string
          enum: ["off", "on"]
          description: Whether two consecutive confidently-outside points whose segment crosses the fence produce an enter and an exit with evidence interpolated (geofence-transitions-v1). Always present once the region has the next backend release. Added in the next backend release.
        updated_at:
          $ref: "#/components/schemas/Timestamp"
    GeofenceEnvelope:
      type: object
      required: [geofence]
      properties:
        geofence:
          $ref: "#/components/schemas/Geofence"
    GeofencesPage:
      type: object
      required: [geofences, next_cursor]
      properties:
        geofences:
          type: array
          items:
            $ref: "#/components/schemas/Geofence"
        next_cursor:
          type: [string, "null"]
          description: The next page's cursor (prefix `gf1_`), or null when the walk is complete.
          maxLength: 256
    GeofenceInput:
      type: object
      additionalProperties: false
      required: [name, geometry, notify_on_entry, notify_on_exit]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: 1 to 200 bytes (maxLength counts characters; the server counts UTF-8 bytes), not only whitespace, no control characters.
        geometry:
          $ref: "#/components/schemas/GeometryInput"
        notify_on_entry:
          type: boolean
        notify_on_exit:
          type: boolean
        notification:
          description: Absent or null means none. On PUT, absent clears it.
          anyOf:
            - $ref: "#/components/schemas/Notification"
            - type: "null"
        pass_through:
          type: [string, "null"]
          enum: ["off", "on", null]
          default: "off"
          description: Absent or null means off. On PUT, absent resets it to off. Any other value is refused with 400 invalid_body. Added in the next backend release; until then the member itself is refused with 400 invalid_body.
        on_unreachable:
          type: [string, "null"]
          enum: ["none", "exit", null]
          default: "none"
          description: Absent or null means none. On PUT, absent resets it to none. Any other value is refused with 400 invalid_body. Added in the next backend release; until then the member itself is refused with 400 invalid_body.
    TrackingSettings:
      type: object
      additionalProperties: false
      properties:
        min_time_between_locations_seconds:
          type: integer
          minimum: 1
          maximum: 86400
          default: 30
        min_distance_between_locations_meters:
          type: integer
          minimum: 0
          maximum: 10000
          default: 100
        accuracy_mode:
          type: string
          enum: [high, balanced, low]
          default: balanced
        when_stationary:
          type: string
          enum: [pause, reduce, keep]
          default: pause
        stationary_radius_meters:
          type: integer
          minimum: 5
          maximum: 10000
          default: 5
        detect_activity:
          type: boolean
          default: false
        heartbeat_interval_seconds:
          type: integer
          description: 0 (off), or 60 to 86400.
          oneOf:
            - const: 0
            - minimum: 60
              maximum: 86400
          default: 0
        max_queue_size:
          type: integer
          minimum: 1000
          maximum: 500000
          default: 100000
    SyncSettings:
      type: object
      additionalProperties: false
      properties:
        interval_seconds:
          type: integer
          minimum: 30
          maximum: 86400
          default: 300
        batch_size:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
        sync_threshold:
          type: integer
          minimum: 0
          maximum: 10000
          default: 0
        unmetered_only:
          type: boolean
          default: false
        charging_only:
          type: boolean
          default: false
    PrivacySettings:
      type: object
      additionalProperties: false
      properties:
        precision_truncate_decimals:
          type: integer
          minimum: 1
          maximum: 6
    DiagnosticsSettings:
      type: object
      additionalProperties: false
      properties:
        log_level:
          type: string
          enum: ["off", error, warn, info, debug]
    FeatureFlags:
      type: object
      description: >-
        Up to 64 flags; keys match [a-z0-9_]{1,64}. presence_probe is reserved for the
        server: a PUT that carries it, with any value, is 400 `invalid_config:
        features.presence_probe`, and GET never shows it. Devices receive it as true while
        the optional push probe is on for the project. The reservation and the probe, switched
        off, arrive with the next backend release; the probe needs the region to enable it and
        an SDK release after 0.5.0.
      maxProperties: 64
      propertyNames:
        pattern: '^[a-z0-9_]{1,64}$'
      additionalProperties:
        type: boolean
    TripSettings:
      type: object
      additionalProperties: false
      properties:
        stop_radius_meters:
          type: integer
          minimum: 25
          maximum: 1000
          default: 100
        stop_duration_seconds:
          type: integer
          minimum: 60
          maximum: 7200
          default: 300
        min_distance_meters:
          type: integer
          minimum: 50
          maximum: 100000
          default: 250
        min_duration_seconds:
          type: integer
          minimum: 0
          maximum: 86400
          default: 120
        max_gap_seconds:
          type: integer
          minimum: 60
          maximum: 86400
          default: 600
        max_accuracy_meters:
          type: integer
          minimum: 10
          maximum: 10000
          default: 100
        silence_timeout_seconds:
          type: [integer, "null"]
          description: >-
            How long an open trip's install may have no contact before the trip is marked
            stalled (trip.stalled). 0 turns off only this silence stall: a trip still stalls
            when presence declares its install unreachable. Otherwise 60 to 86400. Absent or
            null means the effective max_gap_seconds; GET shows the member once it is set.
            Added in the next backend release.
          anyOf:
            - type: "null"
            - const: 0
            - minimum: 60
              maximum: 86400
        finality_timeout_seconds:
          type: integer
          minimum: 3600
          maximum: 604800
          default: 86400
          description: How long an open or stalled trip's install may have no contact before the server closes the trip with end_reason silence (trip.ended). Added in the next backend release.
    PresenceSettings:
      type: object
      additionalProperties: false
      description: Server-read; the SDKs ignore it. Added in the next backend release.
      properties:
        rest_limit_seconds:
          type: integer
          minimum: 3600
          maximum: 604800
          default: 43200
          description: How long a resting device may be silent before the server declares it unreachable (device.unreachable, reason rest_limit).
    FilterSettings:
      type: object
      additionalProperties: false
      properties:
        accuracy_enabled:
          type: boolean
          default: true
        max_accuracy_meters:
          type: number
          minimum: 25
          maximum: 10000
          default: 200
        mock_enabled:
          type: boolean
          default: true
        teleport_enabled:
          type: boolean
          default: true
        max_speed_mps:
          type: number
          minimum: 30
          maximum: 1000
          default: 350
    ConfigDocument:
      type: object
      description: Every section fully materialized. An absent knob (privacy, diagnostics, poll_interval_seconds) is unset and the device uses its own default.
      required: [diagnostics, features, filters, privacy, revision, sync, tracking, trips]
      properties:
        diagnostics:
          $ref: "#/components/schemas/DiagnosticsSettings"
        features:
          $ref: "#/components/schemas/FeatureFlags"
        filters:
          $ref: "#/components/schemas/FilterSettings"
        poll_interval_seconds:
          type: integer
          minimum: 60
          maximum: 86400
        presence:
          $ref: "#/components/schemas/PresenceSettings"
        privacy:
          $ref: "#/components/schemas/PrivacySettings"
        revision:
          type: integer
          description: Set by the server; moves only on a real change.
        sync:
          $ref: "#/components/schemas/SyncSettings"
        tracking:
          $ref: "#/components/schemas/TrackingSettings"
        trips:
          $ref: "#/components/schemas/TripSettings"
    ConfigDocumentInput:
      type: object
      description: |
        Every member optional. tracking, sync, privacy, features, diagnostics and
        poll_interval_seconds are reset to defaults when absent or null; trips, presence and
        filters are kept when absent and reset when null. Never send revision, schema_version,
        service_state or license_jws. At most 65536 bytes.
      additionalProperties: false
      properties:
        diagnostics:
          anyOf:
            - $ref: "#/components/schemas/DiagnosticsSettings"
            - type: "null"
        features:
          anyOf:
            - $ref: "#/components/schemas/FeatureFlags"
            - type: "null"
        filters:
          anyOf:
            - $ref: "#/components/schemas/FilterSettings"
            - type: "null"
        poll_interval_seconds:
          type: [integer, "null"]
          minimum: 60
          maximum: 86400
        presence:
          anyOf:
            - $ref: "#/components/schemas/PresenceSettings"
            - type: "null"
        privacy:
          anyOf:
            - $ref: "#/components/schemas/PrivacySettings"
            - type: "null"
        sync:
          anyOf:
            - $ref: "#/components/schemas/SyncSettings"
            - type: "null"
        tracking:
          anyOf:
            - $ref: "#/components/schemas/TrackingSettings"
            - type: "null"
        trips:
          anyOf:
            - $ref: "#/components/schemas/TripSettings"
            - type: "null"
    EventType:
      type: string
      description: >-
        An event type a webhook endpoint can receive; webhook.ping cannot be named.
        trip.stalled, device.unreachable and device.reachable ship with the next backend
        release: until a region has it, naming one of them is 400 invalid_event_types.
      enum: [billing.usage_threshold, device.reachable, device.unreachable, geofence.dwell, geofence.enter, geofence.exit, trip.ended, trip.stalled, trip.started]
    Webhook:
      type: object
      description: All eight members are always present. The secret is never part of it.
      required: [auto_disabled_at, created_at, endpoint_url, event_types, id, project_id, status, updated_at]
      properties:
        auto_disabled_at:
          description: When Beekon stopped delivering because the endpoint kept failing; null when it has not (or is not yet active in the region).
          oneOf:
            - $ref: "#/components/schemas/Timestamp"
            - type: "null"
        created_at:
          $ref: "#/components/schemas/Timestamp"
        endpoint_url:
          type: string
          format: uri
        event_types:
          type: [array, "null"]
          description: Sorted, de-duplicated. null means every type.
          items:
            $ref: "#/components/schemas/EventType"
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [active, disabled]
        updated_at:
          $ref: "#/components/schemas/Timestamp"
    WebhookReduced:
      type: object
      description: What a key without webhooks:read gets from a write.
      additionalProperties: false
      required: [id, status, updated_at]
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [active, disabled]
        updated_at:
          $ref: "#/components/schemas/Timestamp"
    WebhookForWriter:
      description: The full object for a key holding webhooks:read, else the reduced one.
      anyOf:
        - $ref: "#/components/schemas/Webhook"
        - $ref: "#/components/schemas/WebhookReduced"
    WebhookWithSecret:
      type: object
      required: [secret, webhook]
      properties:
        secret:
          type: string
          description: The signing secret (whsec_...). Shown only here; store it now.
        webhook:
          $ref: "#/components/schemas/WebhookForWriter"
    WebhooksPage:
      type: object
      required: [next_cursor, webhooks]
      properties:
        next_cursor:
          type: [string, "null"]
          description: The next page's cursor (prefix `wh1_`), or null when the walk is complete.
          maxLength: 256
        webhooks:
          type: array
          items:
            $ref: "#/components/schemas/Webhook"
    WebhookCreate:
      type: object
      additionalProperties: false
      required: [endpoint_url]
      properties:
        endpoint_url:
          type: string
          maxLength: 2048
          description: https, a public DNS name (no IP literal, no internal suffix, not getbeekon.com, run.app, cloudfunctions.net or appspot.com), port 443 or 1024-65535, no credentials or fragment.
        event_types:
          type: [array, "null"]
          description: A non-empty list; absent or null means every type.
          minItems: 1
          items:
            $ref: "#/components/schemas/EventType"
    WebhookPatch:
      type: object
      additionalProperties: false
      minProperties: 1
      description: At least one member. A null endpoint_url or status is the same as leaving it out; a null event_types sets every type.
      properties:
        endpoint_url:
          type: [string, "null"]
          maxLength: 2048
        event_types:
          type: [array, "null"]
          minItems: 1
          items:
            $ref: "#/components/schemas/EventType"
        status:
          type: [string, "null"]
          enum: [active, disabled, null]
    RotateSecretRequest:
      type: object
      additionalProperties: false
      properties:
        expire_previous:
          type: boolean
          default: false
          description: true drops the previous secret at once; false keeps it until the next rotation.
    IngestBatch:
      type: object
      description: One upload in the SDK's upload format (schema_version 1). Members not listed are ignored.
      required: [schema_version, device]
      properties:
        schema_version:
          type: integer
          const: 1
        batch_id:
          type: string
          description: Tracing only; never a deduplication key.
        session_id:
          type: string
          maxLength: 128
          description: One tracking run. A change of session ends a trip. No NUL character.
        sent_at:
          $ref: "#/components/schemas/Timestamp"
        device:
          type: object
          required: [install_id]
          properties:
            install_id:
              type: string
              minLength: 1
              maxLength: 128
              description: The device the points belong to. Opaque, not blank, no NUL character.
            platform:
              type: string
            sdk_version:
              type: string
            model:
              type: string
        extras:
          type: object
          description: Your string-to-string map, copied onto every point of the batch. At most 4 KiB encoded (over it is `400 invalid batch`). Its encoded size times the batch's number of points must be at most 256 KiB (over it is `413 batch exceeds the extras size bound`).
          additionalProperties:
            type: string
        segments:
          type: array
          items:
            $ref: "#/components/schemas/IngestSegment"
    IngestSegment:
      type: object
      properties:
        user_id:
          type: string
          maxLength: 256
          description: The user the segment's points belong to. UTF-8, no control characters. Absent means anonymous.
        locations:
          type: array
          items:
            $ref: "#/components/schemas/IngestLocation"
        geofence_events:
          type: array
          description: Geofence crossings the device recorded. Stored as provenance only, deduplicated on `id`, and never readable through the API or sent as events or webhooks; `geofence.*` events come only from the server's own evaluation of stored points. They do not count towards the 1000-point cap.
          items:
            $ref: "#/components/schemas/IngestGeofenceEvent"
    IngestGeofenceEvent:
      type: object
      required: [id, timestamp]
      properties:
        id:
          type: string
          format: uuid
          description: The event id and deduplication key. Any UUID version. Not a UUID is `400 invalid batch`.
        geofence_id:
          type: string
          description: The geofence that fired. Over 256 bytes, or containing a NUL character, the event is skipped (not stored) and the batch still answers 200.
        type:
          type: string
          description: enter or exit. Any other value is skipped, and the batch still answers 200.
          examples: ["exit"]
        timestamp:
          type: string
          format: date-time
          description: When the crossing occurred, on the device clock. Missing or not RFC 3339 is `400 invalid batch`. An event outside the deployment's sanity window is dropped, and the batch still answers 200.
          examples: ["2026-10-07T09:05:00.000Z"]
    IngestLocation:
      type: object
      required: [id, timestamp, latitude, longitude]
      properties:
        id:
          type: string
          format: uuid
          description: The point id and deduplication key. Any UUID version.
        timestamp:
          type: string
          format: date-time
          description: When the point was recorded. Any RFC 3339 offset and fractional precision is accepted, and stored in UTC. A point outside the deployment's sanity window is quarantined (not stored) and the batch still answers 200.
          examples: ["2026-10-07T09:00:00.000Z"]
        trigger:
          type: string
          description: interval, motion, check_in, geofence or manual.
        motion:
          type: string
          description: moving, stationary or unknown.
        is_mock:
          type: boolean
        latitude:
          type: number
          minimum: -90
          maximum: 90
        longitude:
          type: number
          minimum: -180
          maximum: 180
        accuracy:
          type: number
          minimum: 0
          description: Horizontal accuracy, metres. Negative is `400 invalid batch`.
        speed:
          type: number
        bearing:
          type: number
        altitude:
          type: number
        activity:
          type: string
        quality:
          type: string
        battery_percent:
          type: integer
        is_charging:
          type: boolean
        power_save_mode:
          type: boolean
    PingResult:
      type: object
      required: [delivered, delivery_id, status_code]
      properties:
        delivered:
          type: boolean
          description: true when the endpoint answered 2xx.
        delivery_id:
          type: string
          format: uuid
          description: The ping's Beekon-Delivery header.
        status_code:
          type: [integer, "null"]
          description: The endpoint's HTTP status, or null when it gave no response (the answer then comes 10 seconds after the ping started). On a self-hosted server with BEEKON_WEBHOOK_ALLOW_PRIVATE, a ping to an address only that setting allows is also reported as null (delivered false), even when the endpoint answered.
