Guide

Deployments, Sites & Alerts

Beyond raw device data, the Bluesonde API exposes higher-level structures for organizing and monitoring your fleet: deployments, sites, and alerts. These endpoints are read-only. You create and manage deployments, sites, and alert rules from the Bluesonde Dashboard, and the API lets you read them and pull their data.

Deployments

A deployment is a time-bounded grouping of devices for analysis. It represents a period during which a set of devices was collecting data together, for example a single field campaign.

List and fetch deployments:

GET https://bluesonde.io/api/v0/deployments
GET https://bluesonde.io/api/v0/deployments/{deploymentId}
GET https://bluesonde.io/api/v0/deployments/{deploymentId}/summary

The list endpoint accepts optional filters:

  • status: active or completed

  • startAfter: only deployments starting at or after this ISO-8601 timestamp

  • endBefore: only deployments ending at or before this ISO-8601 timestamp

The summary endpoint returns the deployment along with aggregated counts of devices and observations over the deployment window.

See which devices are part of a deployment:

GET https://bluesonde.io/api/v0/deployments/{deploymentId}/devices

Reading deployment observations

There are three ways to consume the observations produced by a deployment's devices, depending on the shape you need:

GET https://bluesonde.io/api/v0/deployments/{deploymentId}/observations
GET https://bluesonde.io/api/v0/deployments/{deploymentId}/observation-table
GET https://bluesonde.io/api/v0/deployments/{deploymentId}/export

  • observations returns a flat list of observations from attached devices within the deployment window.

  • observation-table returns the same data pivoted into a table, with one column per datastream (a device, sensor, and observed property combination) and one row per timestamp. This is convenient for spreadsheets and side-by-side comparison.

  • export returns a ZIP archive with one folder per device. Each folder contains an observations.csv and a locations.csv.

All three accept optional start and end query parameters (ISO-8601) to narrow the time window. By default they cover the full deployment window.

Sites

A site is a stable geographic anchor that deployments attach to. Where a device moves and a deployment is time-bounded, a site is a fixed, named location you return to across campaigns.

GET https://bluesonde.io/api/v0/sites
GET https://bluesonde.io/api/v0/sites/{siteId}
GET https://bluesonde.io/api/v0/sites/{siteId}/deployments

The list endpoint accepts an optional nameLike filter for searching by name. The site deployments endpoint accepts the same status filter (active or completed) as the deployments list.

GET /sites returns more than the sites your organization owns. It also includes sites made visible to you through an active share on a deployment anchored to them. This lets collaborators see the anchor location for data that has been shared with them.

Alerts

Alerts are raised against deployments when a device reading crosses a configured threshold or a geofence boundary. Alert rules are configured per deployment from the dashboard, and the API lets you read both the rules and the alerts they produce.

Read the observed-property threshold rules configured on a deployment:

GET https://bluesonde.io/api/v0/deployments/{deploymentId}/alert-rules

Read alerts, either organization-wide or scoped to a deployment:

GET https://bluesonde.io/api/v0/alerts
GET https://bluesonde.io/api/v0/deployments/{deploymentId}/alerts
GET https://bluesonde.io/api/v0/deployments/{deploymentId}/alerts/{alertId}

The alert-listing endpoints accept an optional status filter (triggered, acknowledged, or resolved):

  • GET /alerts
  • GET /deployments/{deploymentId}/alerts

To fetch every unacknowledged alert across your whole organization in a single call, use:

GET https://bluesonde.io/api/v0/alerts?status=triggered

Rows from the organization-wide endpoint come pre-hydrated with deploymentName and observedPropertyName, so you can render them without additional lookups. The single-alert endpoint returns an AlertDetail that includes the contributing readings and the alert's event history.

Reacting to alerts

Alert state changes are also delivered as webhooks: deployment.alert.triggered, deployment.alert.escalated, deployment.alert.acknowledged, and deployment.alert.resolved. Rather than polling GET /alerts, the recommended pattern is to subscribe to these events and pull the full AlertDetail or deployment data when an event fires. See the Webhooks guide to set this up.

Deployments, sites, and alert rules are managed from the Bluesonde Dashboard. The API surface for them is read-only: you cannot create deployments, move sites, edit alert rules, or acknowledge alerts through the API.

Previous
Data
Next
Webhooks