Velavu API Documentation

Welcome to the Velavu API documentation. For questions or support, contact support@velavu.com.

REST API

This section describes the Velavu REST API.

Response properties with an optional type will be omitted from the response when their value is null. Use a safe accessor (e.g. dict.get('key')) to handle these cases.

Authentication

Requests are authenticated via a Bearer token in the Authorization header. The token may either be a JWT returned by the cognito user login service, or an opaque string token that is created by the /tokens API endpoint.

Pagination

Pagination is supported on endpoints that may return a large number of objects in list format. This includes:

/assets
/devices
/events/.category/asset/.asset_id
/events/.category/device/.device_id
/alerts

These endpoints all accept the query parameters limit and continuation_token. Time-based objects such as Events are always returned in reverse-chronological order. (Newest first)

Pagination Query Parameters

Parameter	Required	Description
limit	false	Maximum amount of objects to return
continuation_token	false	The continuation token returned from the previous query

Paginated responses contain custom headers named X-Continuation-Token and X-Next-Link. These headers only exist if there are more results available to return.

Pagination Response Headers

Header	Description
X-Continuation-Token	The token pointing to the next set of query results
X-Next-Link	The link you can use to query the next set of results

Assets

Asset Object

{
  "id": "2drjCI7",
  "category": "EQUIPMENT",
  "group": "Large moving object",
  "name": "Rohan's Car",
  "device_id": "j1R2W",
  "online": true,
  "notes": "This is a note",
  "profile_img_url": "https://s3.us-east-2.aws.com/image.png",
  "parent_id": "JcoL3sF2"
}

The Asset object represents a physical object or asset that is meant to be tracked. It supports pairing with a device in order to tie the device location and state to the asset.

Property	Type	Description
id	string	Unique identifier for the object
name	string	Name of the asset
category	string	High-level classification, currently restricted to 'EQUIPMENT', 'VEHICLE', or 'PERSON'
group	string	More granular filtering & sorting, this string can be anything
notes	Optional[string]	Store additional asset information
device_id	Optional[string]	ID of the device that is paired to this asset
online	Optional[bool]	`True` if the paired device is online, `False` if it offline, or `None` if the device is only registered or no device is paired with the asset
profile_img_url	Optional[string]	URL where the asset's profile picture is stored

Get All Assets

[
  {
    "id": "2drjCI7",
    "category": "EQUIPMENT",
    "group": "Large moving object",
    "name": "Rohan's Car",
    "device_id": "5kElf",
    "online": false
  },
  {
    "id": "732ewfq",
    "category": "VEHICLE",
    "group": "Car",
    "name": "Tesla Model 3"
  }
]

Returns all assets.

Request

GET api.velavu.com/assets

Query Parameters

Parameter	Required	Description
include_profile_images	false	Whether to return a URL to each asset's profile image. Defaults to false
paired	false	`true` to only return paired assets or `false` to only return unpaired assets
online	false	`true` to only return assets paired to online devices or `false` to only return assets paired to offline devices
only_registered	false	`true` to only return assets paired to registered (but not yet online) devices
category	false	Only return assets matching this category
group	false	Only return assets matching this group
name	false	Asset name to filter against. Matches any asset who's name begins with the provided string

Create a New Asset

{
  "name": "New Asset",
  "category": "VEHICLE",
  "group": "CAR"
}

{
  "id": "9nEU83F",
  "name": "New Asset",
  "category": "VEHICLE",
  "group": "CAR"
}

Creates a new asset.

Request

POST api.velavu.com/assets

Request Parameters

Parameter	Type	Required	Description
name	string	true	The asset's name
category	string	true	The asset's category, accepted values are `VEHICLE`, `EQUIPMENT`, or `PERSON`
group	string	true	The asset's type
notes	string	false	Additional notes about the asset
device_id	string	false	Pair the asset immediately to a device. This device must exist and not be currently paired to another asset

Get a Specific Asset

{
  "id": "2drjCI7",
  "category": "EQUIPMENT",
  "group": "Large moving object",
  "name": "Rohan's Car"
}

Returns all properties of the specified asset.

Request

GET api.velavu.com/assets/.asset_id

Modify a Specific Asset

{
  "name": "Focus"
}

{
  "id": "JcOLj4X",
  "category": "VEHICLE",
  "group": "Car",
  "name": "Focus"
}

Modifies one or more properties of the specified asset.

Request

PATCH api.velavu.com/assets/.asset_id

Request Parameters

Property	Type	Required	Description
name	string	false	The asset's name
category	string	false	The asset's category, accepted values are `VEHICLE`, `EQUIPMENT`, or `PERSON`
group	string	false	The asset's type
device_id	string	false	Pair the asset to a device. This device must exist and not be currently paired to another asset
notes	string	false	Additional notes about the asset

Unpair a Device from an Asset

Unpairs the device currently paired to an asset. If no device is paired, this is a no-op.

Request

POST api.velavu.com/assets/.asset_id/unpair

Delete a Specific Asset

Deletes the specified asset.

Request

DELETE api.velavu.com/assets/.asset_id

Upload a Profile Picture for an Asset

{
  "id": "2drjCI7",
  "category": "EQUIPMENT",
  "group": "Large moving object",
  "name": "Rohan's Car",
  "notes": "This is a note",
  "profile_img_url": "https://s3.us-east-2.aws.com/image.png"
}

Uploads a profile picture for an asset.

Request

PUT api.velavu.com/assets/.asset_id/profile_img

The request body should be an image binary. If the function cannot determine the image type it will return a 400 - Bad Request. Images are cropped to square and resized if larger than 1024 x 1024.

Delete a Profile Picture for an Asset

Deletes the asset's profile image.

Request

DELETE api.velavu.com/assets/.asset_id/profile_img

Asset Routes

Asset Route Object

{
  "id": "ysC9jlb",
  "asset_id": "Jcoasws",
  "timestamp": "2021-02-01T01:06:03+00:00",
  "data": {
    "avg_speed": 11.6,
    "distance": 6715,
    "max_speed": 26,
    "customer_id": "DEFAULT",
    "time_stop": "2021-02-01T01:15:44+00:00",
    "time_start": "2021-02-01T01:06:03+00:00",
    "location_stop": "A&W, 2870 Gibford Drive",
    "event_cnt": 0,
    "location_start": "770 Ridgewood Avenue, Ottawa",
    "geometry": "}{{sGnq}lM??DAH?AEAg@GiBAa@?QDAApADlA@f@NA\\K]JO@@DBv@?XBl@?DBp@LAPAJ??G?FK?"
    "annotations": [
      {
        "speed_limit": {
          "speed": 60,
          "unit": "km/h"
        },
        "events": [
          {
            "max_g": 0.66,
            "direction": "TURNING"
          }
        ],
        "index": 55,
        "speed": 18.1,
        "timestamp": "2021-02-01T01:09:04+00:00"
      }
    ]
  }
}

The Asset Route object represents a vehicle driving route. GPS trackers paired to an asset will record routes by default when they determine to be in a moving vehicle.

Property	Type	Description
id	string	Unique identifier for the object
asset_id	string	Asset associated with this route
timestamp	string	Time that driving started, same as `data.time_start`
data.time_start	string	Time that driving started
data.location_start	string	Location where driving started
data.avg_speed	number	Average route speed in m/s
data.distance	number	Total route distance in meters
data.max_speed	number	Maximum speed in m/s
data.geometry	string	Polyline-encoded geojson linestring representing the entire route
data.time_stop	Optional[string]	Time that driving ended
data.location_stop	Optional[string]	Location where driving ended
data.event_cnt	Optional[number]	Driving event count (Harsh braking, acceleration, etc.)
data.annotations	Optional[list]	Additional info about the route

Get All Routes

[
  {
    "id": "ysC9jlb",
    "asset_id": "Jcoasws",
    "timestamp": "2021-02-01T01:06:03+00:00",
    "data": {
      "avg_speed": 11.6,
      "distance": 6715,
      "max_speed": 26,
      "customer_id": "DEFAULT",
      "time_stop": "2021-02-01T01:15:44+00:00",
      "time_start": "2021-02-01T01:06:03+00:00",
      "location_stop": "A&W, 2870 Gibford Drive",
      "event_cnt": 0,
      "location_start": "770 Ridgewood Avenue, Ottawa",
      "geometry": "}{{sGnq}lM??DAH?AEAg@GiBAa@?QDAApADlA@f@NA\\K]JO@@DBv@?XBl@?DBp@LAPAJ??G?FK?"
    }
  }
]

Returns all routes for the specified asset.

Request

GET api.velavu.com/assets/.asset_id/routes

Query Parameters

Parameter	Required	Description
since	false	Timestamp lower bound
until	false	Timestamp upper bound

Get a Specific Route

{
  "id": "ysC9jlb",
  "asset_id": "Jcoasws",
  "timestamp": "2021-02-01T01:06:03+00:00",
  "data": {
    "avg_speed": 11.6,
    "distance": 6715,
    "max_speed": 26,
    "customer_id": "DEFAULT",
    "time_stop": "2021-02-01T01:15:44+00:00",
    "time_start": "2021-02-01T01:06:03+00:00",
    "location_stop": "A&W, 2870 Gibford Drive",
    "event_cnt": 0,
    "location_start": "770 Ridgewood Avenue, Ottawa",
    "geometry": "}{{sGnq}lM??DAH?AEAg@GiBAa@?QDAApADlA@f@NA\\K]JO@@DBv@?XBl@?DBp@LAPAJ??G?FK?"
    "annotations": [
      {
        "speed_limit": {
          "speed": 60,
          "unit": "km/h"
        },
        "events": [
          {
            "max_g": 0.66,
            "direction": "TURNING"
          }
        ],
        "index": 55,
        "speed": 18.1,
        "timestamp": "2021-02-01T01:09:04+00:00"
      }
    ]
  }
}

Returns a single route for the specified asset, including a list of annotations that correspond to specific points along the route.

Annotations Properties

Property	Type	Description
index	number	Index of corresponding coordinate point in the `geometry` linestring list.
speed	number	Speed in m/s
speed_limit	Optional[dict]	Speed limit at that point
events	Optional[list]	List of driving events which occurred at that point

Request

GET api.velavu.com/assets/.asset_id/routes/.route_id

Delete a Specific Route

Deletes the specified route.

Request

DELETE api.velavu.com/assets/.asset_id/routes/.route_id

Devices

Device Object

{
  "id": "nseWKCv",
  "serial_code": "e0-48-b3-fe-43-c7",
  "location": <Location>,
  "heartbeat": "2021-03-08T18:39:24+00:00",
  "online": true,
  "config": <DeviceConfig>,
  "state": <DeviceState>,
  "category": "TAG",
  "hardware": "argo",
  "model": "Vesta",
  "gateway_id": "fj0kA",
  "asset": <Asset>,
  "site_id": "82HKcs1",
  "environment": <Environment>,
  "dfu_channel": "STABLE"
}

The Device object represents a Velavu IoT device.

Property	Type	Description
id	string	Unique identifier for the object
serial_code	string	Device's hardware serial code
online	bool	Whether the device is online. This is calculated from the heartbeat and heartbeat_rate_s configuration
location	Optional[Location]	Latest device location. Refer to table below.
heartbeat	Optional[string]	Timestamp of the latest heartbeat message
config	Optional[dict]	See protobuf message definition for property information
config_confirmed	Optional[bool]	True if the config stored in the backend is synced with the device
state	Optional[dict]	See protobuf message definition for property information
category	string	Device category, either `TAG` or `ANCHOR`
hardware	Optional[string]	Internal name corresponding to the application running on this device
model	Optional[string]	Unique name given to this device type
gateway_id	Optional[string]	For wirepas mesh devices, the gateway used for routing messages
site_id	Optional[string]	Represents the id of a site a device is within, determined via the site boundaries and the device location
asset	Optional[Asset]	Asset that is paired to the device
environment	Optional[Environment]	Latest environment data of a device
notes	Optional[string]	Additional information about the device
dfu_channel	Optional[string]	Automatic firmware update channel. When set, the device will receive the latest compatible firmware for this channel on each heartbeat. Accepted values: `STABLE`, `BETA`, `ALPHA`. Only supported for `argo` devices

Device Types

The device type is indicated by its hardware property. Different devices have different state and config capabilities as shown below.

Device `argo`

Config

{
  "heartbeat_rate_s": 1800,
  "imu": {
   "shock_detection": 0,
   "motion_detection": true,
   "motion_cooldown_s": 15
  },
  "positioning": {
   "dynamic_mode": true,
   "fixed_rate_s": 0
  },
  "usb_battery_backup": false,
  "vehicle": {
   "record_driving": true,
   "driving_timeout_s": 210,
   "alert_sensitivity": 50
  },
  "wirepas": {
   "gateway_mode": "VELAVU_BACKEND",
   "role": "SINK",
   "low_latency_mode": true
  }
}

Property	Type	Description
heartbeat_rate_s	number	The period in seconds between heartbeat messages
vehicle.driving_timeout_s	number	Timeout in seconds before exiting driving mode when no motion is detected
vehicle.record_driving	bool	True if driving mode is allowed
vehicle.alert_sensitivity	G-threshold for driving event alerts
wirepas.role	string	Wirepas role, must always be `SINK`
wirepas.gateway_mode	string	One of "VLV_BACKEND", "WIREPAS_BACKEND", or "DISABLED"
wirepas.low_latency_mode	bool	True if low-latency mode is enabled on the Wirepas sink
positioning.dynamic_mode	bool	True if device should update its location every time motion is sensed
positioning.fixed_rate_s	number	Describes the fixed update rate for position data
imu.shock_detection	number	Integer level for shock detection threshold from 0 to 3
imu.motion_detection	bool	True if motion detection alerts are enabled
imu.motion_cooldown_s	number	Cooldown period between subsequent motion alerts

State

