Lightbug Documentation

OpenAPI definition

References are expanded below, except recursive definitions and references with sibling fields. Documentation overrides are included. Full original OpenAPI spec (JSON).

View endpoint OpenAPI definition

yaml

info:
  title: Lightbug API
  version: '2'
externalDocs:
  description: ''
  url: ''
openapi: 3.1.0
servers:
  - url: https://api.lightbug.cloud/v2
security:
  - ApiKeyAuth: []
tags: []
paths:
  /devices:
    get:
      parameters:
        - description: Limit for pagination, default 10, max 10000
          in: query
          name: _limit
          schema:
            type: integer
        - description: Page for pagination
          in: query
          name: _page
          schema:
            type: integer
        - description: Sort by this field
          in: query
          name: _sort
          schema:
            type: string
        - description: Sort in this direction (asc, desc)
          in: query
          name: _direction
          schema:
            type: string
        - description: Filter by name (prefix search enabled by appending * to the end of the string)
          in: query
          name: name
          schema:
            description: Filter by name (prefix search enabled by appending * to the end of the string)
            example: Hello *
            form: name
            type: string
        - description: Tag to search for in fully qualified key:value format. Example device_type:truck. Partial searches with wildcards may be used, eg. device_type:* or device_type:veh_*
          in: query
          name: tag
          schema:
            description: Tag to search for in fully qualified key:value format. Example device_type:truck. Partial searches with wildcards may be used, eg. device_type:* or device_type:veh_*
            example: device_type:truck
            form: tag
            type: string
        - description: Filter by current firmware version
          in: query
          name: config.currentFW
          schema:
            description: Filter by current firmware version
            form: config.currentFW
            type: string
        - description: 'Include additional data. Enums: config,users,knownDevices,subscription,subscription.plan,reseller,resellerPlan,qcEvents'
          in: query
          name: _include
          schema:
            description: 'Include additional data. Enums: config,users,knownDevices,subscription,subscription.plan,reseller,resellerPlan,qcEvents'
            form: _include
            items:
              type: string
            type: array
            uniqueItems: false
        - description: Filter by active status
          in: query
          name: active
          schema:
            description: Filter by active status
            example: true
            form: active
            type: boolean
        - description: Filter by serial (prefix search enabled by appending * to the end of the string) (comma separated for multiple values)
          in: query
          name: serial
          schema:
            description: Filter by serial (prefix search enabled by appending * to the end of the string) (comma separated for multiple values)
            example: '12001234'
            form: serial
            type: string
        - description: Filter by IMEI (exact match) (comma separated for multiple values)
          in: query
          name: imei
          schema:
            description: Filter by IMEI (exact match) (comma separated for multiple values)
            form: imei
            type: string
        - description: Filter by iccid (exact match) (comma separated for multiple values)
          in: query
          name: iccid
          schema:
            description: Filter by iccid (exact match) (comma separated for multiple values)
            form: iccid
            type: string
        - description: Filter by user username (search enabled by surrounding with *, comma separated for multiple values)
          in: query
          name: user
          schema:
            description: Filter by user username (search enabled by surrounding with *, comma separated for multiple values)
            example: '*user1*,*user2*'
            form: user
            type: string
        - description: Filter by reseller name (exact match)
          in: query
          name: reseller
          schema:
            description: Filter by reseller name (exact match)
            example: Name*
            form: reseller
            type: string
        - description: Only show devices connected since this date (currently an alpha filter)
          in: query
          name: _connectedSince
          schema:
            description: Only show devices connected since this date (currently an alpha filter)
            form: _connectedSince
            type: string
        - description: Filter by ID (comma separated for multiple values)
          in: query
          name: id
          schema:
            description: Filter by ID (comma separated for multiple values)
            form: id
            type: string
        - description: Filter by type (comma separated for multiple values)
          in: query
          name: type
          schema:
            description: Filter by type (comma separated for multiple values)
            example: ZeroN
            form: type
            type: string
        - description: Optionally provide parameters as a JSON object in this header. X-Query values take precedence over query parameters for any overlapping fields.
          example: '{"id":"1,2,3"}'
          in: header
          name: X-Query
          schema:
            type: string
      responses:

'200':

