Velavu API (2026-10)
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.
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.
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.
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 | ✓ | ✓ | ✓ |
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 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. |
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.