{
  "app_version": "velavu-gateway_1.7.10_argo-revA_OPEN",
  "cell": {
   "apn": "iot.truphone.com",
   "band": 12,
   "fw_version": "mfw_nrf9160_1.3.0",
   "iccid": "8944477100000293095",
   "imei": "351358816815812",
   "operator_name": "310410",
   "psm_rat": -1,
   "psm_tau": 3240,
   "reg_status": "REGISTERED_HOME",
   "rsrp": 47,
   "net_mode": "LTEM"
  },
  "gnss": {
   "sats_in_view": 11,
   "snr": 29,
   "valid_fix": true
  },
  "power": {
   "battery_charging": false,
   "battery_level": 59,
   "usb_power": false
  },
  "vehicle": {
   "driving": false
  }
}

Property	Type	Description
app_version	string	Device application version
power.battery_level	number	Battery level in percent
power.battery_charging	bool	True if the battery is charging
power.usb_power	bool	True if connected to USB power
vehicle.driving	bool	True if in driving mode
cell.imei	string	Cell modem's IMEI
cell.iccid	string	SIM card ICCID
cell.reg_status	string	Cell modem registration status
cell.operator_name	string	MNC operator code
cell.apn	string	Access point name
cell.fw_version	string	Modem firmware version
cell.band	number	Currently used cell band
cell.rsrp	number	Cell signal strength
cell.net_mode	string	Cellular network mode, either 'LTEM' or 'NBIOT'
cell.psm_rat	number	PSM radio attach timer value
cell.psm_tau	number	PSM radio tracking area update value
gnss.valid_fix	bool	True if the device currently has a fix
gnss.sats_in_view	number	Number of tracking satellites
gnss.snr	number	Average SNR (Signal quality) of the tracked satellites

Device `juno`

Config

{
  "env_sensor_rate_s": 60,
  "heartbeat_rate_s": 300,
  "imu": {
   "motion_cooldown_s": 60,
   "motion_detection": false,
   "shock_detection": 0
  },
  "positioning": {
   "dynamic_mode": false,
   "fixed_rate_s": 60,
   "wpe_enabled": true
  },
  "wirepas": {
   "participate_otap": true,
   "role": "SUBNODE",
   "routing_info": false
  },
  "beacon": {
    "interval_ms": 1000,
    "tx_power": 0
  }
}

Property	Type	Description
heartbeat_rate_s	number	The period in seconds between heartbeat messages
env_sensor_rate_s	number	Describes the update rate for environment data
wirepas.role	string	Wirepas role, should always be `SUBNODE`
wirepas.participate_otap	bool	True if device should participate in firmware update procedure
wirepas.routing_info	bool	True if the device should send network routing diagnostics
positioning.dynamic_mode	bool	True if device should update its location every time motion is sensed
positioning.fixed_rate_s	number	Describes the fixed update rate for position data
positioning.wpe_enabled	bool	True if using Wirepas trilateration, False if using 'snap to anchor' positioning
imu.shock_detection	number	Integer level for shock detection threshold from 0 to 3
imu.motion_detection	bool	True if motion detection alerts are enabled
imu.motion_cooldown_s	number	Cooldown period between subsequent motion alerts
beacon.interval_ms	number	Advertising beacon broadcast interval, used only for inventory management
beacon.tx_power	number	Advertising beacon power level, used only for inventory management

State

{
  "app_version": "velavu-tracker_1.3.2_juno-revA_OPEN",
  "power": {
    "battery_level": 92
  },
  "wirepas": {
    "processed_otap_seq": 255,
    "stored_otap_seq": 0
  },
  "routing" {
    "device_id": "8HuK6",
    "install_quality": 100,
    "rssi": -65,
    "tx_power": 4
  }
}

Property	Type	Description
app_version	string	Device application version
power.battery_level	number	Battery level in percent
wirepas.processed_otap_seq	number	Processed OTAP (FW update) sequence
wirepas.stored_otap_seq	number	Stored OTAP (FW update) sequence
routing.device_id	string	Next device in the route to sink
routing.install_quality	number	Percentage from 0-100 indicating the router install quality
routing.rssi	number	Signal strength to the next device in the route to sink
routing.tx_power	number	Currently used radio transmit power

Device `pisces`

Config

{
  "heartbeat_rate_s": 300,
  "clock_timezone_m": -300,
  "imu": {
   "motion_cooldown_s": 60,
   "motion_detection": false,
   "shock_detection": 0
  },
  "positioning": {
   "dynamic_mode": false,
   "fixed_rate_s": 60,
   "wpe_enabled": true
  },
  "wirepas": {
   "participate_otap": true,
   "role": "SUBNODE"
  }
}

Property	Type	Description
heartbeat_rate_s	number	The period in seconds between heartbeat messages
clock_timezone_m	number	The minute offset from UTC time to display on the watch face
wirepas.role	string	Wirepas role, should always be `SUBNODE`
wirepas.participate_otap	bool	True if device should participate in firmware update procedure
positioning.dynamic_mode	bool	True if device should update its location every time motion is sensed
positioning.fixed_rate_s	number	Describes the fixed update rate for position data
positioning.wpe_enabled	bool	True if using Wirepas trilateration, False if using 'snap to anchor' positioning
imu.shock_detection	number	Integer level for shock detection threshold from 0 to 3
imu.motion_detection	bool	True if motion detection alerts are enabled
imu.motion_cooldown_s	number	Cooldown period between subsequent motion alerts

State

{
  "app_version": "velavu-wearable_1.0.0_pisces-revA_OPEN",
  "power": {
    "battery_level": 99,
    "charging": false
  },
  "wirepas": {
    "processed_otap_seq": 255,
    "stored_otap_seq": 0
  },
  "routing" {
    "device_id": "8HuK6",
    "install_quality": 100,
    "rssi": -65,
    "tx_power": 4
  }
}

Property	Type	Description
app_version	string	Device application version
power.battery_level	number	Battery level in percent
power.battery_charging	bool	True if the battery is currently charging
wirepas.processed_otap_seq	number	Processed OTAP (FW update) sequence
wirepas.stored_otap_seq	number	Stored OTAP (FW update) sequence
routing.device_id	string	Next device in the route to sink
routing.install_quality	number	Percentage from 0-100 indicating the router install quality
routing.rssi	number	Signal strength to the next device in the route to sink
routing.tx_power	number	Currently used radio transmit power

Device `meridian`

Config

{
  "env_sensor_rate_s": 60,
  "heartbeat_rate_s": 300,
  "imu": {
   "motion_cooldown_s": 60,
   "motion_detection": false,
   "shock_detection": 0
  },
  "positioning": {
   "dynamic_mode": false,
   "fixed_rate_s": 60,
   "wpe_enabled": true
  },
  "wirepas": {
   "participate_otap": true,
   "role": "HEADNODE",
   "low_latency_mode": false,
   "routing_info": true
  },
  "beacon": {
    "interval_ms": 1000,
    "tx_power": 0
  }
}

Property	Type	Description
heartbeat_rate_s	number	The period in seconds between heartbeat messages
env_sensor_rate_s	number	Describes the update rate for environment data
positioning.dynamic_mode	bool	True if device should update its location every time motion is sensed
positioning.fixed_rate_s	number	Describes the fixed update rate for position data
positioning.wpe_enabled	bool	True if using Wirepas trilateration, False if using 'snap to anchor' positioning
wirepas.role	string	Wirepas role, may be `HEADNODE` or `SUBNODE`
wirepas.participate_otap	bool	True if device should participate in firmware update procedure
wirepas.low_latency_mode	bool	True if the device operates in low latency mode
wirepas.routing_info	bool	True if the device should send network routing diagnostics
imu.shock_detection	number	Integer level for shock detection threshold from 0 to 3
imu.motion_detection	bool	True if motion detection alerts are enabled
imu.motion_cooldown_s	number	Cooldown period between subsequent motion alerts
beacon.interval_ms	number	Advertising beacon broadcast interval, used only for inventory management
beacon.tx_power	number	Advertising beacon power level, used only for inventory management

State

{
  "app_version": "velavu-anchor_1.3.1_meridian-revA_OPEN",
  "power": {
   "battery_level": 96
  },
  "wirepas": {
   "processed_otap_seq": 3,
   "stored_otap_seq": 0
  },
  "routing" {
    "device_id": "8HuK6",
    "install_quality": 100,
    "rssi": -65,
    "tx_power": 4
  }
}

Property	Type	Description
app_version	string	Device application version
power.battery_level	number	Battery level in percent
wirepas.processed_otap_seq	number	Processed OTAP (FW update) sequence
wirepas.stored_otap_seq	number	Stored OTAP (FW update) sequence
routing.device_id	string	Next device in the route to sink
routing.install_quality	number	Percentage from 0-100 indicating the router install quality
routing.rssi	number	Signal strength to the next device in the route to sink
routing.tx_power	number	Currently used radio transmit power

Environment Object

Property	Type	Description
temperature_c	Optional[number]	Temperature in degrees celsius
humidity	Optional[number]	Relative humidity in percent
pressure_kpa	Optional[number]	Atmospheric pressure in kPa

Location Object

The contents of a device's location dict depend on the technology used to locate said device. The property location_type tells what other properties are present, as follows:

GPS Location

{
  "location_type": "GPS",
  "coordinates": [-75.36125, 45.61251],
  "timestamp": "2021-03-08T14:53:52+00:00", 
  "speed": 5.4,
  "heading_deg": 62
}

Property	Type	Description
location_type	string	`GPS` to indicate a gps location
coordinates	list[number]	Device decimal coordinates as a long, lat pair
timestamp	string	ISO8601 formatted timestamp
altitude	Optional[number]	Altitude in meters
speed	Optional[number]	Speed in m/s
heading_deg	Optional[number]	Ground heading in degrees
accuracy	Optional[number]	Estimated position accuracy in meters

Mesh Location

{
  "location_type": "MESH",
  "coordinates": [-75.36125, 45.61251],
  "timestamp": "2021-03-08T14:53:52+00:00", 
  "accuracy": 2.4
  "floor_id": "gqh24Ws"
}

Property	Type	Description
location_type	string	`MESH` to indicate a mesh-calculated location
coordinates	list[number]	Device decimal coordinates as a long, lat pair
timestamp	string	ISO8601 formatted timestamp
accuracy	Optional[number]	Estimated position accuracy in meters
floor_id	Optional[string]	ID of the floor on which the device is located if inside a site

Proximity Location

{
  "location_type": "PROXIMITY",
  "coordinates": [
    -75.694817,
    45.432766
  ],
  "device_id": "tvIGq",
  "timestamp": "2021-03-08T14:53:52+00:00", 
  "accuracy": 1.2
}

Property	Type	Description
location_type	string	`PROXIMITY` to indicate a proximity-calculated location
coordinates	list[number]	Location coordinates of the device specified by `device_id`
timestamp	string	ISO8601 formatted timestamp
accuracy	number	Estimated position accuracy in meters
device_id	string	The signal strength of this device is measured and converted to `accuracy`

Fixed Location

{
  "location_type": "FIXED",
  "coordinates": [-75.36125, 45.61251],
  "timestamp": "2021-03-08T14:53:52+00:00", 
  "floor_id": "gqh24Ws",
  "locked": true
}

Property	Type	Description
location_type	string	`FIXED` to indicate a location set via the REST API
coordinates	list[number]	Device decimal coordinates as a long, lat pair
timestamp	string	ISO8601 formatted timestamp when the location was set
floor_id	Optional[string]	ID of the floor on which the device is located if inside a site
locked	Optional[bool]	True if the location should not be updated automatically by the device itself

Cellular Location

{
  "location_type": "CELLULAR",
  "coordinates": [
    -75.694817,
    45.432766
  ],
  "timestamp": "2021-03-08T14:53:52+00:00", 
  "accuracy": 5000
}

Property	Type	Description
location_type	string	`CELLULAR` to indicate a cell-computed location
coordinates	list[number]	Coordinates obtained by cell tower trilateration
timestamp	string	ISO8601 formatted timestamp
accuracy	Optional[number]	Estimated position accuracy in meters

WiFi Location

{
  "location_type": "WIFI",
  "coordinates": [
    -75.694817,
    45.432766
  ],
  "timestamp": "2021-03-08T14:53:52+00:00", 
  "accuracy": 20
}

Property	Type	Description
location_type	string	`WIFI` to indicate a WiFI-computed location
coordinates	list[number]	Coordinates obtained by WiFi AP scanning
timestamp	string	ISO8601 formatted timestamp
accuracy	Optional[number]	Estimated position accuracy in meters

Get All Devices

[
  {
    "id": "fFalCTg",
    "online": false,
    "state": {
      "power": {
        "battery_level": 100
      }
    }
  },
  {
    "id": "nseWKCv",
    "online": true,
    "asset": {
      "id": "2drjCI7",
      "name": "Rohan's Car"
    },
    "state": {
      "power": {
        "battery_level": 95
      }
    }
  }
]

Returns all devices.

Request

GET api.velavu.com/devices

Query Parameters

Parameter	Required	Description
category	false	Only return devices matching this category, either `TAG` or `ANCHOR`
site_id	false	Only return devices inside this site
geofence_id	false	Only return devices inside this geofence
bbox	false	Comma-separated bounding box to search, eg "-75.695075,45.432396,-75.6941916,45.4333581"
paired	false	`true` to only return paired devices or `false` to only return unpaired devices
hardware	false	Only return devices matching this hardware
model	false	Only return devices matching this model
online	false	`true` to only return online devices or `false` to only return offline devices
only_registered	false	`true` if only devices that are registered but have not yet come online should be returned. Cannot be used in conjunction with the `online` parameter
config_confirmed	false	`true` to only return devices with synchronized configuration or `false` to only return unsynchronized devices
id	false	Device ID to filter against. Matches any device who's ID begins with the provided string

Get a Specific Device