yaml

          content:
            application/json:
              schema:
                properties:
                  data:
                    description: Paginated data
                    items:
                      properties:
                        active:
                          type: boolean
                        batteryPct:
                          type: integer
                        batteryType:
                          type: string
                        batteryVoltage:
                          type: number
                        btMacAddress:
                          description: Bluetooth MAC Address
                          type: string
                        btPasskey:
                          type: integer
                        color:
                          type: string
                        config:
                          description: (optional) Configuration
                          properties:
                            alertAction:
                              description: |-
                                What to do when the button is pressed or the unit is dropped. Options are:
                                'available' (stay registered on the mobile network),
                                'nothing' (one transmission) and
                                'lockOn' (keep transmitting at 'interval' until instructed otherwise
                              type: string
                            behavior:
                              description: Char Bitfield with various flags. Advanced use only.
                              type: integer
                            command:
                              description: Internal use. Sends command to device on next connection
                              type: integer
                            currentFW:
                              description: Current firmware version
                              type: integer
                            debounce:
                              description: |-
                                Movement sensitivity on a scale of 1 to 10, with 1 being the most sensitive.
                                It is correlated to the number of consecutive milliseconds the acceleration needs to exceed the movementSensitivity threshold
                              type: integer
                            flashTryCount:
                              description: Internal use. Set to 0 when changing otaFW
                              type: integer
                            forceFw:
                              description: |-
                                Internal use only
                                Used with otaFW. Set to true to force the unit to upgrade on next connection (rather than waiting for a sleep connection)
                              type: boolean
                            fwChannel:
                              description: The firmware channel to use for OTA updates. If null, the unit will use the default channel.
                              type: string
                            gpsCheckInterval:
                              description: If a safe-zone is used, how often to check the wifi & gps to see if its still inside it (only applies when motion is detected)
                              type: integer
                            gpsStabilize:
                              description: |-
                                How long to let the GPS stabilise in seconds once a lock is achieved before sending the position.
                                Higher values may increase accuracy.
                              type: integer
                            gpsTimeout:
                              description: How long to let the GPS searches for a lock in seconds before giving up. Max 255s.
                              type: integer
                            homeWifiNetwork:
                              description: WiFi network name to use as a Safe-zone. When this network is visible, stay asleep
                              type: string
                            interval:
                              description: The wake mode interval in seconds. The unit will connect to the server this often when awake.
                              type: integer
                            modeControl:
                              description: Char Bitfield with various flags. Advanced use only.
                              type: integer
                            modeControl2:
                              description: Char Bitfield with various flags. Advanced use only. FW >= 69.
                              type: integer
                            modified:
                              description: Non null dates indicate the configuration will be pushed to the device when it next connects
                            movementSensitivity:
                              description: |-
                                A secondary debounce value. Typically this value is lower or equal to debounce, representing increased
                                sensitivity to movement once the device is already moving.
                              type: integer
                            movementSensitivityOld:
                              description: |-
                                Deprecated. See debounce.
                                movementSensitivity threshold in terms of units of gravity. We used to adjust it, but a better way of doing it was the amount of times over that threshold (that what debounce is)
                                Should always be 1, which means... debounce when already moving
                              type: integer
                            otaFW:
                              description: Pending Firmware version. If non null, the unit will be told to upgrade to this version when it next transmits in sleep mode.
                              type: integer
                            packing:
                              description: |-
                                The number of GPS points to send with each transmission.
                                A packing setting of 3 with an 'interval' of 60s will result in points recorded approximately every 20s, but they will only be sent together.
                              type: integer
                            reasonsToWake:
                              properties:
                                bluetooth:
                                  type: boolean
                                drop:
                                  type: boolean
                                geofence:
                                  type: boolean
                                move:
                                  type: boolean
                              type: object
                            receivedAt:
                              description: The last time the settings were sent to the device
                              type: string
                            reset:
                              description: |-
                                Non NULL values cause unit to restart on next connection
                                0 = Normal reboot
                                1 = Clear settings cache and restart
                                2 = Clear cache and bluetooth connection data, then restart
                              type: integer
                            sleepInterval:
                              description: Sleep mode interval in seconds. The unit will try to connect this often to the server when asleep
                              type: integer
                            stopTimeout:
                              description: The total amount of time in seconds the unit has to be stationary for before deeming the journey over and switching to sleep mode
                              type: integer
                            timed:
                              description: 'Timed update settings. Must be array of objects matching [{hh: number, mm: number, day: number, action: number}, ...] format'
                              type: string
                            tolerancePercentage:
                              description: Power budget in mAh per location update. Default 10, do not set lower than 5.
                              type: integer
                            transmitTimeout:
                              description: |-
                                When the unit first wakes up from sleep, how long to wait before trying to transmit in multiples of 30 seconds.
                                0 = instant, 1 = 30s, 2 = 60s...
                                Useful to avoid detection or draining battery inside shielded buildings.
                              type: integer
                            updateAvailability:
                              description: The update availability.
                              type: integer
                            wakeAction:
                              description: |-
                                Internal Use Only.
                                What to do when the unit wakes up (ie is moved and not in a safe-zone).
                                Options are 'available' (lost and found), and 'normal' (tracking)
                              type: string
                          type: object
                        currentMode:
                          description: Indicates last known device state. 0 = awake, 1 = sleep, 6 = flight mode
                          type: integer
                        expires:
                          type: string
                        firstSeen:
                          type: string
                        iccid:
                          description: Integrated Circuit Card Identification Number
                          type: string
                        id:
                          type: integer
                        imei:
                          type: string
                        imsi:
                          description: International Mobile Subscriber Identity (A unique number associated with every GSM mobile phone subscriber, which is maintained on a SIM)
                        knownDevices:
                          description: (optional) Bluetooth MAC addresses of other devices known to this device
                          items:
                            type: string
                          type: array
                          uniqueItems: false
                        lastConnection:
                          type: string
                        meta:
                          additionalProperties: {}
                          type: object
                        name:
                          type: string
                        onoWhitelistId:
                          type: integer
                        ownerId:
                          description: ID of the user which owns this device
                          type: integer
                        qcEvents:
                          additionalProperties:
                            properties:
                              count:
                                type: integer
                              createdAt:
                                type: string
                              updatedAt:
                                type: string
                            type: object
                          description: (optional) QC Events keyed by QC code
                          type: object
                        reseller:
                          description: (optional) Reseller
                          properties:
                            created:
                              type: string
                            email:
                              type: string
                            id:
                              type: integer
                            name:
                              type: string
                            plans:
                              description: BillingTerm     int32           `json:"billingTerm"`
                              items:
                                description: (optional) Reseller Plan
                                properties:
                                  archived:
                                    type: integer
                                  displayName:
                                    type: string
                                  features:
                                    type: string
                                  id:
                                    type: integer
                                  name:
                                    type: string
                                  onoWhitelistId:
                                    type: integer
                                  resellerId:
                                    type: integer
                                  sleepLimit:
                                    type: integer
                                  term:
                                    type: integer
                                  wakeLimit:
                                    type: integer
                                type: object
                              type: array
                              uniqueItems: false
                            stripeAccountId:
                              type: string
                            userId:
                              type: integer
                            xeroContactId:
                              type: string
                          type: object
                        resellerId:
                          type: integer
                        resellerPlan:
                          description: (optional) Reseller Plan
                          properties:
                            archived:
                              type: integer
                            displayName:
                              type: string
                            features:
                              type: string
                            id:
                              type: integer
                            name:
                              type: string
                            onoWhitelistId:
                              type: integer
                            resellerId:
                              type: integer
                            sleepLimit:
                              type: integer
                            term:
                              type: integer
                            wakeLimit:
                              type: integer
                          type: object
                        resellerPlanId:
                          type: integer
                        serial:
                          type: string
                        siloId: {}
                        stripeSubscription: {}
                        subscription:
                          description: (optional) Current subscription
                          properties:
                            _stripeSubscriptionId:
                              description: (legacy) Stripe Subscription ID for per device subscriptions
                              type: string
                            created:
                              type: string
                            deviceId:
                              type: integer
                            expires:
                              type: string
                            id:
                              type: integer
                            plan:
                              description: Details of the plan.
                              properties:
                                description:
                                  type: string
                                displayName:
                                  type: string
                                features:
                                  type: string
                                id:
                                  type: integer
                                name:
                                  type: string
                                onoWhitelistId:
                                  description: |-
                                    Connectivity *string `json:"connectivity"`
                                    Group        string  `json:"group"`
                                    ResellerID *int32 `json:"resellerId"`
                                    ResellerPlanID *int32  `json:"resellerPlanId"`
                                    Archived *int32 `json:"archived"`
                                    PlanType       string  `json:"planType"`
                                  type: integer
                                prices:
                                  properties:
                                    eur:
                                      description: 'breaks:  example:"[0,1.99],[10,1.89]"` // Array of quantity to price in EUR'
                                      items:
                                        items:
                                          type: number
                                        type: array
                                      type: array
                                      uniqueItems: false
                                    gbp:
                                      description: 'breaks:   example:"[1,2.34],[10,2.22]"` // Array of quantity to price in GBP'
                                      items:
                                        items:
                                          type: number
                                        type: array
                                      type: array
                                      uniqueItems: false
                                    tax:
                                      $ref: '#/components/schemas/ProductPricing'
                                    usd:
                                      description: 'breaks:   example:"[1,4.35],[10,4.26]"` // Array of quantity to price in USD'
                                      items:
                                        items:
                                          type: number
                                        type: array
                                      type: array
                                      uniqueItems: false
                                  type: object
                                sku:
                                  type: string
                                sleepLimit:
                                  type: integer
                                wakeLimit:
                                  description: |-
                                    Term           string  `json:"term"`
                                    Price          float64 `json:"price"`
                                    Currency       string  `json:"currency"`
                                    OwnerID        int32   `json:"ownerId"`
                                  type: integer
                              type: object
                            planId:
                              type: integer
                            userId:
                              type: integer
                          type: object
                        subscriptionType: {}
                        tags:
                          items:
                            type: string
                          type: array
                          uniqueItems: false
                        type:
                          type: string
                        users:
                          description: (optional) User IDs associated with this device
                          items:
                            properties:
                              email:
                                type: string
                              hasBillingInfo:
                                description: |-
                                  Does the user have billing info stored (a card) for potential use in automatic billing?
                                  This does not mean that there is actually an active subscription
                                type: boolean
                              id:
                                type: integer
                            type: object
                          type: array
                          uniqueItems: false
                        uwbId:
                          description: UWB Address as 32bit number (ID based on the silicon inside the device)
                      type: object
                    type: array
                    uniqueItems: false
                  limit:
                    description: Requested elements per page
                    type: integer
                  page:
                    description: Requested page number
                    type: integer
                  totalElements:
                    description: Total elements in the database for given filters
                    type: integer
                  totalPages:
                    description: Total pages of elements given limit and filters
                    type: integer
                type: object
          description: OK

'400':

yaml

          content:
            application/json:
              schema:
                properties:
                  code:
                    example: 400
                    type: integer
                  message:
                    example: status bad request
                    type: string
                type: object
          description: Bad Request

'401':

yaml

          content:
            application/json:
              schema:
                properties:
                  code:
                    example: 400
                    type: integer
                  message:
                    example: status bad request
                    type: string
                type: object
          description: Unauthorized

'429':

yaml

          content:
            application/json:
              schema:
                type: string
          description: Limit exceeded
          headers:
            X-Ratelimit-Limit:
              schema:
                type: integer
            X-Ratelimit-Remaining:
              schema:
                type: integer
            X-Ratelimit-Reset:
              schema:
                type: integer

yaml

      security:
        - ApiKeyAuth: []
      summary: Gets devices
      tags:
        - devices
      operationId: get-devices
components:
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey
      description: API Key for authentication. Retrieval from either API version login routes, or other authentication token type. See <a href='/apis/authentication'>Authentication</a> for more details.
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  schemas:
    ProductPricing:
      properties:
        eur:
          description: 'breaks:  example:"[0,1.99],[10,1.89]"` // Array of quantity to price in EUR'
          items:
            items:
              type: number
            type: array
          type: array
          uniqueItems: false
        gbp:
          description: 'breaks:   example:"[1,2.34],[10,2.22]"` // Array of quantity to price in GBP'
          items:
            items:
              type: number
            type: array
          type: array
          uniqueItems: false
        tax:
          $ref: '#/components/schemas/ProductPricing'
        usd:
          description: 'breaks:   example:"[1,4.35],[10,4.26]"` // Array of quantity to price in USD'
          items:
            items:
              type: number
            type: array
          type: array
          uniqueItems: false
      type: object

Version 2

Authentication

Access Tokens

Plans

Devices

Chasm

Geofences

Geofence Lists

Version 1

Glossary

Datapoints

Device Settings

Authentication

Devices

Device Activation

Device Configuration

Points

Readings

Gateway readings

Notifications

Geofences

Reports

RTK

Device Misc

Gets devices

Authorizations

Parameters

Header Parameters

Query Parameters

Request example

Responses

Playground

OpenAPI definition

Glossary

Datapoints

Device Settings

Gets devices​

Authorizations​

Parameters​

Header Parameters

Query Parameters

Request example

Responses​

Playground​

OpenAPI definition ​

Gets devices

Authorizations

Parameters

Responses

Playground

OpenAPI definition