The Bluesonde API is centered around a few core concepts: devices, sensors, observed properties, and observations. Together, these types describe what a buoy is, what hardware it carries, what it measures, and the time-series data it produces.

Devices

A device represents a physical Bluesonde unit. Devices are the top-level resource you’ll work with most often.

Depending on the endpoint, devices appear in two common forms:

• Device Summary: a lightweight view of a device, including its ID, name, serial number, last known location, and current status.

• Device Manifest: a structural description of a device, including the sensors attached to it.

A device summary is useful when listing fleets or building dashboards. A device manifest is useful when you need to understand what measurements a device is capable of producing.

Sensors and Sensor Types

A sensor is an instrument attached to a device. In manifests, each sensor includes:

• its own ID and name

• the sensor type it belongs to

• the observed properties it can measure

• the units used for those measurements

A Sensor Type describes a class of hardware rather than one installed sensor. Sensor type records include metadata such as:

• name

• manufacturer

• datasheet URL

• the observed properties and units recorded by that sensor type

Use sensor types when you want to understand capabilities across hardware models. Use sensor manifests when you want to inspect what is installed on a specific device.

Observed Properties

An observed property describes what is being measured, such as temperature, conductivity, or another environmental value.

Observed properties include:

• an ID

• a name

• an optional description

• an optional definition

Observed properties are intentionally separate from sensors and devices. This lets the API express that multiple sensor types or datastreams may measure the same conceptual thing.

Units of Measurement

A unit of measurement describes how an observed property is expressed, such as degrees Celsius or practical salinity units.

Units include:

• an ID

• a name

• an optional symbol

• an optional description

In the API, observed properties are paired with units so that consumers can safely label charts, exports, and derived analytics.

Locations

A location represents where a device was at a point in time.

Locations contain:

• latitude

• longitude

• timestamp

Device summaries may include a lastKnownLocation value when location history is available.

Device Status

A device represents the current health or operating state of a device.

Statuses include a high-level status value plus optional supporting measurements and reasons. The status level can be:

• ok

• warning

• critical

• offline

• unknown

A status may also include one or more reasons, such as:

• low_voltage

• high_current

• high_humidity

• high_temp

• low_temp

• offline

Additional fields like voltage, current, humidity, temperature bounds, latest observation time, and evaluation time can help explain why a device is in a given state.

Observations

An observation is a single measured value at a particular timestamp.

Observations include:

• value: the measured reading

• timestamp: when the reading was recorded

• metadata: optional additional context about the reading

Observations are the fundamental time-series records returned by raw and processed observation endpoints.

Error responses

Most endpoints may also return structured error objects. Common error types include:

• UNAUTHORIZED

• VALIDATION_ERROR

• NOT_FOUND

• INTERNAL_SERVER_ERROR

Error responses typically include a human-readable message, an error code, and sometimes a traceId for debugging. Validation errors may also include field-specific details.

Putting it together

In practice, most integrations follow this mental model:

• A device is the buoy you are interacting with.

• A device has one or more sensors.

• Each sensor can measure one or more observer properties in specific units.

• Measurements arrive as timestamped observations.