{
  "id": "nseWKCv",
  "serial_code": "e0-48-b3-fe-43-c7",
  "location": {
    "coordinates": [
      -75.67088,
      45.34612
    ],
    "heading_deg": 0,
    "speed": 0,
    "timestamp": "2021-03-08T14:53:52+00:00"
  },
  "heartbeat": "2021-03-08T18:39:24+00:00",
  "online": true,
  "config": {
    "heartbeat_rate_s": 1800,
    "vehicle": {
      "alert": {
        "thresh_acc_g": 0.4,
        "thresh_turn_g": 0.5,
        "enabled": true,
        "thresh_brake_g": 0.6
      },
      "positioning_rate_s": 5,
      "driving_timeout_s": 210
    }
  },
  "state": {
    "power": {
      "battery_level": 95,
      "battery_charging": false,
      "usb_power": false
    },
    "app_version": "1.1.0_DEFAULT",
    "cell": {
      "operator_name": "Bell",
      "iccid": "89302690100000843620",
      "psm_rat": 60,
      "reg_status": "REGISTERED_HOME",
      "psm_tau": 1800,
      "imei": "352656100534299",
      "rsrp": 255,
      "net_mode": "LTEM",
      "band": 12,
      "fw_version": "mfw_nrf9160_1.2.3",
      "apn": "mnet.bell.ca.ioe"
    },
    "vehicle": {
      "driving": false
    },
    "gnss": {
      "valid_fix": true,
      "sats_in_view": 13,
      "snr": 31
    }
  },
  "category": "TAG",
  "hardware": "argo",
  "model": "Vesta"
}

Returns all stored data for the specified device.

Request

GET api.velavu.com/devices/.device_id

Get Available Device by ID or Serial Code

    {
  "device": <DeviceObject>,
  "registered": False
}

Queries a device by ID or serial code. Useful for finding a device when the ID is unknown, or for checking whether a device can be registered via POST api.velavu.com/devices/.device_id.

Request

GET api.velavu.com/available

Query Parameters

Parameter	Type	Required	Description
serial_code	string	false	Serial code of the device
id	string	false	Internal ID of the device

Response Properties

Property	Type	Description
device	DeviceObject	The full device object
registered	bool	`true` if the device is registered to this organization, `false` otherwise

Response Codes

Parameter	Description
200	Device exists and is either already registered or ready to be registered to a customer
400	Request error, check that serial code or ID are provided as a query parameter
403	Device is already registered to another customer
404	Device does not exist in the Velavu system

Register an Available Device

{
  "category": "ANCHOR",
  "location": {
    "coordinates": [
      -75.1251,
      45.6132
    ],
    "floor_id": "fa9K2i188A",
    "locked": true
  }
}

{
  "id": "Vwe8F2a",
  "serial_code": "a1-b2-c3-d4",
  "category": "ANCHOR",
  "hardware": "meridian",
  "model": "Pavo",
  "online": false,
  "location": {
    "location_type": "FIXED",
    "coordinates": [
      -75.1251,
      45.6132
    ],
    "floor_id": "fa9K2i188A",
    "locked": true
  }
}

Registers an available device to this organization.

Request

POST api.velavu.com/devices/.device_id

For ANCHOR devices you should provide the anchor's location coordinates and optional floor ID. This location will be used with Wirepas positioning engine to provide positioning for Wirepas tags.

Request Parameters

Property	Type	Required	Description
location	dict	false	Update the location of a device to a `FixedLocation` type
notes	string	false	Additional notes about the device
category	string	false	Either `TAG` or `ANCHOR`. Restrictions apply to possible categories depending on device model

Create a New Device

{
  "id": "Vwe8F2a",
  "serial_code": "aa-bb-cc-dd-ee-ff",
  "model": "Minew E5",
  "category": "ANCHOR",
  "location": {
    "coordinates": [
      -75.1251,
      45.6132
    ],
    "floor_id": "fa9K2i188A",
    "locked": true
  }
}

{
  "id": "Vwe8F2a",
  "serial_code": "aa-bb-cc-dd-ee-ff",
  "category": "ANCHOR",
  "hardware": "generic",
  "model": "Minew E5",
  "location": {
    "location_type": "FIXED",
    "coordinates": [
      -75.1251,
      45.6132
    ],
    "floor_id": "fa9K2i188A",
    "locked": true
  }
}

Creates and registers a new device that does not yet exist in Velavu.

Request

POST api.velavu.com/devices

Request Parameters

Property	Type	Required	Description
serial_code	string	true	Globally unique serial code that is equivalent to the static MAC address of the device
id	string	true	Any five-character alphanumeric ID to identify this device that is not in use by other devices in this account
model	string	true	Device model name. This must be one of the models returned in `GET /devicemodels`
category	string	true	Either `TAG` or `ANCHOR`. Restrictions apply to possible categories depending on device model
location	dict	false	Update the location of a device to a `FixedLocation` type
notes	string	false	Additional notes about the device

Modify a Specific Device

{
  "location": {
    "coordinates": [
      -75.1251,
      45.6132
    ],
    "floor_id": "AG2jhMM",
    "locked": true
  },
  "notes": "Lower stairwell"
}

{
  "id": "Vwe8F2a",
  "serial_code": "a1-b2-c3-d4",
  "category": "ANCHOR",
  "hardware": "meridian",
  "model": "Pavo",
  "location": {
    "location_type": "FIXED",
    "coordinates": [
      -75.1251,
      45.6132
    ],
    "floor_id": "AG2jhMM",
    "locked": true
  },
  "notes": "Lower stairwell"
}

Modifies one or more properties of the specified device.

Request

PATCH api.velavu.com/devices/.device_id

Request Parameters

Property	Type	Required	Description
location	dict	false	Update the location of a device to a `FixedLocation` type
notes	string	false	Additional notes about the device
state	dict	false	State property to update on a device
category	string	false	Either `TAG` or `ANCHOR`, this property may only be modified for `meridian` type devices
dfu_channel	string	false	Firmware update channel for automatic OTA updates. Accepted values: `STABLE`, `BETA`, `ALPHA`. Only supported for `argo` devices

Supported State Updates:

Hardware	Property	Type	Min	Max
meridian	buzzer_on	bool	false	true
argo	led_flash_on	bool	false	true

Delete a Specific Device

Unlocks the device and sends a factory reset command. If the device is pre-provisioned to an organization, it will re-provision to that organization's account.

Request

DELETE api.velavu.com/devices/.device_id

Remove a Specific Device's Location

Removes the location from the specified device.

Request

DELETE api.velavu.com/devices/.device_id/location

Disable Automatic Firmware Updates for a Device

Clears the dfu_channel from a device, disabling automatic OTA firmware updates.

Request

DELETE api.velavu.com/devices/.device_id/dfu_channel

Reboot a Specific Device

Sends a reboot command to the device.

Request

POST api.velavu.com/devices/.device_id/reboot

Request Position of a Specific Device

Sends a position request command to the device.

Request

POST api.velavu.com/devices/.device_id/positionrequest

Indicate a Specific Device

{
  "timeout_s": 15,
  "on_time_ms": 1000,
  "off_time_ms": 1000
}

Sends an indication command to the device, triggering a visual or audible signal (e.g. LED flash or buzzer) to help physically locate it.

Request

POST api.velavu.com/devices/.device_id/indicate

Request Body Parameters

Property	Type	Required	Description
timeout_s	int	false	Duration in seconds to run the indication sequence. Defaults to 30 s
on_time_ms	int	false	Duration in milliseconds the indicator is on during each cycle. Defaults to 500 ms
off_time_ms	int	false	Duration in milliseconds the indicator is off during each cycle. Defaults to 500 ms

Device Firmware Update (DFU)

The DFU endpoint implements firmware upgrade functionality for standalone devices.

DFU Image Object

{
  "name": "velavu-gateway_1.3.0_argo-revA_DEFAULT",
  "project": "velavu-gateway",
  "version": "1.3.0",
  "board": "argo-revA",
  "channel": "STABLE",
  "comment": "rewrite LED library",
  "release_date": "2021-05-12T23:38:58+00:00"
}

The DFU Image object represents an available Device Firmware Upgrade image.

Property	Type	Description
name	string	Full firmware name
project	string	Short firmware name
version	string	Firmware version
board	string	Board name and rev for which this firmware is built
channel	string	Release channel this image belongs to. May be `STABLE`, `BETA`, or `ALPHA`
comment	string	Note describing changes in this version
release_date	string	Timestamp when the firmware was released

DFU Request Object

{
  "id": "9r3AFn3",
  "timestamp": "2021-05-12T23:38:58+00:00",
  "device_id": "uytNB",
  "data": {
    "name": "velavu-gateway_1.3.0_argo-revA_OPEN",
    "status": "PENDING"
  }
}

The DFU Request object represents a firmware upgrade request that was sent to a device.

Property	Type	Description
id	string	Unique identifier for the object
timestamp	string	When the request was made
device_id	string	Device to which the request was made
data.name	string	Firmware name sent to the device
data.status	string	May be `PENDING`, `STARTED`, `COMPLETE` or `FAILED`

Get DFU images for a Device

[
  {
    "name": "velavu-gateway_1.3.1_argo-revA_DEFAULT",
    "project": "velavu-gateway",
    "version": "1.3.1",
    "board": "argo-revA",
    "channel": "STABLE",
    "comment": "add dfu_auto_update property",
    "release_date": "2021-05-12T23:38:58+00:00"
  },
  {
    "name": "velavu-gateway_1.3.2_argo-revA_DEFAULT",
    "project": "velavu-gateway",
    "version": "1.3.2",
    "board": "argo-revA",
    "channel": "BETA",
    "comment": "stability improvements",
    "release_date": "2021-05-12T23:38:58+00:00"
  }
]

Returns compatible DFU images for the specified device.

Request

GET api.velavu.com/dfu/device/.device_id/images

DFU allows the firmware of standalone devices to be remotely updated. When a new firmware image is built, it is uploaded to an S3 bucket. Use this endpoint to retrieve a list of firmware images compatible with the specified device.

The channel field on each image corresponds to the device's dfu_channel property. When a device has a dfu_channel set, the heartbeat handler will automatically send the latest image whose channel matches, if a newer version is available.

Get all DFU Requests

[
  {
    "id": "9r3AFn3",
    "timestamp": "2021-05-12T23:38:58+00:00",
    "device_id": "uytNB",
    "data":{
      "name": "velavu-gateway_1.3.0_argo-reva_DEFAULT",
      "status": "PENDING"
    }
  },
  {
    "id": "po5CAGo",
    "timestamp": "2021-05-14T02:14:53+00:00",
    "device_id": "nseWKCv",
    "data":{
      "name": "velavu-gateway_1.3.2_argo-revA_DEFAULT",
      "status": "PENDING"
    }
  }
]

Returns all DFU requests.

Request

GET api.velavu.com/dfu
GET api.velavu.com/dfu/device/.device_id

Create a DFU Request

{
  "name": "velavu-gateway_1.2.0_argo-reva_DEFAULT"
}

{
  "id": "9r3AFn3",
  "timestamp": "2021-05-12T23:38:58+00:00",
  "device_id": "uytNB",
  "data":{
    "name": "velavu-gateway_1.2.0_argo-reva_DEFAULT",
    "status": "PENDING"
  }
}

Creates a firmware update request for the specified device.

Request

POST api.velavu.com/dfu/device/.device_id

The firmware name must match a name returned by GET dfu/device/.device_id/images. Invalid firmware names will return a 400 Bad Request.

Request Parameters

Parameter	Type	Required	Description
name	string	true	Name of the firmware image

Delete a DFU Request

Deletes the specified DFU request.

Request

DELETE api.velavu.com/dfu/.request_id

Mesh Firmware Upgrade (OTAP)

The OTAP endpoint implements firmware upgrade functionality for mesh-network devices.

OTAP Image Object

{
  "name": "generic-app_1.0.0_moko-m6_OPEN.otap",
  "channel": "STABLE",
  "comment": "First release",
  "release_date": "2021-05-12T23:38:58+00:00",
  "crc": 15788
}

The OTAP Image object represents an available OTAP image.

Property	Type	Description
name	string	Full firmware name
channel	string	Release channel this image belongs to. May be `STABLE`, `BETA`, or `ALPHA`
comment	string	Note describing changes in this version
release_date	string	Timestamp when the firmware was released
crc	number	CRC of the OTAP image contents

OTAP Request Object

{
  "id": "o1OPs2q",
  "timestamp": "2021-05-14T15:05:30+00:00",
  "device_id": "tVH1g",
  "data":{
    "name": "generic-app_1.0.0_moko-m6_OPEN.otap",
    "sequence": 1,
    "processing_delay": 0,
    "status": "COMPLETE"
  }
}

The OTAP Request object represents an otap upgrade request that was sent to a device.

Property	Type	Description
id	string	Unique identifier for the object
timestamp	string	When the request was made
device_id	string	Gateway device to which the request was sent. The gateway propagates the request to all mesh devices inside its network
data.processing_delay	number	Number of seconds that the firmware is allowed to propagate before processing the update
data.name	string	Firmware name sent to the device
data.sequence	number	OTAP sequence used for the update. This is calculated by the backend to update the most devices possible based on the known devices in the network. Refer to Wirepas documentation for more details
data.status	string	May be `PENDING`, `STARTED`, `COMPLETE` or `FAILED`

Get OTAP images

[
  {
    "name": "generic-app_1.0.0_moko-m6_OPEN.otap",
    "channel": "STABLE",
    "comment": "First release",
    "release_date": "2021-05-12T23:38:58+00:00",
    "crc": 15788
  }
]

Returns OTAP images available for loading to a gateway device.

Request

GET api.velavu.com/otap/images

Any gateway can load any OTAP image. A good strategy is to consider the devices that are online and routing via gateway_id, then send an OTAP request targeting images compatible with those devices.

Get all OTAP Requests

[
  {
    "id": "o1OPs2q",
    "timestamp": "2021-05-14T15:05:30+00:00",
    "device_id": "tVH1g",
    "data":{
      "processing_delay_s": 0,
      "name": "generic-app_1.0.1_moko-m6_OPEN.otap",
      "sequence": 2,
      "status": "STARTED"
    }
  },
  {
    "id": "kHZ4tg9",
    "timestamp": "2021-05-14T14:57:11+00:00",
    "device_id": "tVH1g",
    "data":{
      "processing_delay_s": 0,
      "name": "generic-app_1.0.0_moko-m6_OPEN.otap",
      "sequence": 1,
      "status": "COMPLETE"
    }
  }
]

