Velavu
API docs by Redocly

Velavu API (2026-10)

Download OpenAPI specification:

Velavu Support: support@velavu.com

The Velavu REST API manages the assets, devices, sites, rules and event history in a Velavu organization. For questions or support, contact support@velavu.com.

Conventions

Base URL. All paths are relative to https://api.velavu.com.

Omitted fields. Properties whose value is null, an empty list or an empty object are left out of responses rather than returned as null. Read optional properties with a safe accessor (for example obj.get("key") in Python). Fields marked optional in a schema may be absent for this reason.

Timestamps are ISO 8601 strings in UTC, for example 2026-10-26T17:03:22+00:00.

Coordinates are [longitude, latitude], matching GeoJSON.

IDs. Most objects have a short random ID such as HQojZMGKuF. Device IDs are the 5 character IDs printed on the device (00000, A0363). User IDs are email addresses.

Empty responses. Operations that do not return an object (deletes and device commands) respond 200 with the JSON body null.

Authentication

Every request needs an Authorization: Bearer <token> header. The token is either:

  • an API token created with POST /tokens, or
  • the ID token (JWT) returned by Velavu's Cognito sign-in, which is what the Velavu web app uses.

A request that is missing a valid token is rejected with 401. A valid token without the permission an operation needs is rejected with 403.

Roles and Permissions

Every user and API token has a role. A role grants a fixed set of fine-grained permissions such as assets:write or devices:control, and each operation in this reference lists the permission it requires. Roles are cumulative: each role has every permission of the role to its left.

Role Description
VIEWER Read-only access to most resources. Can only change their own user settings.
OPERATOR Viewer, plus create/delete assets, delete alerts and control devices.
SITE_MANAGER Operator, plus manage sites, geofences, rules, integrations and devices, and read DFU/OTAP images.
ADMIN Every permission, including organization, billing, user and API token management.
Permission VIEWER OPERATOR SITE_MANAGER ADMIN
alerts:delete ✓ ✓ ✓
alerts:read ✓ ✓ ✓ ✓
api-tokens:delete ✓
api-tokens:read ✓
api-tokens:write ✓
assets:delete ✓ ✓ ✓
assets:read ✓ ✓ ✓ ✓
assets:write ✓ ✓ ✓
backends:delete ✓
backends:read ✓ ✓ ✓ ✓
backends:write ✓
billing:read ✓
devices:control ✓ ✓ ✓
devices:delete ✓
devices:manage ✓ ✓
devices:read ✓ ✓ ✓ ✓
devices:write ✓ ✓
dfu:read ✓ ✓
dfu:write ✓ ✓
events:delete ✓
events:read ✓ ✓ ✓ ✓
geofences:delete ✓ ✓
geofences:read ✓ ✓ ✓ ✓
geofences:write ✓ ✓
integrations:read ✓ ✓ ✓ ✓
integrations:write ✓ ✓
inventories:delete ✓ ✓
inventories:manage ✓ ✓ ✓
inventories:read ✓ ✓ ✓ ✓
inventories:write ✓ ✓
mqtt:authorize ✓ ✓ ✓ ✓
mqtt:delete ✓
mqtt:read ✓ ✓ ✓ ✓
mqtt:write ✓
organization:read ✓ ✓ ✓ ✓
organization:write ✓
otap:read ✓
otap:write ✓
rules:delete ✓ ✓
rules:read ✓ ✓
rules:write ✓ ✓
rules:write-config ✓
sites:delete ✓ ✓
sites:manage ✓ ✓
sites:read ✓ ✓ ✓ ✓
sites:write ✓ ✓
users:delete ✓ ✓
users:read ✓ ✓ ✓ ✓
users:write ✓ ✓
users:write-self ✓ ✓ ✓ ✓
vitalguard:respond ✓ ✓ ✓

Pagination

List operations that can return many objects are paginated. They accept limit and continuation_token query parameters. When more results are available the response carries two headers:

Header Description
X-Continuation-Token Pass this as continuation_token to fetch the next page.
X-Next-Link The full URL of the next page.

When neither header is present you have reached the last page. limit defaults to and may not exceed 250 for object lists, and 1000 for event lists. A larger limit is rejected with 400. Events are always returned newest first.

Errors

Errors are returned as a JSON object with a message, and sometimes a machine-readable reason:

{"message": "Device by the key {'customer_id': 'swJd', 'id': 'X0000'} does not exist."}
Status Meaning
400 The request was invalid. Validation failures from query or body parsing return the validator's message.
401 Missing or invalid token.
403 The token lacks the required permission, or the object belongs to another organization.
404 The object does not exist.
500 Unexpected server error.

MQTT Event Stream

Clients that want real-time updates instead of polling can subscribe to Velavu's MQTT broker at iot.velavu.com:8883. Create a client certificate with POST /eventstream/certificates and use the Amazon Root CA 1 for TLS.

Clients may only subscribe to topics under events/<customer_id>/, where customer_id is returned by GET /organization. Publishing is not permitted. Every database change is published to:

events/<customer_id>/<table>/<object_id>/<operation>

table is one of events, assets, devices, sites, geofences or rules; operation is created, updated or deleted. The payload is the full object as JSON, in the same shape as the REST API returns it. For example, a heartbeat from device Fw34K publishes the updated device to events/VLV1/devices/Fw34K/updated.

Assets

Assets are the people, vehicles and equipment being tracked. An asset is located through the device paired to it.

List assets

Required permission: assets:read (role VIEWER or higher)

Authorizations:
bearerAuth
query Parameters
name
string

Only assets whose name starts with this value (case-sensitive).

category
string (AssetCategory)
Enum: "VEHICLE" "EQUIPMENT" "PERSON"
group
string

Only assets in this group (exact match).

paired
boolean

true for assets with a paired device, false for assets without one.

online
boolean

Filter by the paired device's online status.

only_registered
boolean

With true (and no online filter), only assets whose device has never reported an online status.

include_profile_images
boolean
Default: false

Include profile_img_url on each asset.

limit
integer [ 1 .. 250 ]
Default: 250

Maximum number of objects to return.

continuation_token
string

The X-Continuation-Token header from the previous page.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "HQojZMGKuF",
    • "category": "PERSON",
    • "group": "Doctor",
    • "name": "Sarah Davis",
    • "device_id": "00000",
    • "online": true
    }
]

Create an asset

Required permission: assets:write (role OPERATOR or higher)

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
category
required
string (AssetCategory)
Enum: "VEHICLE" "EQUIPMENT" "PERSON"
group
required
string

Free-form group within the category, for example Doctor.

notes
string
device_id
string

Pair this device with the new asset. The device must not already be paired.

Responses

Request samples

Content type
application/json
{
  • "name": "Sarah Davis",
  • "category": "PERSON",
  • "group": "Doctor",
  • "device_id": "00000"
}

Response samples

Content type
application/json
{
  • "id": "HQojZMGKuF",
  • "category": "PERSON",
  • "group": "Doctor",
  • "name": "Sarah Davis",
  • "device_id": "00000",
  • "online": true
}

Get an asset

Required permission: assets:read (role VIEWER or higher)

Authorizations:
bearerAuth
path Parameters
asset_id
required
string
Example: HQojZMGKuF

Responses

Response samples

Content type
application/json
{
  • "id": "HQojZMGKuF",
  • "category": "PERSON",
  • "group": "Doctor",
  • "name": "Sarah Davis",
  • "device_id": "00000",
  • "online": true
}

Update an asset

Required permission: assets:write (role OPERATOR or higher)

Only the fields you send are changed. Send device_id to pair a device; use unpair to remove one.

Authorizations:
bearerAuth
path Parameters
asset_id
required
string
Example: HQojZMGKuF
Request Body schema: application/json
required
name
string
category
string (AssetCategory)
Enum: "VEHICLE" "EQUIPMENT" "PERSON"
group
string
notes
string
device_id
string

Responses

Request samples

Content type
application/json
{
  • "notes": "Night shift"
}

Response samples

Content type
application/json
{
  • "id": "HQojZMGKuF",
  • "category": "PERSON",
  • "group": "Doctor",
  • "name": "Sarah Davis",
  • "device_id": "00000",
  • "online": true
}

Delete an asset

Required permission: assets:delete (role OPERATOR or higher)

Deletes the asset and unpairs its device.

Authorizations:
bearerAuth
path Parameters
asset_id
required
string
Example: HQojZMGKuF

Responses

Response samples

Content type
application/json
null

Unpair the asset's device

Required permission: assets:write (role OPERATOR or higher)

Authorizations:
bearerAuth
path Parameters
asset_id
required
string
Example: HQojZMGKuF

Responses

Response samples

Content type
application/json
{
  • "id": "HQojZMGKuF",
  • "category": "PERSON",
  • "group": "Doctor",
  • "name": "Sarah Davis",
  • "device_id": "00000",
  • "online": true
}

Upload a profile picture

Required permission: assets:write (role OPERATOR or higher)

Authorizations:
bearerAuth
path Parameters
asset_id
required
string
Example: HQojZMGKuF
Request Body schema: application/json
required
image
required
string^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-...

