Velavu API Documentation

You've made it to the Velavu documentation! This page is under development and any questions can be forwarded to support@velavu.com

REST API

This section describes the Velavu REST API.

Please note that for any response property that has a None type, you should use a safe accessor such as dict.get('key') as the property will be omitted from the response if its value is None.

Authentication

Requests are authenticated via a Bearer token in the Authentication 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' or 'VEHICLE'
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"
  }
]

This endpoint retrieves all assets.

Request

GET api.velavu.com/assets

Query Parameters

Parameter	Required	Description
include_profile_images	false	Whether to return an 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"
}

This creates a new Asset object.

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` or `EQUIPMENT`
group	string	true	The asset's type
notes	string	false	Optional field to contain notes the user may want to include with an 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"
}

This request returns the entire data of a requested asset.

Request

GET api.velavu.com/assets/.asset_id

Modify a Specific Asset

{
  "name": "Focus"
}

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

This endpoint modifies one or more properties of the 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` or `EQUIPMENT`
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	Information the user may want to store about an asset

Delete a Specific Asset

This method deletes a specific 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"
}

This method 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

This method deletes an 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 ended
data.location_start	string	Location that driving ended
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 started
data.location_stop	Optional[string]	Location that driving started
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?"
    }
  }
]

This method returns all of an asset's routes.

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"
      }
    ]
  }
}

This method returns a single route of an asset. It includes a list of annotations which are properties that correspond to specific points in 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

This method deletes a specific 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>
}

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 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 deivce
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

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
  },
  "gnss": {
   "sats_in_view": 11,
   "snr": 29,
   "valid_fix": true
  },
  "led_flash_on": false,
  "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.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
led_flash_on	bool	True if the internal LED flashing sequence is enabled

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
buzzer_on	bool	True if the locating buzzer is active
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",
  "buzzer_on": false,
  "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
buzzer_on	bool	True if the locating buzzer is active
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

Proximity Object

Property	Type	Description
device_id	string	The unique identifier of the nearby device
timestamp	string	Time that the device was last seen
distance	number	Proximity in meters to the device

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

Mesh Location

{
  "location_type": "MESH",
  "coordinates": [-75.36125, 45.61251],
  "timestamp": "2021-03-08T14:53:52+00:00", 
  "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
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", 
  "distance": 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
distance	number	Proximity in meters to the device specified by `device_id`
device_id	string	The signal strength of this device is measured and converted to `distance`

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", 
  "distance": 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
distance	number	Estimated position accuracy

WiFi Location

{
  "location_type": "WIFI",
  "coordinates": [
    -75.694817,
    45.432766
  ],
  "timestamp": "2021-03-08T14:53:52+00:00", 
  "distance": 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
distance	number	Estimated position accuracy

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
      }
    }
  }
]

This method returns all of a customer's 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. Can not be used in conjunction with `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,
      "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"
}

This request allows you to retrieve all stored data for a single device.

Request

GET api.velavu.com/devices/.device_id

Get Available Device by ID or Serial Code

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

This method allows you to query a device by ID or serial code. This is useful for finding a device whose device ID is unknown or seeing if a device can be registered to the user 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 customer, else False

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
  }
}

This request allows you to register an existing available device to a customer.

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	Information the user may want to store about a 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
  }
}

This request allows you to register a new device that does not exist in the Velavu backend.

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	Information the user may want to store about a 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"
}

This endpoint modifies one or more properties of the 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	Information the user may want to store about a 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

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

This method makes a device become unlocked and sends a factory reset command to the device. If the device is preprogrammed to a customer, it will self-provision to that customer's account again.

Request

DELETE api.velavu.com/devices/.device_id

Remove a Specific Device's Location

This method removes the location from a specific device.

Request

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

Reboot a Specific Device

This method sends a command to the device which makes it reboot and reconnect to the network.

Request

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

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",
  "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
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",
    "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",
    "comment": "stability improvements",
    "release_date": "2021-05-12T23:38:58+00:00"
  }
]

This method returns compatible DFU images for a device.

Request

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

DFU allows the firmware of standalone device to be remotely updated. When a new firmware image is built, the build tool uploads it to a S3 bucket. A client can call this request to obtain a list of firmware images that are compatible with the selected device.

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"
    }
  }
]

This method 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"
  }
}

This method creates a device firmware update request.

Request

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

The device firmware name should match a name returned by the GET dfu/device/.device_id/images request. 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

This method deletes a 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",
  "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
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",
    "comment": "First release",
    "release_date": "2021-05-12T23:38:58+00:00",
    "crc": 15788
  }
]

This method returns OTAP images that may be loaded to a gateway device.

Request

GET api.velavu.com/otap/images

Any gateway can load any OTAP image, so it is up to the client to decide which OTAP image should be used. A good strategy is to consider the devices that are online and routing via gateway_id, then send a OTAP request that matches those devices to gateway_id.

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"
    }
  }
]

This method returns all OTAP requests.

Request

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

Create a 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
  }
}

This method creates a OTAP update request.

Request

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

The name property should match a name returned by the GET otap/images request. 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 a OTAP Request

This method deletes a 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

{
  "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"
  }
]

This endpoint retrieves 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"
}

This endpoint retrieves a single rule by its ID.

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"
}

This creates a new rule object.

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

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

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"
}

This modifies an existing rule object.

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