Returns all OTAP requests.

Request

GET api.velavu.com/otap
GET api.velavu.com/otap/device/.device_id

Create an OTAP Request

{
  "name": "generic-app_1.0.0_moko-m6_OPEN.otap",
}

{
  "id": "o1OPs2q",
  "timestamp": "2021-05-14T15:05:30+00:00",
  "device_id": "tVH1g",
  "data":{
    "processing_delay_s": 0,
    "name": "generic-app_1.0.0_moko-m6_OPEN.otap",
    "sequence": 2
  }
}

Creates an OTAP firmware update request for the specified device.

Request

POST api.velavu.com/otap/device/.device_id

The name property must match a name returned by GET otap/images. Invalid firmware names will return a 400 Bad Request.

Request Parameters

Parameter	Type	Required	Description
name	string	true	Name of the firmware image
sequence	number	false	The Wirepas OTAP sequence number. Defaults to 1 which is acceptable for most cases
processing_delay_s	number	false	Duration in seconds that the OTAP image propagates on the mesh network before processing the image. Defaults to 0

Delete an OTAP Request

Deletes the specified OTAP request.

Request

DELETE api.velavu.com/otap/.request_id

Rules

Rule Object

{
  "id": "8lrianlTz9",
  "condition": "environment.temperature_c < 5",
  "action": {
      "on_active": {
          "category": "CUSTOM_EVENT",
          "store_event": false,
          "store_alert": true,
          "message": "Temperature drop measured by asset {{asset.name}}.\n Temperature: {{environment.temperature_c}}.",
          "sms_numbers": [
              "+12345678910"
          ]
      }
  },
  "priority": 0,
  "category": "USER",
  "enabled": true,
  "name": "Temperature monitor rule",
  "description": "This rule alerts via SMS if the temperature drops below 5 degrees",
  "created": "2025-07-22T21:16:48+00:00",
  "last_modified": "2025-07-22T21:24:46+00:00"
}

The Rule object represents a logical 'if' statement that can change a device configuration or trigger an alert. With Rules, one can implement logic via the REST API that controls device behavior and creates programmable alerts without writing any code. Rules are also used internally inside the Velavu backend for managing global device settings, as well as site, geofence, and inventory alerts.

Property	Type	Description
id	string	Unique identifier for the object
created	string	Timestamp when the rule was created
last_modified	string	Timestamp when the rule was last modified
condition	string	The conditional statement string that is evaluated to determine if the action should be executed
priority	number	A positive integer describing the rule execution priority in descending order. (Default: 0)
category	string	One of `SYSTEM`, `MANAGED`, or `USER`
action	RuleAction	The action performed when the rule is executed
enabled	bool	True if the rule is enabled, else False
name	Optional[string]	The name of the rule
description	Optional[string]	Text description of the rule

RuleAction Object

Parameter	Type	Required	Description
config	dict	false	A dictionary representing the configuration that will be applied to any device that matches the rule's condition
on_active	EventOptions	false	Event generation options for when a rule becomes activated
on_deactive	EventOptions	false	Event generation options for when a rule becomes deactivated

EventOptions Object

Parameter	Type	Required	Description
category	EventCategory	true	The category of the event created when the rule is triggered. Rules created via the REST API MUST be of type `CUSTOM_EVENT`
message	string	true	A custom message string to publish via SMS or email. Supports variable substitution via double braces (See example above). Only applicable to events of category `CUSTOM_EVENT`
sms_numbers	list[string]	false	A list of phone numbers in E.164 format that will receive an SMS when the rule is triggered. Only applicable to events of type `CUSTOM_EVENT`
email_addresses	list[string]	false	A list of email addresses that will receive an email when the rule is triggered. Only applicable to events of type `CUSTOM_EVENT`
store_event	bool	false	True if the event should be stored in the database. Defaults to true
store_alert	bool	false	True if an alert should be created for this event. Defaults to true

{
  "condition": "hardware == juno AND site_id == aso2Gw6",
  "action": {
    "config": {
      "positioning_rate_s": 300
    }
  }
}

{
  "condition": "asset.category == HAZARDOUS_MATERIALS AND geofence_ids CONTAINS fA2SLW21tr",
  "action": {
    "on_active": {
      "category": "CUSTOM_EVENT",
      "message": "{{asset.name}} entered a restricted zone!",
      "sms_numbers": ["+12345678910"],
      "store_alert": true,
      "store_event": false
    }
  }
}

Rules Condition Syntax

A rule condition string follows a similar format to conditional expressions in popular programming languages.
Conditions are composed of comparison expressions optionally combined by logical operators. The format of a comparison expression must be a device object property path followed by an operator followed by a constant.

For example:
"environment.temperature_c > 25"
or
"geofence_ids" CONTAINS "fA2SLW21tr"

These conditional expressions can be combined using logical operators AND and OR.
For example:
"environment.temperature_c > 25 AND online == True"

Supported Comparison operators:

==
!=
>
<
>=
<=
CONTAINS
NOT_CONTAINS
CONTAINS_K
NOT_CONTAINS_K

Important considerations:

All operators must be surrounded by a single space on either side.
Logical operations are evaluated left-to-right.
Type is inferred from the property's type. In the example above, 25 will be converted to a number because environment.temperature_c is a number.

Actions

Actions take place after the rule's condition changes state. Device configurations described in config will be applied when the condition evaluates true, while on_active, and on_deactive events are triggered when the condition becomes true or false respectively. For config actions, the action must still be one of the supported parameters for the given device hardware.

Get All Rules

[
  {
    "id": "8lrianlTz9",
    "condition": "environment.temperature_c < 5",
    "action": {
        "on_active": {
            "category": "CUSTOM_EVENT",
            "store_event": false,
            "store_alert": true,
            "message": "Temperature drop measured by asset {{asset.name}}.\n Temperature: {{environment.temperature_c}}.",
            "sms_numbers": [
                "+12345678910"
            ]
        }
    },
    "priority": 0,
    "category": "USER",
    "enabled": true,
    "name": "Temperature monitor rule",
    "description": "This rule alerts via SMS if the temperature drops below 5 degrees",
    "created": "2025-07-22T21:16:48+00:00",
    "last_modified": "2025-07-22T21:24:46+00:00"
  }
]

Returns all rules.

Request

GET api.velavu.com/rules

Get a Specific Rule

{
  "id": "8lrianlTz9",
  "condition": "environment.temperature_c < 5",
  "action": {
      "on_active": {
          "category": "CUSTOM_EVENT",
          "store_event": false,
          "store_alert": true,
          "message": "Temperature drop measured by asset {{asset.name}}.\n Temperature: {{environment.temperature_c}}.",
          "sms_numbers": [
              "+12345678910"
          ]
      }
  },
  "priority": 0,
  "category": "USER",
  "enabled": true,
  "name": "Temperature monitor rule",
  "description": "This rule alerts via SMS if the temperature drops below 5 degrees",
  "created": "2025-07-22T21:16:48+00:00",
  "last_modified": "2025-07-22T21:24:46+00:00"
}

Returns the specified rule.

Request

GET api.velavu.com/rules/.rule_id

Create a New Rule

{
  "condition": "environment.temperature_c < 5",
  "action": {
      "on_active": {
          "category": "CUSTOM_EVENT",
          "store_event": false,
          "store_alert": true,
          "message": "Temperature drop measured by asset {{asset.name}}.\n Temperature: {{environment.temperature_c}}.",
          "sms_numbers": [
              "+12345678910"
          ]
      }
  },
  "priority": 0,
  "category": "USER",
  "name": "Temperature monitor rule",
  "description": "This rule alerts via SMS if the temperature drops below 5 degrees",
}

{
  "id": "8lrianlTz9",
  "condition": "environment.temperature_c < 5",
  "action": {
      "on_active": {
          "category": "CUSTOM_EVENT",
          "store_event": false,
          "store_alert": true,
          "message": "Temperature drop measured by asset {{asset.name}}.\n Temperature: {{environment.temperature_c}}.",
          "sms_numbers": [
              "+12345678910"
          ]
      }
  },
  "priority": 0,
  "category": "USER",
  "enabled": true,
  "name": "Temperature monitor rule",
  "description": "This rule alerts via SMS if the temperature drops below 5 degrees",
  "created": "2025-07-22T21:16:48+00:00",
  "last_modified": "2025-07-22T21:24:46+00:00"
}

Creates a new rule.

Request

POST api.velavu.com/rules

Request Parameters

Parameter	Type	Required	Description
condition	string	true	The conditional statement string that is evaluated to determine if the action should be executed
action	RuleAction	true	The action performed when the rule is executed
priority	number	false	A positive integer describing the rule execution priority in descending order. Defaults to 0 (Highest priority)
category	string	false	Either `USER` or `MANAGED`. Defaults to `USER`
name	string	false	Name of the rule
description	string	false	Description of what the rule does

Error Reason Codes

Code	Description
ERR_INVALID_COND	The condition could not be evaluated or the format is incorrect
ERR_INVALID_ACTION	The format of the RuleAction is incorrect
ERR_INVALID_PRIO	The priority is invalid

Modify an Existing Rule

{
  "condition": "environment.temperature_c < 5",
}

{
  "id": "8lrianlTz9",
  "condition": "environment.temperature_c < 5",
  "action": {
      "on_active": {
          "category": "CUSTOM_EVENT",
          "store_event": false,
          "store_alert": true,
          "message": "Temperature drop measured by asset {{asset.name}}.\n Temperature: {{environment.temperature_c}}.",
          "sms_numbers": [
              "+12345678910"
          ]
      }
  },
  "priority": 0,
  "category": "USER",
  "enabled": true,
  "name": "Temperature monitor rule",
  "description": "This rule alerts via SMS if the temperature drops below 5 degrees",
  "created": "2025-07-22T21:16:48+00:00",
  "last_modified": "2025-07-22T21:24:46+00:00"
}

Modifies an existing rule.

Request

PATCH api.velavu.com/rules/.rule_id

Request Parameters

Parameter	Type	Required	Description
condition	string	false	The conditional statement string that is evaluated to determine if the action should be executed
action	RuleAction	false	The action performed when the rule is executed
priority	number	false	A positive integer describing the rule execution priority in descending order. (Default: 0)
enabled	bool	false	True if the rule is enabled, else False
name	string	false	Name of the rule
description	string	false	Description of what the rule does

Delete a Rule

Deletes the specified rule.

Request

DELETE api.velavu.com/rules/.rule_id

Events

Event Object

{
  "id": "1hmmqzy",
  "timestamp": "2022-02-23T23:15:13.323404+00:00",
  "category": "IMU_SHOCK",
  "device_id": "F3gY8",
  "data": {
    "gforce": 2.565323
  }
}

Event objects represent any time-based data associated with a device, such as a location update, crossing a geofence boundary, going offline, or detecting an impact.

Property	Type	Description
id	string	Unique identifier for the object
timestamp	string	ISO8601 formatted timestamp representing when the measurement was made
category	string	Field that describes the type of event, which determines the fields present in `data`
device_id	Optional[string]	ID of the asset to which this event belongs, if any
asset_id	Optional[string]	ID of the asset to which this event belongs, if any
site_id	Optional[string]	Id of the site to which this event belongs, if any
geofence_id	Optional[string]	Id of the geofence to which this event belongs, if any
data	dict	Depends on `category`, as shown below

Environment Data

category: ENVIRONMENT

Property	Type	Description
data.temperature_c	Optional[number]	Temperature in degrees celsius
data.humidity	Optional[number]	Relative humidity in percent
data.pressure_kpa	Optional[number]	Atmospheric pressure in kPa

Environment Threshold Alert

category: ENV_THRESHOLD

Property	Type	Description
data.temperature_c	Optional[number]	Temperature in degrees celsius
data.humidity	Optional[number]	Relative humidity in percent
data.pressure_kpa	Optional[number]	Atmospheric pressure in kPa

Battery Data

category: BATTERY_LEVEL

Property	Type	Description
data.battery_level	number	Device battery level in percent

Battery Threshold Alert

category: LOW_BATTERY

This alert is most commonly used to indicate a low battery condition.

Property	Type	Description
data.battery_level	number	Device battery level in percent

Location Data

category: LOCATION

Refer to the Location Object section in the Devices documentation.

Driving Route

category: DRIVING_ROUTE

Property	Type	Description
data.time_start	string	Time that driving started
data.location_start	string	Location where driving started
data.avg_speed	number	Average route speed in m/s
data.distance	number	Total route distance in meters
data.max_speed	number	Maximum speed in m/s
data.geometry	string	Polyline-encoded geojson linestring representing the entire route
data.time_stop	Optional[string]	Time that driving ended
data.location_stop	Optional[string]	Location where driving ended
data.event_cnt	Optional[number]	Driving event count (harsh braking, acceleration, etc.)
data.annotations	Optional[list]	Additional info about the route

Harsh Driving Event

category: DRIVING_EVT

Property	Type	Description
data.direction	string	`ACCELERATION`, `BRAKING`, or `TURNING`
data.max_g	number	Maximum measured g-force
data.coordinates	list[number]	Location where the event occurred
route_id	string	ID of the associated route object

Device Connect

category: DEVICE_CONNECT

This event has no data.

Device Disconnect

category: DEVICE_DISCONNECT

This event has no data.

Device Provision

category: DEVICE_PROVISION

This event has no data.

Device Boot

category: DEVICE_BOOT

This event has no data.

Device Error

category: DEVICE_ERROR

Property	Type	Description
data.level	string	Error level
data.type	string	Error subtype
data.msg	string	Error message

Fall / Impact Event

category: IMU_SHOCK

Property	Type	Description
data.gforce	number	Peak g-force experienced during the impact

Significant Motion Event

category: IMU_MOTION

This event has no data.

Site Entered

category: SITE_ENTERED

Property	Type	Description
data.site.id	string	ID of the site object
data.site.name	string	Name of the site
data.coordinates	list[number]	Location where the event occurred
data.asset.id	Optional[string]	ID of the associated asset
data.asset.name	Optional[string]	Name of the associated asset