The image file, base64-encoded.

Responses

Request samples

Content type
application/json
{
  • "image": null
}

Response samples

Content type
application/json
{
  • "id": "HQojZMGKuF",
  • "category": "PERSON",
  • "group": "Doctor",
  • "name": "Sarah Davis",
  • "device_id": "00000",
  • "online": true
}

Delete the profile picture

Required permission: assets:delete or assets:write (role OPERATOR or higher)

Authorizations:
bearerAuth
path Parameters
asset_id
required
string
Example: HQojZMGKuF

Responses

Response samples

Content type
application/json
null

Devices

Tags, anchors and gateways in the organization.

A device's config and state objects depend on its hardware type. Pick a hardware type in the Device schema below to see the fields that type's firmware reports.

List devices

Required permission: devices:read (role VIEWER or higher)

Authorizations:
bearerAuth
query Parameters
id
string

Only devices whose ID starts with this value.

category
string (DeviceCategory)
Enum: "TAG" "ANCHOR"
hardware
string (DeviceHardware)
Enum: "argo" "meridian" "generic" "panicbutton" "juno" "aries"

Firmware family running on the device. Determines the shape of config and state. Device models map to hardware types, for example Vesta → argo, Pavo HD → meridian, Mokosmart L02 → generic and Mokosmart B5 → panicbutton; see Device Models.

model
string
Example: model=Pavo HD

Only devices of this model (exact match).

site_id
string

Only devices inside this site. Results are not paginated when filtering by site.

geofence_id
string

Only devices inside this geofence.

bbox
string
Example: bbox=-79.37,43.67,-79.36,43.69

Only devices inside this bounding box, as sw_lon,sw_lat,ne_lon,ne_lat. Requires category.

paired
boolean

true for devices paired to an asset, false for unpaired devices.

online
boolean
only_registered
boolean

With true (and no online filter), only devices that have never reported an online status.

config_confirmed
boolean

false returns devices with a configuration change still pending.

limit
integer [ 1 .. 250 ]
Default: 250

Maximum number of objects to return.

continuation_token
string

The X-Continuation-Token header from the previous page.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "V0000",
    • "serial_code": "sw:Jd:00:00:00:1F",
    • "category": "TAG",
    • "hardware": "argo",
    • "model": "Vesta",
    • "online": true,
    • "heartbeat": "2026-10-26T11:01:45+00:00",
    • "location": {
      },
    • "config": {
      },
    • "config_confirmed": true,
    • "state": {
      },
    • "site_id": "qs2oTBdeaj"
    }
]

Register or create a device

Required permission: devices:write (role SITE_MANAGER or higher)

Adds a device to your organization.

  • If the device ID belongs to an unregistered Velavu device (see GET /available), it is registered and only id is needed.
  • Otherwise a new device record is created, which needs serial_code, category and model. Use this for third-party devices.
Authorizations:
bearerAuth
Request Body schema: application/json
required
id
required
string

Device ID, as printed on the device.

serial_code
string

Required when creating a device that is not a registered Velavu device.

category
string (DeviceCategory)
Enum: "TAG" "ANCHOR"

Required when creating. When registering, defaults to the device's current category. Must be one of the model's categories.

model
string

Device model name. Required when creating.

object (FixedLocation)

Fixed location for an anchor. locked defaults to true.

coordinates
required
Array of numbers = 2 items
floor_id
string
locked
boolean
notes
string

Responses

Request samples

