Havida Sensor API

Current and historical values

The service exposes the latest measurements, time-range history and open CSV export.

Customer isolation

A customer read token can only access locations registered to that customer.

HTTPS and Bearer tokens

All external requests use HTTPS. Tokens must be sent in the Authorization header.

Authentication

Include the customer-specific read token with every data request:

Authorization: Bearer CUSTOMER_ADMIN_READ_TOKEN

In the interactive API documentation, select Authorize and enter only the token value. Swagger adds the Bearer prefix automatically.

Do not place tokens in URLs, source code, screenshots, email, or support logs. Havida's global administration token is never distributed to customers.

Endpoints

Method	Path	Purpose	Authentication
GET	`/v1/measurements/latest`	All latest locations for the authenticated customer	Customer read token
GET	`/v1/measurements/latest?location_name=Fjord%20Site%20A`	Latest values for one location	Customer read token
GET	`/v1/measurements/history?from=...&to=...`	Historical batches for a time range of up to 31 days per request	Customer read token
GET	`/v1/measurements/export.csv?from=...&to=...`	Open CSV export of historical measurements	Customer read token
POST	`/v1/measurements`	Sensor-agent ingest; not intended for customer office systems	Location ingest token
GET	`/health`	API process health; contains no sensor values	None

Read example

curl

curl -sS \
  -H "Authorization: Bearer $READ_TOKEN" \
  "https://ingest.api.havida.no/v1/measurements/latest"

PowerShell

$headers = @{ Authorization = "Bearer $READ_TOKEN" }
Invoke-RestMethod `
  -Uri "https://ingest.api.havida.no/v1/measurements/latest" `
  -Headers $headers | ConvertTo-Json -Depth 10

Response example

{
  "customer_id": "example-aquaculture",
  "customer_name": "Example Aquaculture AS",
  "location_id": "fjord-site-a",
  "location_name": "Fjord Site A",
  "received_at": "2026-08-25T14:55:13.757175+02:00",
  "measurements": [
    {
      "customer_name": "Example Aquaculture AS",
      "location_name": "Fjord Site A",
      "camera_name": "Cage 5 Underwater Camera",
      "temperature_celsius": 8.4,
      "depth_meters": 6.2,
      "measured_at": "2026-08-25T12:55:13.651861Z"
    }
  ]
}

Fields and units

Field	Type	Description
`customer_id`	string	Stable technical customer identifier assigned by Havida
`customer_name`	string	Customer display name
`location_id`	string or null	Stable technical location identifier
`location_name`	string	Location display name
`site_id`	URN	Stable globally unique site identifier assigned by Havida
`device_id`	UUID URN	Stable globally unique logical camera/device identifier
`sensor_ids`	object	Stable UUID URNs for each sensor value supplied by the device
`camera_name`	string	Camera display name from the local Havida system; may contain the cage description
`temperature_celsius`	number or omitted	Temperature in degrees Celsius
`depth_meters`	number or omitted	Depth in metres
`oxygen_percent`	number or omitted	Oxygen value in percent when supplied by the sensor
`measured_at`	ISO 8601	Time the edge agent read the measurement, normally UTC with `Z`
`received_at`	ISO 8601	Time Havida Cloud accepted the batch, including timezone offset

Optional sensor fields are omitted when the local camera object does not provide a numeric value. API consumers must not assume that every camera provides every sensor type.

HTTP responses

`200`	Request completed
`202`	Measurement batch accepted
`401`	Missing or invalid Bearer token
`403`	Token is not authorised for the requested customer or location
`404`	No data received for the requested location
`422`	Invalid request or missing filter
`503`	Customer registry unavailable

Operational behaviour

Measurements are normally refreshed every 10 seconds.
Measurements are stored persistently for historical retrieval and export.
API restarts do not remove historical or latest values.
Clients should use the timestamps to determine measurement freshness.
Token rotation supports an overlap period so clients can migrate without downtime.
Read, export and administrative operations are written to a security audit log without storing bearer tokens.