Site Exited

category: SITE_EXITED

Property	Type	Description
data.site.id	string	ID of the site object
data.site.name	string	Name of the site
data.coordinates	list[number]	Location where the event occurred
data.asset.id	Optional[string]	ID of the associated asset
data.asset.name	Optional[string]	Name of the associated asset

Geofence Entered

category: GEOFENCE_ENTERED

Property	Type	Description
data.geofence.id	string	ID of the geofence object
data.geofence.name	string	Name of the geofence
data.coordinates	list[number]	Location where the event occurred
data.asset.id	Optional[string]	ID of the associated asset
data.asset.name	Optional[string]	Name of the associated asset

Geofence Exited

category: GEOFENCE_EXITED

Property	Type	Description
data.geofence.id	string	ID of the geofence object
data.geofence.name	string	Name of the geofence
data.coordinates	list[number]	Location where the event occurred
data.asset.id	Optional[string]	ID of the associated asset
data.asset.name	Optional[string]	Name of the associated asset

Wearable Alert Button Press

category: WEARABLE_ALERT

This event has no data.

Provision Request

category: PROVISION_REQUEST

Property	Type	Description
data.serial_code	string	The serial code of the device
data.provisioning_id	string	Temporary ID generated by the device in order to receive a provision response
data.gateway_id	Optional[string]	Device ID of the gateway that routed the provisioning request

Provision requests are only generated if the device is communicating on the customer's network but is not yet registered to the customer's account.

Custom Event

category: CUSTOM_EVENT

Property	Type	Description
data.message	string	Custom message describing the event

BLE Scan Request

category: BLE_SCAN_REQUEST

Property	Type	Description
data.expected_response_count	number	Number of scanners expected to respond during this scan
data.pending_response_count	number	Number of scanners that have not yet responded
data.scan_duration	number	Duration in seconds that each scanner scans for advertising beacons
data.scan_timeout	number	Timeout in seconds before the scan will be processed if scanners do not all respond beforehand
data.min_rssi	number	Minimum RSSI of advertising beacons
data.filters	list[string]	List of advertising beacon names to collect
data.status	string	One of `STARTED` or `COMPLETE`

Get All Events

[
  {
    "id": "1hmmqzy",
    "timestamp": "2022-02-23T23:15:13.323404+00:00",
    "category": "IMU_SHOCK",
    "device_id": "F3gY8",
    "data": {
      "gforce": 2.565323
    }
  }
]

Returns all events for the specified asset, device, site, or geofence.

Request

GET api.velavu.com/events/.category
GET api.velavu.com/events/.category/asset/.asset_id
GET api.velavu.com/events/.category/device/.device_id
GET api.velavu.com/events/.category/site/.site_id
GET api.velavu.com/events/.category/geofence/.geofence_id

Query Parameters

Parameter	Required	Description
since	false	Timestamp lower bound
until	false	Timestamp upper bound

Get Essential Events

[
  {
    "id": "1hmmqzy",
    "timestamp": "2022-02-23T23:15:13.323404+00:00",
    "category": "IMU_SHOCK",
    "device_id": "F3gY8",
    "data": {
      "gforce": 2.565323
    }
  }
]

Returns a combined result across several essential event categories for the specified asset or device.

Request

GET api.velavu.com/essentialevents/asset/.asset_id
GET api.velavu.com/essentialevents/device/.device_id

Query Parameters

Parameter	Required	Description
since	false	Timestamp lower bound
until	false	Timestamp upper bound

Included categories: LOW_BATTERY, IMU_SHOCK, IMU_MOTION, DEVICE_CONNECT, DEVICE_DISCONNECT, SITE_ENTERED, SITE_EXITED, GEOFENCE_ENTERED, GEOFENCE_EXITED, CUSTOM_EVENT

Delete All Events

Deletes all events for the specified device or asset.

Request

DELETE api.velavu.com/events/.category
DELETE api.velavu.com/events/.category/asset/.asset_id
DELETE api.velavu.com/events/.category/device/.device_id

Sites

Site Object

{
  "id": "1izt8dA",
  "name": "Home",
  "online": false,
  "coordinates": [
    -75.695174,
    45.433299
  ],
  "floors": [<Floor>],
  "boundary": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -75.68602811873693,
          45.36778576393944
        ],
        [
          -75.6860849818981,
          45.36832122537368
        ]
      ]
    ]
  },
  "boundary_factor": 1.5,
  "target_otap": <TargetOTAP>
}

The Site object represents a physical site or facility in which devices can reside. Sites can include floor plans to visualize the buildings in 3D and determine which devices are inside or outside a site.

Property	Type	Description
id	string	Unique identifier for the object
name	string	Name of the site
online	bool	True if the any gateways are in the site and online, else False
coordinates	list[number]	Site location as a long, lat pair
floors	Optional[list[Floor]]	List of floors within a site, sorted by floor level
boundary	Optional[dict]	GeoJSON Polygon describing the boundary for devices to be considered inside the site. This is generated by the floor plans and boundary_factor
boundary_factor	number	The scaling factor of the floor plan dimensions to the site boundary

Floor Object

{
  "name": "Test Floor",
  "level": 0,
  "id": "i6sbvssqdl",
  "geometry": {
    "walls": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {},
          "geometry": {
            "coordinates": [
              [
                -75.69528996678712,
                45.43330857313856
              ],
              [
                -75.69513580742498,
                45.43337360966831
              ]
            ],
            "type": "LineString"
          }
        }
      ]
    }
  },
  "img": <FloorImage>,
}

The Floor object represents a floor inside a building.

Property	Type	Description
id	string	Unique identifier for the object
name	string	Human-readable floor name
level	number	Floor level; used to sort the `floors` list
geometry.walls	dict	GeoJSON FeatureCollection of LineStrings representing the floor walls
img	Optional[FloorImage]	Image display properties such as rotation, scale, and opacity

FloorImage Object

{
  "filename": "Test Floor",
  "scale": 0,
  "rotation": "i6sbvssqdl",
  "opacity": 0.5,
  "width": 100,
  "height": 100,
  "center": [
    -75.695174,
    45.433299
  ],
  "coordinates": [
    [
      -75.695174,
      45.433299
    ],
    [
      -75.695174,
      45.433299
    ],
    [
      -75.695174,
      45.433299
    ],
    [
      -75.695174,
      45.433299
    ]
  ],
  "url": "https://s3.amazonaws.com/floorplan.png"
}

The FloorImage object stores display properties for a floorplan image overlay.

Property	Type	Description
filename	string	Filename of the uploaded image
scale	number	Scale factor applied to the image
rotation	number	Rotation of the image in degrees
opacity	number	Opacity of the image overlay (0–1)
width	number	Width of the image in pixels
height	number	Height of the image in pixels
center	list[number]	Geographic center of the image as a long, lat pair
coordinates	list[list[number]]	Bounding coordinates of the image corners
url	string	URL of the uploaded floorplan image

TargetOTAP Object

{
  "name": "aries-app_1.1.0_aries-revA_OPEN.otap",
  "crc": 15744,
  "rule_id": "I3tUufNKw8"
}

The TargetOTAP object defines the Wirepas firmware update image that propagates via any gateways in this site.

Property	Type	Description
name	string	Name of the Wirepas OTAP image
crc	number	CRC of the OTAP image contents
rule_id	string	ID of the auto-generated rule that enables OTAP propagation in this site

Get All Sites

[
  {
    "id": "1izt8dA",
    "name": "Rogers Centre",
    "online": false,
    "coordinates": [
      -75.695174,
      45.433299
    ],
    "floors": [
      <Floor>
    ],
    "boundary": <GEOJSON>,
    "boundary_factor": 1.5
  }
]

Returns all sites.

Request

GET api.velavu.com/sites

Get a Specific Site

{
  "id": "1izt8dA",
  "name": "Rogers Centre",
  "online": false,
  "coordinates": [
    -75.695174,
    45.433299
  ],
  "floors": [
    <Floor>
  ],
  "boundary": <GEOJSON>,
  "boundary_factor": 1.5
}

Returns the specified site.

Request

GET api.velavu.com/sites/.site_id

Create a New Site

{
  "name": "Test site",
  "coordinates": [
    -75.695174,
    45.433299
  ]
}

{
  "id": "NINv9e3RtU",
  "name": "Test site",
  "online": false,
  "coordinates": [
    -75.695174,
    45.433299
  ],
  "boundary": {
    "type": "Polygon",
    "coordinates": []
  },
  "boundary_factor": 1.5
}

Creates a new site.

Request

POST api.velavu.com/sites

Request Parameters

Parameter	Type	Required	Description
name	string	true	Human-readable site name
coordinates	list[number]	true	Site location as a long, lat pair

Modify an Existing Site

{
  "name": "New Name",
}

{
  "id": "1izt8dA",
  "name": "New Name",
  "online": false,
  "coordinates": [
    -75.531,
    45.775
  ]
}

Modifies the name or coordinates of the specified site.

Request

PATCH api.velavu.com/sites/.site_id

Request Parameters

Parameter	Type	Required	Description
name	string	false	Human-readable site name
coordinates	list[number]	false	Site location as a long, lat pair
boundary_factor	number	false	The scaling factor of the floor plan dimensions to the site boundary

Delete an Existing Site

Deletes the specified site.

Request

DELETE api.velavu.com/sites/.site_id

Create a New Site Floor

{
  "name": "Test Floor",
  "level": 0,
  "geometry": {
    "walls": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {},
          "geometry": {
            "coordinates": [
              [
                -75.69528996678712,
                45.43330857313856
              ],
              [
                -75.69513580742498,
                45.43337360966831
              ]
            ],
            "type": "LineString"
          }
        }
      ]
    }
  },
  "img": <FloorImage>,
  "img_upload": "VGVz ... cdA=="
}

{
  "name": "Test Floor",
  "level": 0,
  "id": "i6sbvssqdl",
  "geometry": {
    "walls": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {},
          "geometry": {
            "coordinates": [
              [
                -75.69528996678712,
                45.43330857313856
              ],
              [
                -75.69513580742498,
                45.43337360966831
              ]
            ],
            "type": "LineString"
          }
        }
      ]
    }
  },
  "img": <FloorImage>,
}

Creates a new floor within the specified site.

Request

POST api.velavu.com/sites/.site_id/floors

Request Parameters

Parameter	Type	Required	Description
name	string	true	Human-readable floor name
level	number	true	Floor level, this is used to sort the `floors` list
geometry.walls	dict	true	GeoJSON FeatureCollection consisting of only LineStrings which represents the floor walls
img		false	Image properties such as rotation, size, etc
img_upload	string	false	Floorplan image, base64 encoded

Update a Site Floor

{
  "name": "Updated floor name",
  "level": -1
}

{
  "name": "Updated floor name",
  "level": -1,
  "id": "i6sbvssqdl",
  "geometry": {
    "walls": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {},
          "geometry": {
            "coordinates": [
              [
                -75.69528996678712,
                45.43330857313856
              ],
              [
                -75.69513580742498,
                45.43337360966831
              ]
            ],
            "type": "LineString"
          }
        }
      ]
    }
  },
  "img": <FloorImage>,
}

Updates a floor in the specified site.

Request

PATCH api.velavu.com/sites/.site_id/floors/.floor_id

Request Parameters

Parameter	Type	Required	Description
name	string	false	Human-readable floor name
level	number	false	Floor level, this is used to sort the `floors` list
geometry.walls	dict	false	GeoJSON FeatureCollection consisting of only LineStrings which represents the floor walls
img		false	Image properties such as rotation, size, etc
img_upload	string	false	Floorplan image, base64 encoded

Delete a Site Floor

Deletes the specified site floor.

Request

DELETE api.velavu.com/sites/.site_id/floors/.floor_id

Upload a Floorplan Image

{
  "name": "Test Floor",
  "level": 0,
  "id": "i6sbvssqdl",
  "geometry": {
    "walls": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {},
          "geometry": {
            "coordinates": [
              [
                -75.69528996678712,
                45.43330857313856
              ],
              [
                -75.69513580742498,
                45.43337360966831
              ]
            ],
            "type": "LineString"
          }
        }
      ]
    }
  },
  "img": <FloorImage>,
}

Uploads a floorplan image for the specified floor.

Request

PUT api.velavu.com/sites/.site_id/floors/.floor_id/image

The request body should be an image binary. The Content-Type header should be set to image/png or image/jpeg.

Delete a Floorplan Image

Deletes the floorplan image for the specified floor.

Request

DELETE api.velavu.com/sites/.site_id/floors/.floor_id/image

Set the target OTAP image in a Site

{
  "name": "aries-app_1.1.0_aries-revA_OPEN.otap"
}

{
  "name": "aries-app_1.1.0_aries-revA_OPEN.otap",
  "crc": 15744,
  "rule_id": "I3tUufNKw8"
}

Sets the OTAP image to propagate via all gateways in the specified site.

Request

POST api.velavu.com/sites/.site_id/target_otap

Request Parameters

Parameter	Type	Required	Description
name	string	true	Name of the OTAP image

Unset the target OTAP image in a Site

Unsets the target OTAP image and disables OTAP for all gateways in the specified site.

Request

DELETE api.velavu.com/sites/.site_id/target_otap

Create a BLE Scan Request in a Site

{
  "min_rssi": -55,
  "filters": [
      "Minew I9"
  ]
}

{
    "id": "1i2qBcBkCi",
    "category": "BLE_SCAN_REQUEST",
    "timestamp": "2025-03-17T22:09:56+00:00",
    "site_id": "tOHnpVS0X8",
    "data": {
        "expected_response_count": 3,
        "filters": [
            "Minew I9"
        ],
        "min_rssi": -55,
        "pending_response_count": 3,
        "scan_duration": 15,
        "scan_timeout": 120,
        "status": "STARTED"
    }
}

Creates a BLE scan request in the specified site.

Request

POST api.velavu.com/sites/.site_id/blescanrequest

Request Parameters