Content type
application/json
Example
{
  • "id": "A0363",
  • "category": "ANCHOR",
  • "location": {
    • "coordinates": [
      ],
    • "floor_id": "qs2oTBdeajf_13bb5816ec8a9b70"
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "V0000",
  • "serial_code": "sw:Jd:00:00:00:1F",
  • "category": "TAG",
  • "hardware": "argo",
  • "model": "Vesta",
  • "online": true,
  • "heartbeat": "2026-10-26T11:01:45+00:00",
  • "location": {
    • "coordinates": [
      ],
    • "timestamp": "2026-09-24T15:55:53+00:00",
    • "location_type": "FIXED",
    • "floor_id": "qs2oTBdeajf_13bb5816ec8a9b70",
    • "locked": true
    },
  • "config": {
    • "heartbeat_rate_s": 1800,
    • "dfu_auto_update": true,
    • "disable_offline_sink": true,
    • "positioning": {
      },
    • "imu": {
      },
    • "vehicle": {
      },
    • "wirepas": {
      }
    },
  • "config_confirmed": true,
  • "state": {
    • "app_version": "velavu-gateway_2.12.2_argo-revB_OPEN",
    • "power": {
      },
    • "vehicle": {
      },
    • "cell": {
      },
    • "gnss": {
      },
    • "wirepas": {
      }
    },
  • "site_id": "qs2oTBdeaj"
}

Get a device

Required permission: devices:read (role VIEWER or higher)

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
Example
{
  • "id": "V0000",
  • "serial_code": "sw:Jd:00:00:00:1F",
  • "category": "TAG",
  • "hardware": "argo",
  • "model": "Vesta",
  • "online": true,
  • "heartbeat": "2026-10-26T11:01:45+00:00",
  • "location": {
    • "coordinates": [
      ],
    • "timestamp": "2026-09-24T15:55:53+00:00",
    • "location_type": "FIXED",
    • "floor_id": "qs2oTBdeajf_13bb5816ec8a9b70",
    • "locked": true
    },
  • "config": {
    • "heartbeat_rate_s": 1800,
    • "dfu_auto_update": true,
    • "disable_offline_sink": true,
    • "positioning": {
      },
    • "imu": {
      },
    • "vehicle": {
      },
    • "wirepas": {
      }
    },
  • "config_confirmed": true,
  • "state": {
    • "app_version": "velavu-gateway_2.12.2_argo-revB_OPEN",
    • "power": {
      },
    • "vehicle": {
      },
    • "cell": {
      },
    • "gnss": {
      },
    • "wirepas": {
      }
    },
  • "site_id": "qs2oTBdeaj"
}

Register an available device

Required permission: devices:write (role SITE_MANAGER or higher)

Registers an unregistered Velavu device with this ID. Equivalent to POST /devices with only id.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000
Request Body schema: application/json
required
object (FixedLocation)
coordinates
required
Array of numbers = 2 items
floor_id
string
locked
boolean
notes
string
category
string (DeviceCategory)
Enum: "TAG" "ANCHOR"

Responses

Request samples

Content type
application/json
{
  • "category": "TAG",
  • "notes": "Spare"
}

Response samples

Content type
application/json
Example
{
  • "id": "V0000",
  • "serial_code": "sw:Jd:00:00:00:1F",
  • "category": "TAG",
  • "hardware": "argo",
  • "model": "Vesta",
  • "online": true,
  • "heartbeat": "2026-10-26T11:01:45+00:00",
  • "location": {
    • "coordinates": [
      ],
    • "timestamp": "2026-09-24T15:55:53+00:00",
    • "location_type": "FIXED",
    • "floor_id": "qs2oTBdeajf_13bb5816ec8a9b70",
    • "locked": true
    },
  • "config": {
    • "heartbeat_rate_s": 1800,
    • "dfu_auto_update": true,
    • "disable_offline_sink": true,
    • "positioning": {
      },
    • "imu": {
      },
    • "vehicle": {
      },
    • "wirepas": {
      }
    },
  • "config_confirmed": true,
  • "state": {
    • "app_version": "velavu-gateway_2.12.2_argo-revB_OPEN",
    • "power": {
      },
    • "vehicle": {
      },
    • "cell": {
      },
    • "gnss": {
      },
    • "wirepas": {
      }
    },
  • "site_id": "qs2oTBdeaj"
}

Update a device

Required permission: devices:write (role SITE_MANAGER or higher)

Only the fields you send are changed.

  • location sets a fixed location (normally for anchors). The device is placed in the site containing the coordinates; floor_id must be a floor of that site.
  • category must be one of the model's categories. A device paired to an asset cannot become an ANCHOR.
  • state sends a state change to the device. Only fields the device already reports can be set, and the change is only sent if the device is online.
  • dfu_channel is only accepted for argo devices.

config and asset_id are accepted by the request schema but currently ignored. Change configuration with a rule and pair devices from the asset.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000
Request Body schema: application/json
required
object (FixedLocation)
coordinates
required
Array of numbers = 2 items
floor_id
string
locked
boolean
asset_id
string
Deprecated

Ignored. Pair from the asset instead.

notes
string
object
Deprecated

Ignored. Use a rule to change configuration.

property name*
additional property
any
object

State fields to set on the device.

property name*
additional property
any
category
string (DeviceCategory)
Enum: "TAG" "ANCHOR"
dfu_channel
string (FwChannel)
Enum: "STABLE" "BETA" "ALPHA"

Automatic firmware update channel. argo only.

Responses

Request samples

Content type
application/json
{
  • "notes": "Mounted above door 2",
  • "location": {
    • "coordinates": [
      ],
    • "floor_id": "qs2oTBdeajf_13bb5816ec8a9b70",
    • "locked": true
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "V0000",
  • "serial_code": "sw:Jd:00:00:00:1F",
  • "category": "TAG",
  • "hardware": "argo",
  • "model": "Vesta",
  • "online": true,
  • "heartbeat": "2026-10-26T11:01:45+00:00",
  • "location": {
    • "coordinates": [
      ],
    • "timestamp": "2026-09-24T15:55:53+00:00",
    • "location_type": "FIXED",
    • "floor_id": "qs2oTBdeajf_13bb5816ec8a9b70",
    • "locked": true
    },
  • "config": {
    • "heartbeat_rate_s": 1800,
    • "dfu_auto_update": true,
    • "disable_offline_sink": true,
    • "positioning": {
      },
    • "imu": {
      },
    • "vehicle": {
      },
    • "wirepas": {
      }
    },
  • "config_confirmed": true,
  • "state": {
    • "app_version": "velavu-gateway_2.12.2_argo-revB_OPEN",
    • "power": {
      },
    • "vehicle": {
      },
    • "cell": {
      },
    • "gnss": {
      },
    • "wirepas": {
      }
    },
  • "site_id": "qs2oTBdeaj"
}

Remove a device

Required permission: devices:delete (role ADMIN or higher)

Removes the device from your organization. The device is unpaired from its asset, removed from any Wirepas backend and sent a factory reset. Velavu devices become available to register again. A cellular device's SIM is deactivated one day later.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
null

Look up a device to register

Required permission: devices:read (role VIEWER or higher)

Finds a device by ID or serial code and tells you whether it is already registered to your organization. Pass id or serial_code.

Authorizations:
bearerAuth
query Parameters
id
string
Example: id=00000
serial_code
string

Responses

Response samples

Content type
application/json
{
  • "device": {
    • "id": "V0000",
    • "serial_code": "sw:Jd:00:00:00:1F",
    • "category": "TAG",
    • "hardware": "argo",
    • "model": "Vesta",
    • "online": true,
    • "heartbeat": "2026-10-26T11:01:45+00:00",
    • "location": {
      },
    • "config": {
      },
    • "config_confirmed": true,
    • "state": {
      },
    • "site_id": "qs2oTBdeaj"
    },
  • "registered": true
}

Clear a device's location

Required permission: devices:write (role SITE_MANAGER or higher)

Removes location, site_id and geofence_ids from the device.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
null

Turn off automatic firmware updates

Required permission: devices:write (role SITE_MANAGER or higher)

Clears dfu_channel.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
null

Reboot a device

Required permission: devices:manage (role SITE_MANAGER or higher)

Sends a reboot command and marks the device offline until its next heartbeat. The device must be online to receive it.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
null

Shut down a device

Required permission: devices:manage (role SITE_MANAGER or higher)

Sends a shutdown command and marks the device offline. Only argo devices support this; other hardware returns 400.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
null

Request a position update

Required permission: devices:control (role OPERATOR or higher)

Asks the device to report its position now. The new position arrives as a LOCATION event. The device must be online.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
null

Request a BLE scan

Required permission: devices:control (role OPERATOR or higher)

Asks the device to scan for nearby BLE beacons. Results arrive asynchronously as a BLE_BEACON_SCAN event about scan_duration seconds later. Supported on argo, meridian, generic and aries hardware. The device must be online.

Unlike the site scan, this does not create a BLE_SCAN_REQUEST event.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000
Request Body schema: application/json
filters
Array of strings (BleScanFilter)
Items Enum: "Minew V1" "Minew V2" "Eddystone" "iBeacon"

Beacon formats to report.

min_rssi
integer

Beacons weaker than this (dBm) are ignored.

scan_duration
integer > 0

Scan length in seconds.

Responses

Request samples

Content type
application/json
{
  • "filters": [
    • "Eddystone"
    ],
  • "scan_duration": 30,
  • "min_rssi": -71
}

Response samples

Content type
application/json
null

Flash or beep a device

Required permission: devices:control (role OPERATOR or higher)

Makes the device flash its LED or sound its buzzer so it can be found. The indicator used depends on the model (indicator on the device model). Supported on argo, meridian, generic and panicbutton hardware. The device must be online.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000
Request Body schema: application/json
timeout_s
integer > 0

How long to keep indicating, in seconds.

on_time_ms
integer > 0

On time of each blink, in milliseconds.

off_time_ms
integer > 0

Off time of each blink, in milliseconds.

Responses

Request samples

Content type
application/json
{
  • "timeout_s": 30,
  • "on_time_ms": 500,
  • "off_time_ms": 500
}

Response samples

Content type
application/json
null

Clear a panic button alert

Required permission: devices:control (role OPERATOR or higher)

Tells a panicbutton device that its alert has been handled.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
null

Events

Time-series history: locations, sensor readings, boundary crossings, device lifecycle and more. The shape of data depends on category; pick a category in the Event schema to see it.

List events

Required permission: events:read (role VIEWER or higher)

Events of one category across the organization, newest first.

Authorizations:
bearerAuth
path Parameters
event_category
required
string (EventCategory)
Enum: "LOCATION" "ENVIRONMENT" "BATTERY_LEVEL" "LOW_BATTERY" "DRIVING_ROUTE" "DRIVING_EVT" "IMU_SHOCK" "IMU_MOTION" "DEVICE_BOOT" "DEVICE_POWER_DOWN" "DEVICE_ERROR" "DEVICE_CONNECT" "DEVICE_DISCONNECT" "DEVICE_PROVISION" "PROVISION_REQUEST" "SITE_ENTERED" "SITE_EXITED" "GEOFENCE_ENTERED" "GEOFENCE_EXITED" "INVENTORY_ADDED" "INVENTORY_REMOVED" "WEARABLE_ALERT" "CUSTOM_EVENT" "DFU_REQUEST" "OTAP_REQUEST" "BLE_SCAN_REQUEST" "BLE_BEACON_SCAN" "MESH_BEACON_SCAN" "WIFI_BEACON_SCAN" "ALERT"

Event category to return. Unknown categories return an empty list.

query Parameters
since
string <date-time>
Example: since=2026-10-01T00:00:00+00:00

Only return events at or after this time (ISO 8601).

until
string <date-time>

Only return events at or before this time (ISO 8601).

limit
integer [ 1 .. 1000 ]
Default: 1000

Maximum number of events to return.

continuation_token
string

The X-Continuation-Token header from the previous page.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "N8yxl5rx4j",
    • "category": "LOCATION",
    • "timestamp": "2026-10-26T17:13:57+00:00",
    • "asset_id": "ogJoterwmx",
    • "device_id": "00487",
    • "data": {
      }
    }
]

Delete events

Required permission: events:delete (role ADMIN or higher)

Deletes every event of this category in the time range. With no range, deletes all of them.

Authorizations:
bearerAuth
path Parameters
event_category
required
string (EventCategory)
Enum: "LOCATION" "ENVIRONMENT" "BATTERY_LEVEL" "LOW_BATTERY" "DRIVING_ROUTE" "DRIVING_EVT" "IMU_SHOCK" "IMU_MOTION" "DEVICE_BOOT" "DEVICE_POWER_DOWN" "DEVICE_ERROR" "DEVICE_CONNECT" "DEVICE_DISCONNECT" "DEVICE_PROVISION" "PROVISION_REQUEST" "SITE_ENTERED" "SITE_EXITED" "GEOFENCE_ENTERED" "GEOFENCE_EXITED" "INVENTORY_ADDED" "INVENTORY_REMOVED" "WEARABLE_ALERT" "CUSTOM_EVENT" "DFU_REQUEST" "OTAP_REQUEST" "BLE_SCAN_REQUEST" "BLE_BEACON_SCAN" "MESH_BEACON_SCAN" "WIFI_BEACON_SCAN" "ALERT"

Event category to return. Unknown categories return an empty list.

query Parameters
since
string <date-time>
Example: since=2026-10-01T00:00:00+00:00

Only return events at or after this time (ISO 8601).

until
string <date-time>

Only return events at or before this time (ISO 8601).

Responses

Response samples

Content type
application/json
null

List events for an asset, device, site or geofence

Required permission: events:read (role VIEWER or higher)

For example GET /events/LOCATION/asset/HQojZMGKuF returns an asset's location history.

Authorizations:
bearerAuth
path Parameters
event_category
required
string (EventCategory)
Enum: "LOCATION" "ENVIRONMENT" "BATTERY_LEVEL" "LOW_BATTERY" "DRIVING_ROUTE" "DRIVING_EVT" "IMU_SHOCK" "IMU_MOTION" "DEVICE_BOOT" "DEVICE_POWER_DOWN" "DEVICE_ERROR" "DEVICE_CONNECT" "DEVICE_DISCONNECT" "DEVICE_PROVISION" "PROVISION_REQUEST" "SITE_ENTERED" "SITE_EXITED" "GEOFENCE_ENTERED" "GEOFENCE_EXITED" "INVENTORY_ADDED" "INVENTORY_REMOVED" "WEARABLE_ALERT" "CUSTOM_EVENT" "DFU_REQUEST" "OTAP_REQUEST" "BLE_SCAN_REQUEST" "BLE_BEACON_SCAN" "MESH_BEACON_SCAN" "WIFI_BEACON_SCAN" "ALERT"