This method deletes a 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 ended
data.location_start	string	Location that driving ended
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 started
data.location_stop	Optional[string]	Location that driving started
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
    }
  }
]

This method returns all events associated with an asset or device.

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
    }
  }
]

This method queries several "essential" event categories and returns the combined result.

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

This method deletes all of a device's or asset's events.

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	true
level	number	true
geometry.walls	dict	true
img		false

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 Floor object represents a floor inside a building.

Property	Type	Description
id	string	Unique identifier for the object
name	string	true
level	number	true
geometry.walls	dict	true
img		false

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
  }
]

This method returns all of an organization's 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
}

This method returns a single site by its unique ID.

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
}

This method 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
  ]
}

This method modifies the name or perimeter coordinates of a 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

This method deletes an existing 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>,
}

This method creates a new floor in an existing 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>,
}

This method updates a floor in an existing 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

This method deletes a site floor by its ID.

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>,
}

This method uploads a floorplan image.

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

This method deletes a floorplan image

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"
}

This method sets the OTAP image that will propagate for all gateways inside this 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

This method unsets the target OTAP image and disables OTAP for all gateways inside this 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"
    }
}

This method creates a BLE scan request in a 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 can be used to detect standard BLE tags using devices like the Velavu Dorado which are capable of BLE scanning. When issusing a BLE scan request to a site, the system determines how many devices exist inside that site that are capable of BLE scanning and stores that in the data.pending_response_count. Each device's scan is stored in the backend until the data.pending_response_count reaches zero or the 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
          ]
        ]
      ]
    }
  }
]

This method returns all of an organization's 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
        ]
      ]
    ]
  }
}

This method returns a single geofence by its unique ID.

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
        ]
      ]
    ]
  }
}

This method creates a new geofence zone.

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
        ]
      ]
    ]
  }
}

This method modifies the name or boundary of a 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

This method deletes an existing geofence.

Request

DELETE api.velavu.com/geofences/.geofence_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"
        }
      ]
    }
  }
]

This method returns all of an organization's 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"
      }
    ]
  }
}

This method returns a single backend by its unique ID.

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"
      }
    ]
  }
}

This method creates a new backend configuration.

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
    }
  }
}

This method modifies the name, configuration, or certificates of a 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

This method deletes an existing backend.

Request

DELETE api.velavu.com/backends/.backend_id

Add a Device to a Backend

PUT 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"
    }
  ]
}

This method configures a device to connect to the backend.

Request

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

Remove a Device from a Backend

DELETE 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"
      }
    ]
  }
}

This method removes the configuration and disconnects a device from the backend.

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"
  }
]

This method returns all of an organization's 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"
}

This request creates a new user profile and sends a profile activation email to their email.

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"
  }
}

This request retrieves a single 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"
  }
}

This method can be used to save persistent user settings that are relevant to the application. Settings 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

This method deletes a 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"
}

This method uploads a profile picture for a 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

This method deletes a person's profile image.

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	Always `ALERT`
created	string	Creation time of the certificate
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"
  }
]

This method 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"
}

This method 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

This method deactivates and deletes an MQTT certificate. Any clients using this certificate will be disconnected.

Request

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

Authorize MQTT for Cognito Users

This method must be called when using cognito authentication in order to attach the MQTT policy to the logged-in user's federated identity.

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
    }
  }
]

This method returns all of an organization's 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

This method deletes a single alert

Request

DELETE api.velavu.com/alerts/.alert_id

Delete All Alerts

This method deletes all of an organization's 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"
}

This method returns information about the organization to which the current user belongs

Request

GET api.velavu.com/organization

Update Organization Details

{
  "name": "New Name"
}

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

This method allows the user's organization name to be modified.

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"
}

This method returns all tokens associated with a customer account.

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"
}

This method 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

This method deletes an 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"
  }
]

This method returns all invoices associated with a customer.

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
}

This method returns a draft of the upcoming invoice for this 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"
        }
    }
]

This method 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"
    }
}

This method returns a specific device model.

Request

GET api.velavu.com/devicemodels/.model_name

Integrations

Integrations Object

{
  "mappedin": {
    "api_key": "mik_yANQUgEVdu3RbPM9E53af072c",
    "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",
    "imports": [
      {
        "site_id": "6UQdYNgBdK",
        "venue_id": "690ac52c1992d4000bc55edf"
      }
    ]
  }
}

This method returns all integrations.

Request

GET api.velavu.com/integrations

Add MappedIn Integration

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

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

This method stores the MappedIn credentials in Velavu's backend, enabling the MappedIn Integration.

Request

POST api.velavu.com/integrations/mappedin

Response Codes

Parameter	Description
200	The integration was set up successfully
403	The provided credentials are incorrect

Remove MappedIn Integration

This method deletes the MappedIn credentials in Velavu's backend, removing the MappedIn Integration.

Request

DELETE api.velavu.com/integrations/mappedin

Get MappedIn Venues

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

This method queries the MappedIn API and returns a list of MappedIn venues.

Request

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

Import a MappedIn Venue

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

This method 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 exist

Disconnect a MappedIn Venue

This method disconnects a previously imported 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

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

Proximity Object

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

Reboot a Specific Device

Request

Device Firmware Update (DFU)

DFU Image Object

DFU Request Object

Get DFU images for a Device

Request

Get all DFU Requests

Request

Create a DFU Request

Request

Device `argo`

Device `juno`

Device `pisces`

Device `meridian`