Parameter	Type	Required	Description
min_rssi	string	false	Minimum RSSI of advertising beacons. Defaults to -72
filters	list[string]	false	List of advertising beacon names to collect. Currently supported options are `Minew I9` and `KKM K9P`. Defaults to `Minew I9`
scan_duration	number	false	Duration in seconds that each scanner scans for advertising beacons. Defaults to 15
scan_timeout	number	false	Timeout in seconds before the scan will be processed if scanners do not all respond beforehand. Defaults to 120

A BLE scan request detects standard BLE tags using devices capable of BLE scanning, such as the Velavu Dorado. When issuing a BLE scan request to a site, the system determines how many devices inside that site can perform BLE scanning and stores that count in data.pending_response_count. Each device's scan results are stored until data.pending_response_count reaches zero or data.scan_timeout elapses.

Geofences

Geofence Object

{
  "id": "1izt8dA",
  "name": "Restricted area",
  "center": [
    -75.531351,
    45.775512
  ],
  "boundary": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -75.68602811873693,
          45.36778576393944
        ],
        [
          -75.6860849818981,
          45.36832122537368
        ]
      ]
    ]
  }
}

The Geofence object represents a geographical area that can trigger alerts when devices enter or leave it.

Property	Type	Description
id	string	Unique identifier for the object
name	string	Name of the geofence
center	list[number]	Centroid of the boundary area as a long, lat pair
boundary	dict	GeoJSON Polygon describing the boundary for devices to be considered inside the geofence

Get All Geofences

[
  {
    "id": "1izt8dA",
    "name": "Restricted area",
    "center": [
      -75.531351,
      45.775512
    ],
    "boundary": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -75.68602811873693,
            45.36778576393944
          ],
          [
            -75.6860849818981,
            45.36832122537368
          ]
        ]
      ]
    }
  }
]

Returns all geofences.

Request

GET api.velavu.com/geofences

Get a Specific Geofence

{
  "id": "1izt8dA",
  "name": "Restricted area",
  "center": [
    -75.531351,
    45.775512
  ],
  "boundary": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -75.68602811873693,
          45.36778576393944
        ],
        [
          -75.6860849818981,
          45.36832122537368
        ]
      ]
    ]
  }
}

Returns the specified geofence.

Request

GET api.velavu.com/geofences/.geofence_id

Create a New Geofence

{
  "name": "Restricted area",
  "boundary": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -75.68602811873693,
          45.36778576393944
        ],
        [
          -75.6860849818981,
          45.36832122537368
        ]
      ]
    ]
  }
}

{
  "id": "1izt8dA",
  "name": "Restricted area",
  "center": [
    -75.531351,
    45.775512
  ],
  "boundary": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -75.68602811873693,
          45.36778576393944
        ],
        [
          -75.6860849818981,
          45.36832122537368
        ]
      ]
    ]
  }
}

Creates a new geofence.

Request

POST api.velavu.com/geofences

Request Parameters

Parameter	Type	Required	Description
name	string	true	Human-readable geofence name
boundary	dict	true	Geojson polygon describing the area boundary

Modify an Existing Geofence

{
  "name": "New Name",
}

{
  "id": "1izt8dA",
  "name": "New Name",
  "center": [
    -75.531351,
    45.775512
  ],
  "boundary": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -75.68602811873693,
          45.36778576393944
        ],
        [
          -75.6860849818981,
          45.36832122537368
        ]
      ]
    ]
  }
}

Modifies the name or boundary of the specified geofence.

Request

PATCH api.velavu.com/geofences/.geofence_id

Request Parameters

Parameter	Type	Required	Description
name	string	false	Human-readable geofence name
boundary	dict	false	Geojson polygon describing the area boundary

Delete an Existing Geofence

Deletes the specified geofence.

Request

DELETE api.velavu.com/geofences/.geofence_id

Inventory Areas

Inventory Area Object

{
  "id": "bK3aRMVna6",
  "name": "Inventory area",
  "sections": [
    {
      "id": "7Z9r7BRWA2",
      "name": "Section A",
      "anchor_id": "3eOsA"
    }
  ],
  "assets": [
    {
      "id": "MAy3dS0Qa6",
      "category": "EQUIPMENT",
      "group": "Toolbox",
      "name": "John's Toolbox",
      "online": true,
      "assigned": {
        "inventory_id": "bK3aRMVna6",
        "section_id": "7Z9r7BRWA2"
      },
      "found": {
        "inventory_id": "bK3aRMVna6",
        "section_id": "7Z9r7BRWA2"
      }
    }
  ]
}

The Inventory Area object represents a physical area used for organizing and tracking asset inventory. Inventory areas can be divided into sections, and assets can be assigned to specific sections within an area.

Property	Type	Description
id	string	Unique identifier for the inventory area
name	string	Name of the inventory area
sections	Optional[list[Section]]	List of sections within this inventory area
assets	Optional[list[InventoryAsset]]	List of assets that are assigned to this inventory area, with assignment and location information

Section Object

{
  "id": "7Z9r7BRWA2",
  "name": "Section A",
  "anchor_id": "3eOsA"
}

The Section object represents a subdivision within an inventory area. Sections can be associated with anchors for more precise asset tracking.

Property	Type	Description
id	string	Unique identifier for the section
name	string	Name of the section
anchor_id	Optional[string]	ID of the anchor device associated with this section

InventoryAsset Object

{
  "id": "MAy3dS0Qa6",
  "category": "EQUIPMENT",
  "group": "Toolbox",
  "name": "John's Toolbox",
  "online": true,
  "assigned": {
    "inventory_id": "bK3aRMVna6",
    "section_id": "7Z9r7BRWA2"
  },
  "found": {
    "inventory_id": "bK3aRMVna6",
    "section_id": "7Z9r7BRWA2"
  }
}

The InventoryAsset object represents an asset with additional inventory tracking information, including where it is assigned and where it was last found.

Property	Type	Description
id	string	Unique identifier for the asset
category	string	High-level classification, currently restricted to 'EQUIPMENT', 'VEHICLE', or 'PERSON'
group	string	More granular filtering & sorting
name	string	Name of the asset
online	Optional[bool]	`True` if the paired device is online, `False` if offline, or `None` if no device is paired
assigned	Optional[dict]	Location where the asset is assigned, contains `inventory_id` and `section_id`
found	Optional[dict]	Location where the asset was last found, contains `inventory_id` and `section_id`

Get Inventory Areas

[
  {
    "id": "bK3aRMVna6",
    "name": "Inventory area",
    "sections": [
      {
        "id": "7Z9r7BRWA2",
        "name": "Section A",
        "anchor_id": "3eOsA"
      }
    ],
    "assets": [
      {
        "id": "MAy3dS0Qa6",
        "category": "EQUIPMENT",
        "group": "Toolbox",
        "name": "John's Toolbox",
        "online": true,
        "assigned": {
          "inventory_id": "bK3aRMVna6",
          "section_id": "7Z9r7BRWA2"
        },
        "found": {
          "inventory_id": "bK3aRMVna6",
          "section_id": "7Z9r7BRWA2"
        }
      }
    ]
  }
]

Returns all inventory areas.

Request

GET api.velavu.com/inventories

Get a Specific Inventory Area

{
  "id": "bK3aRMVna6",
  "name": "Inventory area",
  "sections": [
    {
      "id": "7Z9r7BRWA2",
      "name": "Section A",
      "anchor_id": "3eOsA"
    }
  ],
  "assets": [
    {
      "id": "MAy3dS0Qa6",
      "category": "EQUIPMENT",
      "group": "Toolbox",
      "name": "John's Toolbox",
      "online": true,
      "assigned": {
        "inventory_id": "bK3aRMVna6",
        "section_id": "7Z9r7BRWA2"
      },
      "found": {
        "inventory_id": "bK3aRMVna6",
        "section_id": "7Z9r7BRWA2"
      }
    }
  ]
}

Returns the specified inventory area.

Request

GET api.velavu.com/inventories/.inventory_id

Create an Inventory Area

{
  "name": "Test area"
}

{
  "id": "bK3aRMVna6",
  "name": "Test area"
}

Creates a new inventory area.

Request

POST api.velavu.com/inventories

Request Parameters

Parameter	Type	Required	Description
name	string	true	Name of the inventory area

Update an Inventory Area

{
  "name": "Updated area name"
}

{
  "id": "bK3aRMVna6",
  "name": "Updated area name"
}

Modifies the specified inventory area.

Request

PATCH api.velavu.com/inventories/.inventory_id

Request Parameters

Parameter	Type	Required	Description
name	string	false	Name of the inventory area

Delete an Inventory Area

Deletes the specified inventory area.

Request

DELETE api.velavu.com/inventories/.inventory_id

Create a Section

{
  "name": "Section B",
  "anchor_id": "5kElf"
}

{
  "id": "9xK2pL8Wd5",
  "name": "Section B",
  "anchor_id": "5kElf"
}

Creates a new section within the specified inventory area.

Request

POST api.velavu.com/inventories/.inventory_id/sections

Request Parameters

Parameter	Type	Required	Description
name	string	true	Name of the section
anchor_id	string	false	ID of the anchor device to associate with this section

Update a Section

{
  "name": "Updated Section",
  "anchor_id": "newAnchorId"
}

{
  "id": "7Z9r7BRWA2",
  "name": "Updated Section",
  "anchor_id": "newAnchorId"
}

Modifies the specified section.

Request

PATCH api.velavu.com/inventories/.inventory_id/sections/.section_id

Request Parameters

Parameter	Type	Required	Description
name	string	false	Name of the section
anchor_id	string	false	ID of the anchor device to associate with this section

Delete a Section

Deletes the specified section.

Request

DELETE api.velavu.com/inventories/.inventory_id/sections/.section_id

Add Asset to Inventory

{
  "asset_id": "MAy3dS0Qa6",
  "section_id": "7Z9r7BRWA2"
}

{
  "id": "MAy3dS0Qa6",
  "category": "EQUIPMENT",
  "group": "Toolbox",
  "name": "John's Toolbox",
  "online": true,
  "assigned": {
    "inventory_id": "bK3aRMVna6",
    "section_id": "7Z9r7BRWA2"
  }
}

Adds an asset to the specified inventory area, optionally assigning it to a specific section.

Request

POST api.velavu.com/inventories/.inventory_id/assets

Request Parameters

Parameter	Type	Required	Description
asset_id	string	true	ID of the asset to add to the inventory
section_id	string	false	ID of the section to assign the asset to

Remove Asset from Inventory

Removes an asset from the specified inventory area.

Request

DELETE api.velavu.com/inventories/.inventory_id/assets/.asset_id

Backends

Backend Object

{
  "name": "New Backend",
  "config": {
    "host": "mqtt.example.com",
    "port": 1883,
    "username": "user",
    "password": "123456",
    "use_backend_api": true,
    "wirepas_config": {
      "network_addr": 1,
      "node_addr": 1,
      "network_chan": 9,
      "diag_interval_s": 1800
    },
    "upstream_eps": [
      {
        "wirepas_channel": 4,
        "mqtt_topic": "sensor/temperature"
      }
    ]
  }
}

The Backend object represents a configuration for transmitting and receiving data directly between a Wirepas Mesh network and a customer's own backend.

Property	Type	Description
id	string	Unique identifier for the object
name	string	Name of the backend
config.host	string	Endpoint of the MQTT broker
config.port	number	Port of the MQTT broker
config.username	string	Username for MQTT authentication
config.password	string	Password for MQTT authentication
config.wirepas_config.network_addr	number	Wirepas network address
config.wirepas_config.node_addr	Optional[number]	Sink address. If not specified, gateway will use its device ID
config.wirepas_config.network_chan	number	Wirepas default network channel
config.wirepas_config.diag_interval_s	number	Wirepas diagnostic interval. May be 0, 60, 120, 300, 600, or 1800
config.wirepas_config.auth_key	Optional[base64]	Wirepas authentication key
config.wirepas_config.encr_key	Optional[base64]	Wirepas encryption key
config.upstream_eps	list[dict]	Upstream channel-topic configurations
config.downstream_eps	list[dict]	Downstream channel-topic configurations
config.use_backend_api	bool	True if the device should publish and subscribe to Wirepas Backend API endpoints
certificates.ca_cert	base64	CA certificate for TLS authentication
certificates.server_cert	base64	Server certificate if using mutual TLS authentication
certificates.private_key	base64	Private key if using mutual TLS authentication

Get All Backends

[
  {
    "id": "M93t4Jz",
    "name": "New Backend",
    "config": {
      "host": "mqtt.example.com",
      "port": 1883,
      "username": "user",
      "password": "123456",
      "use_backend_api": true,
      "wirepas_config": {
        "network_addr": 1,
        "node_addr": 1,
        "network_chan": 9,
        "diag_interval_s": 1800
      },
      "upstream_eps": [
        {
          "wirepas_channel": 4,
          "mqtt_topic": "sensor/temperature"
        }
      ]
    }
  }
]

Returns all backends.

Request

GET api.velavu.com/backends

Get a Specific Backend

{
  "id": "M93t4Jz",
  "name": "New Backend",
  "config": {
    "host": "mqtt.example.com",
    "port": 1883,
    "username": "user",
    "password": "123456",
    "use_backend_api": true,
    "wirepas_config": {
      "network_addr": 1,
      "node_addr": 1,
      "network_chan": 9,
      "diag_interval_s": 1800
    },
    "upstream_eps": [
      {
        "wirepas_channel": 4,
        "mqtt_topic": "sensor/temperature"
      }
    ]
  }
}

Returns the specified backend.

Request

GET api.velavu.com/backends/.backend_id

Create a New Backend

{
  "name": "New Backend",
  "config": {
    "host": "mqtt.example.com",
    "port": 1883,
    "username": "user",
    "password": "123456",
    "wirepas_config": {
      "network_addr": 1,
      "network_chan": 9,
      "diag_interval_s": 0
    },
    "upstream_eps": [
      {
        "wirepas_channel": 4,
        "mqtt_topic": "sensor/temperature"
      }
    ]
  }
}