Event category to return. Unknown categories return an empty list.

resource
required
string
Enum: "asset" "device" "site" "geofence"

Kind of object to filter by.

resource_id
required
string
Example: HQojZMGKuF

ID of the asset, device, site or geofence.

query Parameters
since
string <date-time>
Example: since=2026-10-01T00:00:00+00:00

Only return events at or after this time (ISO 8601).

until
string <date-time>

Only return events at or before this time (ISO 8601).

limit
integer [ 1 .. 1000 ]
Default: 1000

Maximum number of events to return.

continuation_token
string

The X-Continuation-Token header from the previous page.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "GmS7fAYAnr",
    • "category": "LOCATION",
    • "timestamp": "2026-10-26T17:03:22+00:00",
    • "asset_id": "HQojZMGKuF",
    • "device_id": "00000",
    • "data": {
      }
    }
]

Delete events for an asset, device, site or geofence

Required permission: events:delete (role ADMIN or higher)

Authorizations:
bearerAuth
path Parameters
event_category
required
string (EventCategory)
Enum: "LOCATION" "ENVIRONMENT" "BATTERY_LEVEL" "LOW_BATTERY" "DRIVING_ROUTE" "DRIVING_EVT" "IMU_SHOCK" "IMU_MOTION" "DEVICE_BOOT" "DEVICE_POWER_DOWN" "DEVICE_ERROR" "DEVICE_CONNECT" "DEVICE_DISCONNECT" "DEVICE_PROVISION" "PROVISION_REQUEST" "SITE_ENTERED" "SITE_EXITED" "GEOFENCE_ENTERED" "GEOFENCE_EXITED" "INVENTORY_ADDED" "INVENTORY_REMOVED" "WEARABLE_ALERT" "CUSTOM_EVENT" "DFU_REQUEST" "OTAP_REQUEST" "BLE_SCAN_REQUEST" "BLE_BEACON_SCAN" "MESH_BEACON_SCAN" "WIFI_BEACON_SCAN" "ALERT"

Event category to return. Unknown categories return an empty list.

resource
required
string
Enum: "asset" "device" "site" "geofence"

Kind of object to filter by.

resource_id
required
string
Example: HQojZMGKuF

ID of the asset, device, site or geofence.

query Parameters
since
string <date-time>
Example: since=2026-10-01T00:00:00+00:00

Only return events at or after this time (ISO 8601).

until
string <date-time>

Only return events at or before this time (ISO 8601).

Responses

Response samples

Content type
application/json
null

Delete an event

Required permission: events:delete (role ADMIN or higher)

Authorizations:
bearerAuth
path Parameters
event_category
required
string (EventCategory)
Enum: "LOCATION" "ENVIRONMENT" "BATTERY_LEVEL" "LOW_BATTERY" "DRIVING_ROUTE" "DRIVING_EVT" "IMU_SHOCK" "IMU_MOTION" "DEVICE_BOOT" "DEVICE_POWER_DOWN" "DEVICE_ERROR" "DEVICE_CONNECT" "DEVICE_DISCONNECT" "DEVICE_PROVISION" "PROVISION_REQUEST" "SITE_ENTERED" "SITE_EXITED" "GEOFENCE_ENTERED" "GEOFENCE_EXITED" "INVENTORY_ADDED" "INVENTORY_REMOVED" "WEARABLE_ALERT" "CUSTOM_EVENT" "DFU_REQUEST" "OTAP_REQUEST" "BLE_SCAN_REQUEST" "BLE_BEACON_SCAN" "MESH_BEACON_SCAN" "WIFI_BEACON_SCAN" "ALERT"

Event category to return. Unknown categories return an empty list.

event_id
required
string

Responses

Response samples

Content type
application/json
null

List an asset's essential events

Required permission: events:read (role VIEWER or higher)

A combined timeline of the most important event categories: IMU_SHOCK, IMU_MOTION, DEVICE_CONNECT, DEVICE_DISCONNECT, LOW_BATTERY, SITE_ENTERED, SITE_EXITED, GEOFENCE_ENTERED, GEOFENCE_EXITED and CUSTOM_EVENT. At most 50 events per category are returned, sorted newest first. Not paginated.

Authorizations:
bearerAuth
path Parameters
asset_id
required
string
Example: HQojZMGKuF
query Parameters
since
string <date-time>
Example: since=2026-10-01T00:00:00+00:00

Only return events at or after this time (ISO 8601).

until
string <date-time>

Only return events at or before this time (ISO 8601).

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "GmS7fAYAnr",
    • "category": "LOCATION",
    • "timestamp": "2026-10-26T17:03:22+00:00",
    • "asset_id": "HQojZMGKuF",
    • "device_id": "00000",
    • "data": {
      }
    }
]

List a device's essential events

Required permission: events:read (role VIEWER or higher)

A combined timeline of the most important event categories: IMU_SHOCK, IMU_MOTION, DEVICE_CONNECT, DEVICE_DISCONNECT, LOW_BATTERY, SITE_ENTERED, SITE_EXITED, GEOFENCE_ENTERED, GEOFENCE_EXITED and CUSTOM_EVENT. At most 50 events per category are returned, sorted newest first. Not paginated.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000
query Parameters
since
string <date-time>
Example: since=2026-10-01T00:00:00+00:00

Only return events at or after this time (ISO 8601).

until
string <date-time>

Only return events at or before this time (ISO 8601).

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "GmS7fAYAnr",
    • "category": "LOCATION",
    • "timestamp": "2026-10-26T17:03:22+00:00",
    • "asset_id": "HQojZMGKuF",
    • "device_id": "00000",
    • "data": {
      }
    }
]

Alerts

Alerts are copies of events that rules have flagged for attention.

List alerts

Required permission: alerts:read (role VIEWER or higher)

Authorizations:
bearerAuth
query Parameters
event_categories
string
Example: event_categories=WEARABLE_ALERT,LOW_BATTERY

Comma-separated event categories. Only alerts raised by these categories are returned.

limit
integer [ 1 .. 250 ]
Default: 250

Maximum number of objects to return.

continuation_token
string

The X-Continuation-Token header from the previous page.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "Jx81mQe0aB",
    • "category": "ALERT",
    • "event_category": "WEARABLE_ALERT",
    • "timestamp": "2026-10-24T14:02:11+00:00",
    • "device_id": "00000",
    • "data": {
      },
    • "device": {
      },
    • "asset": {
      }
    }
]

Delete alerts

Required permission: alerts:delete (role OPERATOR or higher)

Deletes all alerts, or only those raised by the given categories.

Authorizations:
bearerAuth
query Parameters
event_categories
string

Comma-separated event categories.

Responses

Response samples

Content type
application/json
null

Delete an alert

Required permission: alerts:delete (role OPERATOR or higher)

Authorizations:
bearerAuth
path Parameters
alert_id
required
string

Responses

Response samples

Content type
application/json
null

Sites

Buildings or yards with floors, floor plans and a boundary.

List sites

Required permission: sites:read (role VIEWER or higher)

All sites, sorted by name. Not paginated.

Authorizations:
bearerAuth
query Parameters
include_details
boolean
Default: true

Set to false to leave out floors and online. This is faster, because the site status and floor plan image URLs are not computed.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "qs2oTBdeaj",
    • "name": "Hospital Demo",
    • "online": true,
    • "coordinates": [
      ],
    • "boundary": {
      },
    • "boundary_factor": 1.5,
    • "floors": [
      ]
    }
]

Create a site

Required permission: sites:write (role SITE_MANAGER or higher)

Creates a site with no floors. Add floors with POST /sites/{site_id}/floors; the boundary is computed from their walls.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
coordinates
required
Array of numbers = 2 items

Site location as [longitude, latitude].

Responses

Request samples

Content type
application/json
{
  • "name": "Hospital Demo",
  • "coordinates": [
    • -79.367186,
    • 43.680116
    ]
}

Response samples

Content type
application/json
{
  • "id": "qs2oTBdeaj",
  • "name": "Hospital Demo",
  • "online": true,
  • "coordinates": [
    • -79.367186,
    • 43.680116
    ],
  • "boundary": {
    • "type": "Polygon",
    • "coordinates": [
      ]
    },
  • "boundary_factor": 1.5,
  • "floors": [
    • {
      }
    ]
}

Get a site

Required permission: sites:read (role VIEWER or higher)

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj

Responses

Response samples

Content type
application/json
{
  • "id": "qs2oTBdeaj",
  • "name": "Hospital Demo",
  • "online": true,
  • "coordinates": [
    • -79.367186,
    • 43.680116
    ],
  • "boundary": {
    • "type": "Polygon",
    • "coordinates": [
      ]
    },
  • "boundary_factor": 1.5,
  • "floors": [
    • {
      }
    ]
}