{
  "id": "M93t4Jz",
  "name": "New Backend",
  "config": {
    "host": "mqtt.example.com",
    "port": 1883,
    "username": "user",
    "password": "123456",
    "use_backend_api": false,
    "wirepas_config": {
      "network_addr": 1,
      "network_chan": 9,
      "diag_interval_s": 0
    },
    "upstream_eps": [
      {
        "wirepas_channel": 4,
        "mqtt_topic": "sensor/temperature"
      }
    ]
  }
}

Creates a new backend.

Request

POST api.velavu.com/backends

Request Parameters

Parameter	Type	Required	Description
name	string	true	Name of the backend
config.host	string	true	Endpoint of the MQTT broker
config.port	number	true	Port of the MQTT broker
config.username	string	false	Username for MQTT authentication
config.password	string	false	Password for MQTT authentication
config.wirepas_config.network_addr	number	true	Wirepas network address
config.wirepas_config.node_addr	number	false	Wirepas node address
config.wirepas_config.network_chan	number	true	Wirepas default network channel
config.wirepas_config.diag_interval_s	number	true	Wirepas diagnostic interval
config.wirepas_config.auth_key	base64	false	Wirepas authentication key
config.wirepas_config.encr_key	base64	false	Wirepas encryption key
config.upstream_eps	list[dict]	false	Upstream channel-topic configurations
config.downstream_eps	list[dict]	false	Downstream channel-topic configurations
config.use_backend_api	bool	false	Defaults to false
certificates.ca_cert	base64	false	CA certificate for TLS authentication
certificates.server_cert	base64	false	Server certificate if using mutual TLS authentication
certificates.private_key	base64	false	Private key if using mutual TLS authentication

Modify an Existing Backend

{
  "config": {
    "host": "mqtt.example.com",
    "port": 5000,
    "username": "user",
    "password": "123456",
    "wirepas_config": {
      "network_addr": 1,
      "node_addr": 1,
      "network_chan": 9,
      "diag_interval_s": 1800
    }
  }
}

{
  "id": "M93t4Jz",
  "name": "New Backend",
  "config": {
    "host": "mqtt.example.com",
    "port": 5000,
    "username": "user",
    "password": "123456",
    "use_backend_api": false,
    "wirepas_config": {
      "network_addr": 1,
      "node_addr": 1,
      "network_chan": 9,
      "diag_interval_s": 1800
    }
  }
}

Modifies the name, configuration, or certificates of the specified backend.

Request

PATCH api.velavu.com/backends/.backend_id

Request Parameters

Parameter	Type	Required	Description
name	string	false	Name of the backend
config.host	string	true	Endpoint of the MQTT broker
config.port	number	true	Port of the MQTT broker
config.username	string	true	Username for MQTT authentication
config.password	string	true	Password for MQTT authentication
config.wirepas_config.network_addr	number	true	Wirepas network address
config.wirepas_config.node_addr	number	false	Wirepas node address
config.wirepas_config.network_chan	number	true	Wirepas default network channel
config.wirepas_config.diag_interval_s	number	true	Wirepas diagnostic interval
config.wirepas_config.auth_key	base64	true	Wirepas authentication key
config.wirepas_config.encr_key	base64	true	Wirepas encryption key
config.upstream_eps	list[dict]	true	Upstream channel-topic configurations
config.downstream_eps	list[dict]	true	Downstream channel-topic configurations
config.use_backend_api	bool	false	Defaults to false
certificates.ca_cert	base64	false	CA certificate for TLS authentication
certificates.server_cert	base64	false	Server certificate if using mutual TLS authentication
certificates.private_key	base64	false	Private key if using mutual TLS authentication

Delete an Existing Backend

Deletes the specified backend.

Request

DELETE api.velavu.com/backends/.backend_id

Add a Device to a Backend

PUT api.velavu.com/backends/M93t4Jz/device/7HOYW

{
  "id": "M93t4Jz",
  "name": "New Backend",
  "config": {
    "host": "mqtt.example.com",
    "port": 5000,
    "username": "user",
    "password": "123456",
    "wirepas_config": {
      "network_addr": 1,
      "node_addr": 1
    },
    "upstream_eps": [
      {
        "wirepas_channel": 4,
        "mqtt_topic": "sensor/temperature"
      }
    ]
  },
  "devices": [
    {
      "status": "DISCONNECTED",
      "id": "7HOYW"
    }
  ]
}

Configures a device to connect to the specified backend.

Request

PUT api.velavu.com/backends/.backend_id/device/.device_id

Remove a Device from a Backend

DELETE api.velavu.com/backends/M93t4Jz/device/7HOYW

{
  "id": "M93t4Jz",
  "name": "New Backend",
  "config": {
    "host": "mqtt.example.com",
    "port": 5000,
    "username": "user",
    "password": "123456",
    "wirepas_config": {
      "network_addr": 1,
      "node_addr": 1
    },
    "upstream_eps": [
      {
        "wirepas_channel": 4,
        "mqtt_topic": "sensor/temperature"
      }
    ]
  }
}

Disconnects a device from the specified backend and removes its configuration.

Request

DELETE api.velavu.com/backends/.backend_id/device/.device_id

Users

User Object

{
  "email": "john@smith.com",
  "name": "John Smith",
  "status": "CONFIRMED",
  "settings": {
    "foo": "bar"
  },
  "profile_img_url": "https://s3.us-east-2.aws.com/image.png"
}

The User object represents a user within an organization.

Property	Type	Description
name	string	User's full name
email	string	User's email address
status	string	'FORCE_PASSWORD_CHANGE' if the user has been invited or 'CONFIRMED' if the user has logged in and changed their password
mapbox_token	string	Unique token for authenticating with the mapbox API
settings	Optional[dict]	Application-specific user settings
profile_img_url	Optional[string]	URL where the user's profile picture is stored

Get All Users

[
  {
    "email": "john@smith.com",
    "name": "John Smith",
    "status": "CONFIRMED",
    "mapbox_token": "pk.tokenstring",
    "settings": {
      "foo": "bar"
    },
    "profile_img_url": "https://s3.us-east-2.aws.com/image.png"
  },
  {
    "email": "barry@allen.com",
    "name": "Barry Allen",
    "status": "FORCE_PASSWORD_CHANGE",
    "mapbox_token": "pk.tokenstring"
  }
]

Returns all users.

Request

GET api.velavu.com/users

Register a New User

{
  "email": "john@smith.com",
  "name": "John Smith"
}

{
  "email": "john@smith.com",
  "name": "John Smith",
  "status": "FORCE_PASSWORD_CHANGE",
  "mapbox_token": "pk.tokenstring"
}

Creates a new user profile and sends an activation email to the specified address.

Request

POST api.velavu.com/users

Request Parameters

Property	Type	Required	Description
name	string	true	User's full name
email	string	true	User's email address

Get a Specific User

{
  "email": "john@smith.com",
  "name": "John Smith",
  "status": "CONFIRMED",
  "mapbox_token": "pk.tokenstring",
  "settings": {
    "foo": "bar"
  }
}

Returns the specified user's data.

Request

GET api.velavu.com/users/.email

Update a Specific Users' Settings

{
  "settings": {
    "foo": "bar"
  },
  "name": "John Smith the 3rd"
}

{
  "email": "john@smith.com",
  "name": "John Smith the 3rd",
  "status": "CONFIRMED",
  "mapbox_token": "pk.tokenstring",
  "settings": {
    "foo": "bar"
  }
}

Updates persistent settings for the specified user. The settings field must be a dictionary of key-value pairs.

Request

PUT api.velavu.com/users/.email

Request Parameters

Property	Type	Required	Description
settings	dict	false	Application-specific user settings
name	string	false	User's new name

Delete a Specific User

Deletes the specified user profile.

Request

DELETE api.velavu.com/users/.email

Upload a Profile Picture for a User

{
  "email": "john@smith.com",
  "name": "John Smith",
  "status": "CONFIRMED",
  "mapbox_token": "pk.tokenstring",
  "settings": {
    "foo": "bar"
  },
  "profile_img_url": "https://s3.us-east-2.aws.com/image.png"
}

Uploads a profile picture for the specified user.

Request

PUT api.velavu.com/users/.email/profile_img

The request body should be an image binary. The Content-Type header should be set to image/png or image/jpeg. Images are cropped to square and resized if larger than 1024 x 1024.

Delete a Profile Picture for a User

Deletes the profile picture for the specified user.

Request

DELETE api.velavu.com/users/.email/profile_img

MQTT Event Stream

Users wishing to obtain real-time updates from the Velavu backend without polling the REST API may connect to Velavu's AWS IoT MQTT broker.

The broker domain name is iot.velavu.com and port is 8883.

Client certificate & key pairs for connecting to the broker can be obtained from the 'Settings' area in the Velavu Web app. For security purposes, clients may only subscribe to topics prefixed with events\.customer_id\ where .customer_id is the unique customer ID associated with their account. (See GET /organizations) Subscribing to other topics or publishing data is not permitted by the broker's security policy. The Amazon root CA 1 certificate is also required to support TLS-encryption.

The Velavu backend publishes all database changes to the events topic in the following topic format: events/.customer_id/.table_name/.object_id/.operation_name. The payload contains the entire object in JSON format, as described in the REST API documentation.

Supported table names are events, assets, devices, sites, geofences, and rules.
Supported operation names are created, updated, deleted.

For example: A device with customer_id: VLV1 and id: Fw34K that performs a heartbeat update will publish the latest version of itself to events/VLV1/devices/Fw34K/updated.

MQTT Certificate Object

{
  "id": "91fa702c9b4c0265a1fa44248a73a22fc21a9d08f851eb219bb820c5045d5842",
  "name": "New consumer certificate",
  "created": "2024-12-17T18:15:16+00:00",
  "creator": "user@organization.com",
  "certificate_pem": "-----BEGIN CERTIFICATE-----\n ... -----END CERTIFICATE-----\n",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n ... -----END RSA PRIVATE KEY-----\n"
}

The Certificate object represents a x509 certificate that can be used to connect to Velavu's AWS IoT broker.

Property	Type	Description
id	string	Unique identifier for the object
name	string	Name assigned to the certificate
created	string	Timestamp when the certificate was created
creator	string	Email address of the user that created the certificate
certificate_pem	string	Client certificate in PEM format
private_key	string	Private key for the certificate

Get All MQTT Certificates

[
  {
    "id": "91fa702c9b4c0265a1fa44248a73a22fc21a9d08f851eb219bb820c5045d5842",
    "name": "New consumer certificate",
    "created": "2024-12-17T18:15:16+00:00",
    "creator": "user@organization.com"
  }
]

Returns all activated MQTT certificates.

Request

GET api.velavu.com/eventstream/certificates

Create an MQTT Certificate

{
  "name": "New consumer certificate"
}

{
  "id": "91fa702c9b4c0265a1fa44248a73a22fc21a9d08f851eb219bb820c5045d5842",
  "name": "New consumer certificate",
  "created": "2024-12-17T18:15:16+00:00",
  "creator": "user@organization.com",
  "certificate_pem": "-----BEGIN CERTIFICATE-----\n ... -----END CERTIFICATE-----\n",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n ... -----END RSA PRIVATE KEY-----\n"
}

Issues a new MQTT certificate.

Request

POST api.velavu.com/eventstream/certificates

Request Parameters

Property	Type	Required	Description
name	string	true	Name to identify the certificate

Delete an MQTT Certificate

Deactivates and deletes the specified MQTT certificate. Any clients using this certificate will be disconnected.

Request

DELETE api.velavu.com/eventstream/certificates/.certificate_id

Authorize MQTT for Cognito Users

Attaches the MQTT policy to the logged-in user's federated identity. Must be called when using Cognito authentication.

Request

POST api.velavu.com/eventstream/authorize/.identity

Alerts

Alert Object

{
  "id": "CNreBHF",
  "category": "ALERT",
  "event_category": "LOW_BATTERY",
  "timestamp": "2021-02-12T20:49:26+00:00",
  "device": {
    "id": "E7qVNeE",
    "serial_code": "f4-8d-e3-ce-d0-91",
    "model": "Vesta",
    "category": "TAG",
  },
  "asset": {
    "id": "JcOLj4X",
    "name": "Ford Focus RS",
    "group": "VEHICLE",
    "category": "CAR",
  },
  "data": {
    "battery_level": 18
  }
}

The Alert object represents an event that occurred that may interest the user. The format of an alert is very similar to that of an event. The type of event is reported in the event_category property, and the alert's data dict is the same as it would be for the corresponding event object.

Property	Type	Description
id	string	Unique identifier for the object
category	string	Always `ALERT`
event_category	string	Category of the event represented by the alert, see below for definitions
event_id	string	The ID of the associated event object (Not yet implemented)
timestamp	string	When the alert occurred
device	dict	The device associated with the alert
asset	Optional[dict]	The device's asset if one was paired at the time of the alert
data	Optional[dict]	Additional data about the event, based on the `event_category`

Get All Alerts

[
  {
    "id": "XUQp8RW",
    "timestamp": "2021-05-19T19:44:53+00:00",
    "category": "ALERT",
    "event_category": "CONNECT",
    "device": {
      "serial_code": "cd-e7-65-14-2a-07",
      "model": "Vesta",
      "category": "TAG",
      "id": "tVH1g"
    }
  },
  {
    "id": "0192urS",
    "timestamp": "2021-05-19T19:47:21+00:00",
    "category": "ALERT",
    "event_category": "LOW_BATTERY",
    "device": {
      "serial_code": "cd-e7-65-14-2a-07",
      "model": "Vesta",
      "category": "TAG",
      "id": "tVH1g"
    },
    "data": {
      "battery_level": 8
    }
  }
]

Returns all alerts.

Request

GET api.velavu.com/alerts

Query Parameters

Parameter	Required	Description
event_categories	false	Comma-separated string of event categories to filter

Delete a Single Alert

Deletes the specified alert.

Request

DELETE api.velavu.com/alerts/.alert_id

Delete All Alerts

Deletes all alerts.

Request

DELETE api.velavu.com/alerts

Query Parameters

Parameter	Required	Description
event_categories	false	Comma-separated string of event categories to filter

Organizations