Update a site

Required permission: sites:write (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj
Request Body schema: application/json
required
name
string
coordinates
Array of numbers = 2 items
boundary_factor
number

How far the boundary extends beyond the floor walls.

Responses

Request samples

Content type
application/json
{
  • "boundary_factor": 2
}

Response samples

Content type
application/json
{
  • "id": "qs2oTBdeaj",
  • "name": "Hospital Demo",
  • "online": true,
  • "coordinates": [
    • -79.367186,
    • 43.680116
    ],
  • "boundary": {
    • "type": "Polygon",
    • "coordinates": [
      ]
    },
  • "boundary_factor": 1.5,
  • "floors": [
    • {
      }
    ]
}

Delete a site

Required permission: sites:delete (role SITE_MANAGER or higher)

Deletes the site and its floor plan images.

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj

Responses

Response samples

Content type
application/json
null

Add a floor

Required permission: sites:write (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj
Request Body schema: application/json
required
name
required
string
level
required
integer

Floor number. 0 is the ground floor.

required
object

{"walls": <GeoJSON FeatureCollection of LineStrings>}. Used to compute the site boundary.

property name*
additional property
any
object

Floor plan image placement (see FloorImage).

property name*
additional property
any
img_upload
string^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-...

Floor plan image file, base64-encoded.

Responses

Request samples

Content type
application/json
{
  • "name": "Level 1",
  • "level": 0,
  • "geometry": {
    • "walls": {
      }
    }
}

Response samples

Content type
application/json
{
  • "id": "qs2oTBdeajf_13bb5816ec8a9b70",
  • "name": "Level 1",
  • "level": 0,
  • "geometry": {
    • "walls": { }
    },
  • "img": {
    • "url": "http://example.com",
    • "filename": "string",
    • "width": 0,
    • "height": 0,
    • "center": [
      ],
    • "coordinates": [
      ],
    • "scale": 0,
    • "rotation": 0,
    • "opacity": 0
    }
}

Update a floor

Required permission: sites:write (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj
floor_id
required
string
Example: qs2oTBdeajf_13bb5816ec8a9b70
Request Body schema: application/json
required
name
string
level
integer
object
property name*
additional property
any
object
property name*
additional property
any
img_upload
string^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-...

Responses

Request samples

Content type
application/json
{
  • "name": "Ground floor"
}

Response samples

Content type
application/json
{
  • "id": "qs2oTBdeajf_13bb5816ec8a9b70",
  • "name": "Level 1",
  • "level": 0,
  • "geometry": {
    • "walls": { }
    },
  • "img": {
    • "url": "http://example.com",
    • "filename": "string",
    • "width": 0,
    • "height": 0,
    • "center": [
      ],
    • "coordinates": [
      ],
    • "scale": 0,
    • "rotation": 0,
    • "opacity": 0
    }
}

Delete a floor

Required permission: sites:delete (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj
floor_id
required
string
Example: qs2oTBdeajf_13bb5816ec8a9b70

Responses

Response samples

Content type
application/json
null

Upload a floor plan image

Required permission: sites:write (role SITE_MANAGER or higher)

Send the image file as the raw request body with a binary content type such as image/png. Requests whose body API Gateway does not base64-encode (text content types) are rejected with 400. Fetch the site to get the new img.url.

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj
floor_id
required
string
Example: qs2oTBdeajf_13bb5816ec8a9b70
Request Body schema: image/*
required
string <binary>

Responses

Response samples

Content type
application/json
null

Delete a floor plan image

Required permission: sites:write (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj
floor_id
required
string
Example: qs2oTBdeajf_13bb5816ec8a9b70

Responses

Response samples

Content type
application/json
null

Set the site's target OTAP image

Required permission: sites:write (role SITE_MANAGER or higher)

Keeps every mesh device in the site on this OTAP image. Velavu creates a managed rule that re-sends the image to gateways whose mesh is not on it.

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj
Request Body schema: application/json
required
name
required
string

OTAP image name from GET /otap/images.

Responses

Request samples

Content type
application/json
{
  • "name": "velavu-52833_legacy_20261021_103118.otap"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "crc": 0,
  • "rule_id": "string"
}

Clear the site's target OTAP image

Required permission: sites:write (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj

Responses

Response samples

Content type
application/json
null

Request positions from all devices of a hardware type

Required permission: none is mapped for this route, so requests are currently rejected with 403.

Broadcasts a position request through every gateway in the site to devices of the given hardware type.

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj
Request Body schema: application/json
required
hardware
required
string

Hardware type to ask, for example panicbutton.

Responses

Request samples

Content type
application/json
{
  • "hardware": "panicbutton"
}

Response samples

Content type
application/json
null

Request a BLE scan across a site

Required permission: sites:manage (role SITE_MANAGER or higher)

Asks every online BLE-capable scanner in the site to scan. Each scanner's results arrive as a BLE_BEACON_SCAN event; the returned BLE_SCAN_REQUEST event tracks how many scanners have responded and becomes COMPLETE when all have, or after scan_timeout seconds.

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj
Request Body schema: application/json
filters
Array of strings (BleScanFilter)
Items Enum: "Minew V1" "Minew V2" "Eddystone" "iBeacon"
min_rssi
integer
scan_duration
integer > 0
scan_timeout
integer > 0

Seconds to wait for all scanners before completing the request.

Responses

Request samples

Content type
application/json
{
  • "filters": [
    • "Eddystone"
    ],
  • "scan_duration": 30,
  • "scan_timeout": 60,
  • "min_rssi": -71
}

Response samples

Content type
application/json
{
  • "id": "Hc7nR2uQ9x",
  • "category": "BLE_SCAN_REQUEST",
  • "timestamp": "2026-10-26T15:00:00+00:00",
  • "site_id": "qs2oTBdeaj",
  • "data": {
    • "status": "STARTED",
    • "expected_response_count": 3,
    • "pending_response_count": 3,
    • "scan_duration": 30,
    • "scan_timeout": 60,
    • "min_rssi": -71,
    • "filters": [
      ]
    }
}

Geofences

Polygon areas that generate entry and exit events.

List geofences

Required permission: geofences:read (role VIEWER or higher)

Not paginated.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "name": "string",
    • "boundary": {
      },
    • "center": [
      ]
    }
]

Create a geofence

Required permission: geofences:write (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
required
object

GeoJSON Polygon.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "name": "Loading dock",
  • "boundary": {
    • "type": "Polygon",
    • "coordinates": [
      ]
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "boundary": {
    • "type": "Polygon",
    • "coordinates": [
      ]
    },
  • "center": [
    • -79.367355,
    • 43.679585
    ]
}

Get a geofence

Required permission: geofences:read (role VIEWER or higher)

Authorizations:
bearerAuth
path Parameters
geofence_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "boundary": {
    • "type": "Polygon",
    • "coordinates": [
      ]
    },
  • "center": [
    • -79.367355,
    • 43.679585
    ]
}

Update a geofence

Required permission: geofences:write (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
geofence_id
required
string
Request Body schema: application/json
required
name
string
object
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "boundary": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "boundary": {
    • "type": "Polygon",
    • "coordinates": [
      ]
    },
  • "center": [
    • -79.367355,
    • 43.679585
    ]
}

Delete a geofence

Required permission: geofences:delete (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
geofence_id
required
string

Responses

Response samples

Content type
application/json
null

Device Firmware (DFU)

Firmware updates for cellular gateways and trackers (argo hardware), downloaded directly by the device.

List DFU requests

Required permission: dfu:read (role SITE_MANAGER or higher)

All DFU_REQUEST events in the organization, newest first.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "Qm2xYv8Lr1",
    • "category": "DFU_REQUEST",
    • "timestamp": "2026-10-21T15:02:44+00:00",
    • "device_id": "V0000",
    • "data": {
      }
    }
]

Delete a DFU request

Required permission: dfu:write (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
request_id
required
string

ID of the request event.

Responses

Response samples

Content type
application/json
null

List a device's DFU requests

Required permission: dfu:read (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "Qm2xYv8Lr1",
    • "category": "DFU_REQUEST",
    • "timestamp": "2026-10-21T15:02:44+00:00",
    • "device_id": "V0000",
    • "data": {
      }
    }
]

Update a device's firmware

Required permission: dfu:write (role SITE_MANAGER or higher)

Sends a firmware update to an argo device. name must be one of the images returned by GET /dfu/device/{device_id}/images. Track progress with the returned request's data.status.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000
Request Body schema: application/json
required
name
required
string

Image file name.

Responses

Request samples

Content type
application/json
{
  • "name": "velavu-gateway_2.12.2_argo-revB_OPEN.bin"
}

Response samples

Content type
application/json
{
  • "id": "Qm2xYv8Lr1",
  • "category": "DFU_REQUEST",
  • "timestamp": "2026-10-21T15:02:44+00:00",
  • "device_id": "V0000",
  • "data": {
    • "name": "velavu-gateway_2.12.2_argo-revB_OPEN.bin",
    • "status": "COMPLETE"
    }
}

List compatible firmware images

Required permission: dfu:read (role SITE_MANAGER or higher)

Firmware images whose project and board match the device's current state.app_version (<project>_<version>_<board>_<customer>).

Returns 500 if the device's app_version is not in that format.

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
[
  • {
    • "name": "velavu-gateway_2.12.2_argo-revB_OPEN.bin",
    • "project": "velavu-gateway",
    • "version": "2.12.2",
    • "board": "argo-revB",
    • "channel": "STABLE",
    • "comment": "string",
    • "release_date": "2019-08-24T14:15:22Z"
    }
]

Mesh Firmware (OTAP)

Over-the-air firmware updates for Wirepas mesh devices, distributed through a gateway.

List OTAP requests

Required permission: otap:read (role ADMIN or higher)

All OTAP_REQUEST events in the organization, newest first.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "Zk4pW7tN0c",
    • "category": "OTAP_REQUEST",
    • "timestamp": "2026-10-21T15:10:02+00:00",
    • "device_id": "V0000",
    • "data": {
      }
    }
]

Delete an OTAP request

Required permission: otap:write (role ADMIN or higher)

Authorizations:
bearerAuth
path Parameters
request_id
required
string

ID of the request event.

Responses

Response samples

Content type
application/json
null

List OTAP images

Required permission: otap:read (role ADMIN or higher)

Velavu's published OTAP images plus any your organization has uploaded.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "name": "velavu-52833_legacy_20261021_103118.otap",
    • "comment": "Template: velavu-52833 | Build: 2026-10-21 10:27:40 | Bootloader: legacy | Stack: nrf52833@5.9.4.1 | Images: juno-app-juno-revA@2.3.3.0, meridian-app-meridian-revB@2.3.2.0",
    • "release_date": "2019-08-24T14:15:22Z",
    • "crc": 4139
    }
]

Upload an OTAP image

Required permission: otap:write (role ADMIN or higher)

Uploads a scratchpad image for your organization under name. Send the file as the raw request body with Content-Type: application/octet-stream, or as base64 text with Content-Type: text/plain.

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: custom-mesh_20261021.otap

Image file name.

Request Body schema:
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "name": "velavu-52833_legacy_20261021_103118.otap",
  • "comment": "Template: velavu-52833 | Build: 2026-10-21 10:27:40 | Bootloader: legacy | Stack: nrf52833@5.9.4.1 | Images: juno-app-juno-revA@2.3.3.0, meridian-app-meridian-revB@2.3.2.0",
  • "release_date": "2019-08-24T14:15:22Z",
  • "crc": 4139
}

Delete an uploaded OTAP image

Required permission: otap:write (role ADMIN or higher)

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: custom-mesh_20261021.otap

Image file name.

Responses

Response samples

Content type
application/json
null

List a gateway's OTAP requests

Required permission: otap:read (role ADMIN or higher)

Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "Zk4pW7tN0c",
    • "category": "OTAP_REQUEST",
    • "timestamp": "2026-10-21T15:10:02+00:00",
    • "device_id": "V0000",
    • "data": {
      }
    }
]

Start a mesh update through a gateway

Required permission: otap:write (role ADMIN or higher)

Sends an OTAP image to a gateway, which distributes it through its mesh.

  • Set sequence to 0 when the image is an update for the gateway's own sink. Otherwise omit it.
  • processing_delay only applies when the gateway's config.wirepas.otap_mode is PROPAGATE_AND_PROCESS_WITH_DELAY; in other modes it is ignored.
  • The request fails if the gateway's config.wirepas.otap_mode is OTAP_DISABLED.
Authorizations:
bearerAuth
path Parameters
device_id
required
string
Example: 00000
Request Body schema: application/json
required
name
required
string

OTAP image name from GET /otap/images.

sequence
integer >= 0

Wirepas OTAP sequence number. Use 0 to update the gateway's own sink; otherwise omit.

processing_delay
integer >= 0

Seconds the mesh waits before processing the image. Only used when the gateway's otap_mode is PROPAGATE_AND_PROCESS_WITH_DELAY.

Responses

Request samples

Content type
application/json
{
  • "name": "velavu-52833_legacy_20261021_103118.otap"
}

Response samples

Content type
application/json
{
  • "id": "Zk4pW7tN0c",
  • "category": "OTAP_REQUEST",
  • "timestamp": "2026-10-21T15:10:02+00:00",
  • "device_id": "V0000",
  • "data": {
    • "name": "velavu-52833_legacy_20261021_103118.otap",
    • "sequence": 1,
    • "processing_delay": 0,
    • "status": "STARTED"
    }
}

List a site's latest OTAP requests

Required permission: otap:read (role ADMIN or higher)

The most recent OTAP request for each gateway in the site.

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "Zk4pW7tN0c",
    • "category": "OTAP_REQUEST",
    • "timestamp": "2026-10-21T15:10:02+00:00",
    • "device_id": "V0000",
    • "data": {
      }
    }
]

Start a mesh update for a site

Required permission: otap:write (role ADMIN or higher)

Sends the OTAP image to every gateway in the site, creating one request per gateway. To keep a site on an image permanently, set a target OTAP image instead.

The sequence, processing_delay and OTAP_DISABLED rules of POST /otap/device/{device_id} apply to each gateway.

Authorizations:
bearerAuth
path Parameters
site_id
required
string
Example: qs2oTBdeaj
Request Body schema: application/json
required
name
required
string

OTAP image name from GET /otap/images.

sequence
integer >= 0

Wirepas OTAP sequence number. Use 0 to update the gateway's own sink; otherwise omit.

processing_delay
integer >= 0

Seconds the mesh waits before processing the image. Only used when the gateway's otap_mode is PROPAGATE_AND_PROCESS_WITH_DELAY.

Responses

Request samples

Content type
application/json
{
  • "name": "velavu-52833_legacy_20261021_103118.otap"
}

Response samples

Content type
application/json
[
  • {
    • "id": "Zk4pW7tN0c",
    • "category": "OTAP_REQUEST",
    • "timestamp": "2026-10-21T15:10:02+00:00",
    • "device_id": "V0000",
    • "data": {
      }
    }
]

Rules

Rules apply device configuration and generate events or alerts when a condition is met.

List rules

Required permission: rules:read (role SITE_MANAGER or higher)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "aKAh1Nobi4",
    • "name": "Device rate settings for Mokosmart B5",
    • "condition": "model == 'Mokosmart B5'",
    • "action": {
      },
    • "priority": 99,
    • "category": "MANAGED",
    • "enabled": true,
    • "created": "2026-10-24T22:46:27+00:00",
    • "last_modified": "2026-10-24T23:16:42+00:00"
    }
]

Create a rule

Required permission: rules:write or rules:write-config (role SITE_MANAGER or higher)

Conditions

A condition compares device properties with constants, for example environment.temperature_c > 25 or geofence_ids CONTAINS 'fA2SLW21tr'. Each comparison is a device property path, an operator and a constant, with exactly one space on each side of the operator. The constant's type is taken from the property. Combine comparisons with AND and OR; they are evaluated left to right.

Operators: ==, !=, >, <, >=, <=, CONTAINS, NOT_CONTAINS, CONTAINS_K, NOT_CONTAINS_K.

Actions

  • config is applied to every device that matches the condition. Use the config field names of the device's hardware type; fields the device does not report are dropped. When several rules set the same field, the highest priority wins.
  • on_active and on_deactive raise an event (and optionally an alert, SMS or email) when a device starts or stops matching.

Error reasons

reason Meaning
ERR_INVALID_COND The condition could not be parsed or evaluated.
ERR_INVALID_ACTION The action is not valid.
ERR_INVALID_PRIO The priority is not valid.
Authorizations:
bearerAuth
Request Body schema: application/json
required
condition
required
string
required
object (_RuleAction)
object
object (_EventOptions)
object (_EventOptions)
category
required
string
Enum: "USER" "MANAGED"
priority
integer >= 0
enabled
boolean
name
string
description
string

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Device rate settings for Mokosmart B5",
  • "condition": "model == 'Mokosmart B5'",
  • "category": "USER",
  • "priority": 10,
  • "action": {
    • "config": {
      }
    }
}

Response samples

Content type
application/json
{
  • "id": "aKAh1Nobi4",
  • "name": "Device rate settings for Mokosmart B5",
  • "condition": "model == 'Mokosmart B5'",
  • "action": {
    • "config": {
      }
    },
  • "priority": 99,
  • "category": "MANAGED",
  • "enabled": true,
  • "created": "2026-10-24T22:46:27+00:00",
  • "last_modified": "2026-10-24T23:16:42+00:00"
}

Get a rule

Required permission: rules:read (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
rule_id
required
string
Example: aKAh1Nobi4

Responses

Response samples

Content type
application/json
{
  • "id": "aKAh1Nobi4",
  • "name": "Device rate settings for Mokosmart B5",
  • "condition": "model == 'Mokosmart B5'",
  • "action": {
    • "config": {
      }
    },
  • "priority": 99,
  • "category": "MANAGED",
  • "enabled": true,
  • "created": "2026-10-24T22:46:27+00:00",
  • "last_modified": "2026-10-24T23:16:42+00:00"
}

Update a rule

Required permission: rules:write or rules:write-config (role SITE_MANAGER or higher)

Conditions

A condition compares device properties with constants, for example environment.temperature_c > 25 or geofence_ids CONTAINS 'fA2SLW21tr'. Each comparison is a device property path, an operator and a constant, with exactly one space on each side of the operator. The constant's type is taken from the property. Combine comparisons with AND and OR; they are evaluated left to right.

Operators: ==, !=, >, <, >=, <=, CONTAINS, NOT_CONTAINS, CONTAINS_K, NOT_CONTAINS_K.

Actions

  • config is applied to every device that matches the condition. Use the config field names of the device's hardware type; fields the device does not report are dropped. When several rules set the same field, the highest priority wins.
  • on_active and on_deactive raise an event (and optionally an alert, SMS or email) when a device starts or stops matching.

Error reasons

reason Meaning
ERR_INVALID_COND The condition could not be parsed or evaluated.
ERR_INVALID_ACTION The action is not valid.
ERR_INVALID_PRIO The priority is not valid.
Authorizations:
bearerAuth
path Parameters
rule_id
required
string
Example: aKAh1Nobi4
Request Body schema: application/json
required
condition
string
object (_RuleAction)
object
object (_EventOptions)
object (_EventOptions)
priority
integer >= 0
enabled
boolean
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "enabled": false
}

Response samples

Content type
application/json
{
  • "id": "aKAh1Nobi4",
  • "name": "Device rate settings for Mokosmart B5",
  • "condition": "model == 'Mokosmart B5'",
  • "action": {
    • "config": {
      }
    },
  • "priority": 99,
  • "category": "MANAGED",
  • "enabled": true,
  • "created": "2026-10-24T22:46:27+00:00",
  • "last_modified": "2026-10-24T23:16:42+00:00"
}

Delete a rule

Required permission: rules:delete (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
rule_id
required
string
Example: aKAh1Nobi4

Responses

Response samples

Content type
application/json
null

Integrations

Connections to third-party services. Currently MappedIn indoor maps.

Get integrations

Required permission: integrations:read (role VIEWER or higher)

Returns {} when no integrations are connected.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "mappedin": {
    • "api_key": "mik_xxxxxxxxxxxxxxxxxxxxxxxx",
    • "token": "eyJhbGciOi...",
    • "token_expiry": "2026-10-26T22:29:26+00:00",
    • "imports": [
      ]
    }
}

Connect MappedIn

Required permission: integrations:write (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
Request Body schema: application/json
required
api_key
required
string

MappedIn API key.

secret
required
string

MappedIn API secret. Stored by Velavu and never returned.

Responses

Request samples

Content type
application/json
{
  • "api_key": null,
  • "secret": null
}

Response samples

Content type
application/json
{
  • "mappedin": {
    • "api_key": "mik_xxxxxxxxxxxxxxxxxxxxxxxx",
    • "token": "eyJhbGciOi...",
    • "token_expiry": "2026-10-26T22:29:26+00:00",
    • "imports": [
      ]
    }
}

Disconnect MappedIn

Required permission: integrations:write (role SITE_MANAGER or higher)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
null

List MappedIn venues

Required permission: integrations:read (role VIEWER or higher)

Venues available in the connected MappedIn account.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "64ef49e662fd90fe020bee61",
    • "name": "Office Demo"
    }
]

Import a MappedIn venue as a site

Required permission: integrations:write (role SITE_MANAGER or higher)

Creates (or updates) a site with the venue's floors and walls.

Authorizations:
bearerAuth
path Parameters
venue_id
required
string

MappedIn venue ID.

Responses

Response samples

Content type
application/json
{
  • "api_key": "mik_xxxxxxxxxxxxxxxxxxxxxxxx",
  • "token": "eyJhbGciOi...",
  • "token_expiry": "2026-10-26T22:29:26+00:00",
  • "imports": [
    • {
      }
    ]
}

Disconnect an imported venue

Required permission: integrations:write (role SITE_MANAGER or higher)

Stops syncing the venue. The site is kept.

Authorizations:
bearerAuth
path Parameters
venue_id
required
string

MappedIn venue ID.

Responses

Response samples

Content type
application/json
null

Wirepas Backends

Forward mesh traffic from selected gateways to your own Wirepas backend (MQTT broker).

List Wirepas backends

Required permission: backends:read (role VIEWER or higher)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "name": "string",
    • "config": {
      },
    • "certificates": { },
    • "devices": [
      ]
    }
]

Create a Wirepas backend

Required permission: backends:write (role ADMIN or higher)

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
required
object (Config)
host
required
string
port
required
integer
required
object (Config_WirepasConfig)
use_backend_api
boolean
username
string
password
string
Array of objects (Config_Endpoint)
Array of objects (Config_Endpoint)
object (Certificates)
ca_cert
string
server_cert
string
private_key
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "config": {
    • "host": "string",
    • "port": 0,
    • "use_backend_api": true,
    • "username": "string",
    • "password": "string",
    • "wirepas_config": {
      },
    • "upstream_eps": [
      ],
    • "downstream_eps": [
      ]
    },
  • "certificates": {
    • "ca_cert": "string",
    • "server_cert": "string",
    • "private_key": "string"
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "config": {
    • "host": "string",
    • "port": 0,
    • "username": "string",
    • "password": "string",
    • "use_backend_api": true,
    • "wirepas_config": { },
    • "upstream_eps": [
      ],
    • "downstream_eps": [
      ]
    },
  • "certificates": { },
  • "devices": [
    • {
      }
    ]
}

Get a Wirepas backend

Required permission: backends:read (role VIEWER or higher)

Authorizations:
bearerAuth
path Parameters
backend_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "config": {
    • "host": "string",
    • "port": 0,
    • "username": "string",
    • "password": "string",
    • "use_backend_api": true,
    • "wirepas_config": { },
    • "upstream_eps": [
      ],
    • "downstream_eps": [
      ]
    },
  • "certificates": { },
  • "devices": [
    • {
      }
    ]
}

Update a Wirepas backend

Required permission: backends:write (role ADMIN or higher)

Connected gateways are sent the new configuration.

Authorizations:
bearerAuth
path Parameters
backend_id
required
string
Request Body schema: application/json
required
name
string
object (Config)
host
required
string
port
required
integer
required
object (Config_WirepasConfig)
use_backend_api
boolean
username
string
password
string
Array of objects (Config_Endpoint)
Array of objects (Config_Endpoint)
object (Certificates)
ca_cert
string
server_cert
string
private_key
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "config": {
    • "host": "string",
    • "port": 0,
    • "use_backend_api": true,
    • "username": "string",
    • "password": "string",
    • "wirepas_config": {
      },
    • "upstream_eps": [
      ],
    • "downstream_eps": [
      ]
    },
  • "certificates": {
    • "ca_cert": "string",
    • "server_cert": "string",
    • "private_key": "string"
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "config": {
    • "host": "string",
    • "port": 0,
    • "username": "string",
    • "password": "string",
    • "use_backend_api": true,
    • "wirepas_config": { },
    • "upstream_eps": [
      ],
    • "downstream_eps": [
      ]
    },
  • "certificates": { },
  • "devices": [
    • {
      }
    ]
}

Delete a Wirepas backend

Required permission: backends:delete (role ADMIN or higher)

Authorizations:
bearerAuth
path Parameters
backend_id
required
string

Responses

Response samples

Content type
application/json
null

Add a gateway to a backend

Required permission: backends:write (role ADMIN or higher)

Only argo gateways can forward to a backend.

Authorizations:
bearerAuth
path Parameters
backend_id
required
string
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "config": {
    • "host": "string",
    • "port": 0,
    • "username": "string",
    • "password": "string",
    • "use_backend_api": true,
    • "wirepas_config": { },
    • "upstream_eps": [
      ],
    • "downstream_eps": [
      ]
    },
  • "certificates": { },
  • "devices": [
    • {
      }
    ]
}

Remove a gateway from a backend

Required permission: backends:write (role ADMIN or higher)

Authorizations:
bearerAuth
path Parameters
backend_id
required
string
device_id
required
string
Example: 00000

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "config": {
    • "host": "string",
    • "port": 0,
    • "username": "string",
    • "password": "string",
    • "use_backend_api": true,
    • "wirepas_config": { },
    • "upstream_eps": [
      ],
    • "downstream_eps": [
      ]
    },
  • "certificates": { },
  • "devices": [
    • {
      }
    ]
}

Organization

The organization (customer account) itself and any child organizations.

Get your organization

Required permission: organization:read (role VIEWER or higher)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "customer_id": "swJd",
  • "name": "Velavu Sandbox",
  • "settings": {
    • "rules": {
      }
    },
  • "meta": {
    • "assets": {
      },
    • "devices": {
      }
    },
  • "allow_child_orgs": true
}

Update your organization

Required permission: organization:write (role ADMIN or higher)

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
string
object
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "name": "Velavu Sandbox"
}

Response samples

Content type
application/json
{
  • "customer_id": "swJd",
  • "name": "Velavu Sandbox",
  • "settings": {
    • "rules": {
      }
    },
  • "meta": {
    • "assets": {
      },
    • "devices": {
      }
    },
  • "allow_child_orgs": true
}

List child organizations

Required permission: organization:read (role VIEWER or higher)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "customer_id": "swJd",
    • "name": "Velavu Sandbox",
    • "settings": {
      },
    • "meta": {
      },
    • "allow_child_orgs": true
    }
]

Create a child organization

Required permission: organization:write (role ADMIN or higher)

Creates an organization under yours, with the given admin user, default rules and your device models. Requires allow_child_orgs on your organization.

The response body is currently null; list child organizations to get the new one.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
admin_name
required
string
admin_email
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Acme Hospital",
  • "admin_name": "Jane Smith",
  • "admin_email": "jane@example.com"
}

Response samples

Content type
application/json
null

Delete a child organization

Required permission: organization:write (role ADMIN or higher)

The child organization must have no devices.

Authorizations:
bearerAuth
path Parameters
customer_id
required
string

The child organization's customer_id.

Responses

Response samples

Content type
application/json
null

Users

People with access to the organization. A user's ID is their email address.

List users

Required permission: users:read (role VIEWER or higher)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "email": "jane@example.com",
    • "name": "Jane Smith",
    • "role": "ADMIN",
    • "status": "CONFIRMED",
    • "settings": {
      },
    • "permissions": [
      ]
    }
]

Invite a user

Required permission: users:write (role SITE_MANAGER or higher)

Creates the user and emails them a temporary password. role defaults to ADMIN when omitted, so set it explicitly.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
email
required
string
role
string (Role)
Enum: "VIEWER" "OPERATOR" "SITE_MANAGER" "ADMIN"

Responses

Request samples

Content type
application/json
{
  • "name": "Jane Smith",
  • "email": "jane@example.com",
  • "role": "OPERATOR"
}

Response samples

Content type
application/json
{
  • "email": "jane@example.com",
  • "name": "Jane Smith",
  • "role": "ADMIN",
  • "status": "CONFIRMED",
  • "settings": {
    • "showWelcomeScreen": false
    },
  • "permissions": [
    • "alerts:delete",
    • "alerts:read",
    • "api-tokens:delete",
    • "api-tokens:read",
    • "api-tokens:write"
    ]
}

Get a user

Required permission: users:read (role VIEWER or higher)

Authorizations:
bearerAuth
path Parameters
email
required
string <email>
Example: jane@example.com

The user's email address (URL-encoded).

Responses

Response samples

Content type
application/json
{
  • "email": "jane@example.com",
  • "name": "Jane Smith",
  • "role": "ADMIN",
  • "status": "CONFIRMED",
  • "settings": {
    • "showWelcomeScreen": false
    },
  • "permissions": [
    • "alerts:delete",
    • "alerts:read",
    • "api-tokens:delete",
    • "api-tokens:read",
    • "api-tokens:write"
    ]
}

Update a user

Required permission: users:write or users:write-self (role VIEWER or higher)

Changes the fields you send. Changing role needs users:write; users with only users:write-self can update their own name and settings.

Authorizations:
bearerAuth
path Parameters
email
required
string <email>
Example: jane@example.com

The user's email address (URL-encoded).

Request Body schema: application/json
required
name
string
object

Free-form settings, replaced as a whole.

property name*
additional property
any
role
string (Role)
Enum: "VIEWER" "OPERATOR" "SITE_MANAGER" "ADMIN"

Responses

Request samples

Content type
application/json
{
  • "role": "SITE_MANAGER"
}

Response samples

Content type
application/json
{
  • "email": "jane@example.com",
  • "name": "Jane Smith",
  • "role": "ADMIN",
  • "status": "CONFIRMED",
  • "settings": {
    • "showWelcomeScreen": false
    },
  • "permissions": [
    • "alerts:delete",
    • "alerts:read",
    • "api-tokens:delete",
    • "api-tokens:read",
    • "api-tokens:write"
    ]
}

Delete a user

Required permission: users:delete (role SITE_MANAGER or higher)

Authorizations:
bearerAuth
path Parameters
email
required
string <email>
Example: jane@example.com

The user's email address (URL-encoded).

Responses

Response samples

Content type
application/json
null

Upload a profile picture

Required permission: users:write or users:write-self (role VIEWER or higher)

Authorizations:
bearerAuth
path Parameters
email
required
string <email>
Example: jane@example.com

The user's email address (URL-encoded).

Request Body schema: application/json
required
image
required
string^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-...

The image file, base64-encoded.

Responses

Request samples

Content type
application/json
{
  • "image": null
}

Response samples

Content type
application/json
{
  • "email": "jane@example.com",
  • "name": "Jane Smith",
  • "role": "ADMIN",
  • "status": "CONFIRMED",
  • "settings": {
    • "showWelcomeScreen": false
    },
  • "permissions": [
    • "alerts:delete",
    • "alerts:read",
    • "api-tokens:delete",
    • "api-tokens:read",
    • "api-tokens:write"
    ]
}

Delete the profile picture

Required permission: users:write or users:write-self (role VIEWER or higher)

Authorizations:
bearerAuth
path Parameters
email
required
string <email>
Example: jane@example.com

The user's email address (URL-encoded).

Responses

Response samples

Content type
application/json
null

API Tokens

Long-lived bearer tokens for server-to-server access.

List API tokens

Required permission: api-tokens:read (role ADMIN or higher)

Tokens newest first. The secret token value is not included.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "name": "string",
    • "role": "VIEWER",
    • "created": "2019-08-24T14:15:22Z",
    • "expiry": "2019-08-24T14:15:22Z",
    • "creator": "string"
    }
]

Create an API token

Required permission: api-tokens:write (role ADMIN or higher)

The response is the only time the secret token is returned. role defaults to ADMIN when omitted, so set it explicitly.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
role
string (Role)
Enum: "VIEWER" "OPERATOR" "SITE_MANAGER" "ADMIN"
expiry
string

When the token stops working (ISO 8601, in the future). Omit for a token that never expires.

Responses

Request samples

Content type
application/json
{
  • "name": "Warehouse integration",
  • "role": "VIEWER",
  • "expiry": "2027-10-26T00:00:00+00:00"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "role": "VIEWER",
  • "created": "2019-08-24T14:15:22Z",
  • "expiry": "2019-08-24T14:15:22Z",
  • "creator": "string",
  • "token": "string"
}

Revoke an API token

Required permission: api-tokens:delete (role ADMIN or higher)

Authorizations:
bearerAuth
path Parameters
token_id
required
string

Responses

Response samples

Content type
application/json
null

Event Stream

Client certificates for the MQTT event stream.

List MQTT client certificates

Required permission: mqtt:read (role VIEWER or higher)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "name": "string",
    • "created": "2019-08-24T14:15:22Z",
    • "creator": "string"
    }
]

Create an MQTT client certificate

Required permission: mqtt:write (role ADMIN or higher)

The response is the only time the certificate PEM and private key are returned.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Data warehouse"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "creator": "string",
  • "certificate_pem": "string",
  • "private_key": "string"
}

Revoke an MQTT client certificate

Required permission: mqtt:delete (role ADMIN or higher)

Authorizations:
bearerAuth
path Parameters
certificate_id
required
string

Responses

Response samples

Content type
application/json
null

Authorize a signed-in user for MQTT

Required permission: mqtt:authorize (role VIEWER or higher)

Lets a Cognito identity (a signed-in web app user) subscribe to the event stream over MQTT-over-WebSocket. API clients should use a certificate instead. PUT /mqttauth/{identity} is an older alias for this operation.

Authorizations:
bearerAuth
path Parameters
identity
required
string

Cognito identity ID of the signed-in user.

Responses

Device Models

Device models available to the organization, with images and default configuration.

List device models

Required permission: devices:read (role VIEWER or higher)

Device models enabled for your organization.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {}
]

Get a device model

Required permission: devices:read (role VIEWER or higher)

Authorizations:
bearerAuth
path Parameters
model_name
required
string
Example: Vesta

Device model name (URL-encoded).

Responses

Response samples

Content type
application/json
{}

Billing

Invoices for the organization's subscription.

List invoices

Required permission: billing:read (role ADMIN or higher)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "period_start": "2019-08-24T14:15:22Z",
    • "period_end": "2019-08-24T14:15:22Z",
    • "status": "string",
    • "total": 0,
    • "usage": [
      ],
    • "payment_url": "http://example.com",
    • "invoice_pdf": "http://example.com"
    }
]

Get the upcoming invoice

Required permission: billing:read (role ADMIN or higher)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "period_start": "2019-08-24T14:15:22Z",
  • "period_end": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "total": 0,
  • "usage": [
    • { }
    ],
  • "payment_url": "http://example.com",
  • "invoice_pdf": "http://example.com"
}