Organization Object

{
  "name": "Brash",
  "settings": {"foo":"bar"},
  "customer_id": "DEFAULT",
  "subscription": {
    "status": "trialing",
    "start_date": "2023-10-18T14:48:11+00:00",
    "trial_end_date": "2023-10-23T14:48:11+00:00"
  },
  "meta": {
    "assets": {
      "categories": ["VEHICLE", "EQUIPMENT"],
      "groups": ["transit van", "forklift", "printer"],
      "category_groups": {
        "VEHICLE": ["transit van", "forklift"],
        "EQUIPMENT": ["printer"]
      }
    }
  }
}

An Organization object represents the organization to which a user belongs. All other objects (assets, devices, sites etc.) are tied to an organization defined by its customer id.

Property	Type	Description
name	string	Organization's name
settings	any	Client-defined organization-wide settings
subscription	Optional[Subscription]	Details of the customer's subscription, if one exists
meta	Optional[Metadata]	Organization metadata
customer_id	string	Organization's unique ID

Subscription Object

Property	Type	Description
status	string	Subscription status, one of `active`, `trialing`, or `paused`
start_date	string	Timestamp when the subscription was started
trial_end_date	Optional[string]	Timestamp when the trial ends, if status is `trialing`

Metadata Object

Property	Type	Description
assets.categories	list(string)	Categories in-use for assets in the system
assets.groups	list(string)	Groups in-use for assets in the system
assets.category_groups	dict	Category-group associations
devices.models	list(string)	Device models in-use by this customer

Get Organization Details

{
  "name": "Brash",
  "settings": {"foo":"bar"},
  "customer_id": "DEFAULT"
}

Returns details about the current user's organization.

Request

GET api.velavu.com/organization

Update Organization Details

{
  "name": "New Name"
}

{
  "name": "New Name",
  "settings": {"foo":"bar"},
  "customer_id": "DEFAULT"
}

Modifies the organization's name or settings.

Request

PATCH api.velavu.com/organization

Request Parameters

Property	Type	Required	Description
name	string	false	Organization's name
settings	any	false	Client-defined organization-wide settings

API Tokens

Token Object

{
  "id": "HZsQTE3",
  "token": "UIqJqUl0DqOOecbu24ANn38GpFh4ETgETTnHrabDnTwT",
  "name": "new token",
  "created": "2021-05-19T21:32:29+00:00",
  "expiry": "2021-06-19T21:32:29+00:00",
  "creator": "hello@velavu.com"
}

A Token object represents an access token that can be used to authenticate API requests.

Property	Type	Description
id	string	Unique identifier for the object
token	Optional[string]	Bearer token to be used for authentication
name	string	Name given to the token
creator	string	Email of the user who created this token
created	string	Timestamp when the token was created
expiry	Optional[string]	Timestamp when the token will expire

Get all Tokens

{
  "id": "avZRYLa",
  "name": "Dev client token",
  "created": "2021-05-19T21:32:29+00:00",
  "creator": "dominic@velavu.com"
},
{
  "id": "HZsQTE3",
  "name": "Another token",
  "created": "2021-05-19T21:32:29+00:00",
  "expiry": "2021-06-19T21:32:29+00:00",
  "creator": "hello@velavu.com"
}

Returns all API tokens.

Request

GET api.velavu.com/tokens

Create a new Token

{
  "name": "new token",
  "expiry": "2021-06-19T21:32:29+00:00"
}

{
  "id": "HZsQTE3",
  "token": "UIqJqUl0DqOOecbu24ANn38GpFh4ETgETTnHrabDnTwT",
  "name": "new token",
  "created": "2021-05-19T21:32:29+00:00",
  "expiry": "2021-06-19T21:32:29+00:00",
  "creator": "hello@velavu.com"
}

Creates a new authentication token.

Request

POST api.velavu.com/tokens

Request Parameters

Parameter	Type	Required	Description
name	string	true	Human-readable name to identify the token
expiry	string	false	Timestamp when the token will expire. Must be ISO8601 format and later than the current time

Delete a token

Deletes the specified authentication token.

Request

DELETE api.velavu.com/tokens/.token_id

Invoices

Invoice Object

{
  "id": "in_1O30D8JKCeJtD3tSilNowwwv",
  "period_start": "2023-04-19T22:43:35+00:00",
  "period_end": "2023-04-19T22:43:35+00:00",
  "usage": [
    {
      "product": "Velavu Subscription - Pavo",
      "quantity": 50,
      "unit_price": 100,
      "line_total": 5000
    },
    {
      "product": "Velavu Subscription - Vesta",
      "quantity": 2,
      "unit_price": 2000,
      "line_total": 4000
    }
  ],
  "status": "paid",
  "total": 9000,
  "payment_url": "https://invoice.stripe.com",
  "invoice_pdf": "https://pay.stripe.com/invoice"
}

The Invoice object represents a Stripe invoice that is generated at the end of each month to bill for Velavu's service charges.

Property	Type	Description
id	Optional[string]	Unique identifier for the object
period_start	string	Time when the billing period started
period_end	string	Time when the billing period ends
usage	list[dict]	List of model name and quantities billed in this invoice
usage.product	string	Subscription line item name
usage.quantity	number	Number of units of this product billed this month
usage.unit_price	number	Price per device per month in USD cents
usage.line_total	number	Line total in USD cents
status	string	May be one of `draft`, `open`, `paid`, `void`, or `uncollectible`
total	number	Total invoice amount in USD cents
payment_url	Optional[string]	URL containing a payment page for the invoice
invoice_pdf	Optional[string]	URL to download the invoice as a PDF

Get all Invoices

[
  {
    "id": "in_1O30D8JKCeJtD3tSilNowwwv",
    "period_start": "2023-04-19T22:43:35+00:00",
    "period_end": "2023-04-19T22:43:35+00:00",
    "usage": [
      {
        "product": "Velavu Subscription - Pavo",
        "quantity": 0,
        "unit_price": 100,
        "line_total": 0
      },
      {
        "product": "Velavu Subscription - Vesta",
        "quantity": 0,
        "unit_price": 2000,
        "line_total": 0
      }
    ],
    "status": "paid",
    "total": 0,
    "payment_url": "https://invoice.stripe.com",
    "invoice_pdf": "https://pay.stripe.com/invoice"
  }
]

Returns all invoices.

Request

GET api.velavu.com/invoices

Get the Upcoming Invoice

{
  "period_start": "2023-04-19T22:43:35+00:00",
  "period_end": "2023-04-19T22:43:35+00:00",
  "usage": [
    {
      "product": "Velavu Subscription - Pavo",
      "quantity": 50,
      "unit_price": 100,
      "line_total": 5000
    },
    {
      "product": "Velavu Subscription - Vesta",
      "quantity": 2,
      "unit_price": 2000,
      "line_total": 4000
    }
  ],
  "status": "draft",
  "total": 9000
}

Returns a draft of the upcoming invoice for the current billing cycle.

Request

GET api.velavu.com/invoices/upcoming

Device Models

DeviceModel Object

{
    "name": "Pavo",
    "hardware": "meridian",
    "manufacturer": "Velavu",
    "categories": [
        "TAG"
    ],
    "model_id": 2,
    "indicator": "buzzer",
    "images": {
        "hero": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/hero.png",
        "icon": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/icon.svg",
        "thumbnail": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/thumbnail.png"
    }
}

The DeviceModel object stores the required information to display a device correctly in the Velavu Web and Mobile apps.

Property	Type	Description
name	string	Externally visible unique name that matches the `device.model` field
hardware	string	Internal name matching the device.hardware field. Two or more models may share the same hardware
manufacturer	string	Name of the model manufacturer
categories	List[string]	List of possible device categories for this hardware
images.icon	string	URL to the device icon in SVG format
images.thumbnail	string	URL to the device thumbnail (144x144)
images.hero	string	URL to the device hero image (1250x1250)
model_id	Optional[number]	Model association with the model_id found in Velavu QR codes and Velavu NFC tags
indicator	Optional[string]	Represents the type of indication expected when you call `POST /devices/.device_id/indicate`. May be `led` or `buzzer`. If the property does not exist, the device does not have any indicate capabilities

Get all Device Models

[
    {
        "name": "Vesta",
        "hardware": "argo",
        "manufacturer": "Velavu",
        "categories": [
            "TAG"
        ],
        "images": {
            "effect-focus": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/effect-focus.png",
            "effect-hover": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/effect-hover.png",
            "fixed": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/fixed.png",
            "hero": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/hero.png",
            "icon": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/icon.svg",
            "mobile": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/mobile.png",
            "offline": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/offline.png",
            "registered": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/registered.png",
            "thumbnail": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/thumbnail.png"
        }
    },
    {
        "name": "Pavo",
        "hardware": "meridian",
        "manufacturer": "Velavu",
        "categories": [
            "TAG",
            "ANCHOR"
        ],
        "images": {
            "effect-focus": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/effect-focus.png",
            "effect-hover": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/effect-hover.png",
            "fixed": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/fixed.png",
            "hero": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/hero.png",
            "icon": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/icon.svg",
            "mobile": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/mobile.png",
            "offline": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/offline.png",
            "registered": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/registered.png",
            "thumbnail": "https://velavupublic-dev.s3.amazonaws.com/img/model/Pavo/thumbnail.png"
        }
    }
]

Returns all device models.

Request

GET api.velavu.com/devicemodels

Get a Specific Device Model

{
    "name": "Vesta",
    "hardware": "argo",
    "manufacturer": "Velavu",
    "categories": [
        "TAG"
    ],
    "images": {
        "effect-focus": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/effect-focus.png",
        "effect-hover": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/effect-hover.png",
        "fixed": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/fixed.png",
        "hero": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/hero.png",
        "icon": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/icon.svg",
        "mobile": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/mobile.png",
        "offline": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/offline.png",
        "registered": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/registered.png",
        "thumbnail": "https://velavupublic-dev.s3.amazonaws.com/img/model/Vesta/thumbnail.png"
    }
}

Returns the specified device model.

Request

GET api.velavu.com/devicemodels/.model_name

Integrations

Integrations Object

{
  "mappedin": {
    "api_key": "mik_yANQUgEVdu3RbPM9E53af072c",
    "token": "{JWT token}",
    "imports": [
      {
        "site_id": "6UQdYNgBdK",
        "venue_id": "690ac52c1992d4000bc55edf"
      }
    ]
  }
}

The Integrations object stores configurations related to different integrations with the Velavu backend.

Property	Type	Description
mappedin	dict	Contains the API key and list of imports for the MappedIn integration

Get Integrations

{
  "mappedin": {
    "api_key": "mik_yANQUgEVdu3RbPM9E53af072c",
    "token": "{JWT token}",
    "imports": [
      {
        "site_id": "6UQdYNgBdK",
        "venue_id": "690ac52c1992d4000bc55edf"
      }
    ]
  }
}

Returns all integrations.

Request

GET api.velavu.com/integrations

Add MappedIn Integration

{
  "api_key": "mik_yANQUgEVdu3RbPM9E53af072c",
  "secret": "sk_XXXXXXXXXXXXXXXX"
}

{
  "mappedin": {
    "api_key": "mik_yANQUgEVdu3RbPM9E53af072c",
    "token": "{JWT token}",
    "imports": []
  }
}

Stores MappedIn credentials, enabling the MappedIn integration.

Request

POST api.velavu.com/integrations/mappedin

Error Reason Codes

Code	Description
ERR_INVALID_MP_TOKEN	The provided credentials are incorrect

Remove MappedIn Integration

Deletes MappedIn credentials, removing the MappedIn integration.

Request

DELETE api.velavu.com/integrations/mappedin

Get MappedIn Venues

[
  {
    "id": "690ac52c1992d4000bc55edf",
    "name": "Test Venue"
  }
]

Queries the MappedIn API and returns a list of available venues.

Request

GET api.velavu.com/integrations/mappedin/venues

Import a MappedIn Venue

{
  "mappedin": {
    "api_key": "mik_yANQUgEVdu3RbPM9E53af072c",
    "token": "{JWT token}",
    "imports": [
      {
        "site_id": "6UQdYNgBdK",
        "venue_id": "690ac52c1992d4000bc55edf"
      }
    ]
  }
}

Imports a MappedIn venue as a Velavu site.

Request

POST api.velavu.com/integrations/mappedin/venues/.venue_id/import

Response Codes

Parameter	Description
200	The venue was imported successfully
400	MappedIn integration is not set up
404	The venue does not exist

Disconnect a MappedIn Venue

Disconnects a previously imported MappedIn venue from its Velavu site.

Request

POST api.velavu.com/integrations/mappedin/venues/.venue_id/disconnect

Velavu API Documentation

REST API

Authentication

Pagination

Pagination Query Parameters

Pagination Response Headers

Assets

Asset Object

Get All Assets

Request

Query Parameters

Create a New Asset

Request

Request Parameters

Get a Specific Asset

Request

Modify a Specific Asset

Request

Request Parameters

Unpair a Device from an Asset

Request

Delete a Specific Asset

Request

Upload a Profile Picture for an Asset

Request

Delete a Profile Picture for an Asset

Request

Asset Routes

Asset Route Object

Get All Routes

Request

Query Parameters

Get a Specific Route

Annotations Properties

Request

Delete a Specific Route

Request

Devices

Device Object

Device Types

Device argo

Device juno

Device pisces

Device meridian

Environment Object

Location Object

Get All Devices

Request

Query Parameters

Get a Specific Device

Request

Get Available Device by ID or Serial Code

Request

Query Parameters

Response Properties

Response Codes

Register an Available Device

Request

Request Parameters

Create a New Device

Request

Request Parameters

Modify a Specific Device

Request

Request Parameters

Supported State Updates:

Delete a Specific Device

Request

Remove a Specific Device's Location

Request

Disable Automatic Firmware Updates for a Device

Request

Reboot a Specific Device

Request

Request Position of a Specific Device

Request

Indicate a Specific Device

Request

Request Body Parameters

Device Firmware Update (DFU)

Device `argo`

Device `juno`

Device `pisces`

Device `meridian`